I have been wanting to blog about my SPNEGO install guide for a while but have been just a bit busy lately (my usual excuse). However, I just had to help a client setup SPNEGO for their IBM Connections environment so I decided the time for procrastination is over.
If you look at the IBM documentation, the process to create the SPNEGO keytab files and mapping the correct URLs and Fully Qualified Hostnames of servers to the AD account is rather onerous. IBM documentation will have you create separate keytab files for each url/FQHN that you want to include in the SPNEGO config and then merge them. For the normal user that is setting up SPNEGO for the fist time that is painful indeed and confusing. My process below does it all in one step (one step per URL/fqhn) and adds all the settings to ONE keytab file. I am usually done in 5 minutes and then create the config file using wsadmin commands and am up and running in SPNEGO in under an hour.
Note: all commands below have to happen ON AN AD DOMAIN CONTROLLER, running them on your workstation will not work.
Environment / Variables:
- SPNEGOAD account: SPNEGOAccount@DOMAIN.COM – domain\SPNEGOAccount
- Server FQHN: serverfqhn1.example.com, serverfqhn2.example.com, serverfqhn3.example.com, etc.
- Connections URL (c-record): connections.example.com
Check Current SPN mappings for SPNEGO AD Account:
- setspn -l SPNEGOAccount
Step 2: Add SPN mapping to SPNEGOAccount and create Keytab files
[setspn -s] or [setspn -a] could be used just to add/map the SPNs to the account, but this does not create the keytab files.
- setspn -s HTTP/servernew.example.com SPNEGOAccount
- setspn -s HTTP/newsite.example.com SPNEGOAccount
Run commands to create a SINGLE keytab file AND map accounts at the same time:
- ktpass -princ HTTPfirstname.lastname@example.org -ptype KRB5_NT_PRINCIPAL -mapUser SPNEGOAccount -mapOp set -pass password1A -in C:\Temp\KRB\krb5.keytab-out C:\Temp\KRB\krb5.keytab
- ktpass -princ HTTPemail@example.com -ptype KRB5_NT_PRINCIPAL -mapUser SPNEGOAccount -mapOp add -pass password1A -in C:\Temp\KRB\krb5.keytab -out C:\Temp\KRB\krb5.keytab
Note: the first command has the command [set], all the following commands (one for each url/fqhn you want to add) has the command [add]. If you do not use the [add] command, each of your subsequent commands will override your previous one, leaving your AD account with only one fqhn/URL mapped to it. THIS IS IMPORTANT!
Check whether the SPNS are all correct:
- setspn -l SPNEGOAccount
(get output and show it has mappings)
- ldifde -f c:\temp\new-output1.txt -r “(servicePrincipalName=HTTP/ serverfqhn1.example.com)”
- ldifde -f c:\temp\new-output2.txt -r “(servicePrincipalName=HTTP/connections.example.com)”
(Get output files and review)
Which URLs/c-records and server FQHNs to map:
I map EVERYTHING. The main reason is that often your C-record for the site (our example connections.example.com) will point to the fqhn of a server or a load balancing device. In that case you need BOTH of them mapped. I mal all webservers/HIS, WAS servers and (if existing) the LB address (this s usually overkill and not necessary … but paranoia pays off sometimes).
Depending you your AD forest, the above ktpass command might need the AD account your are mapping to either in the [ACCOUNTNAME@DOMAIN.COM] format or [DOMAIN\ACCOUNTNAME] format. You will see the error right away when you run it for the first time.
SPNEGO setting in WebSphere:
If you go by the IBM documentation (there is allot flying around) you will see they generally tell you to add the fqhn of the Deployment Manager as the HOSTNAME in SPNEGO. Keep in mind that works for them because generally they testers tend to work with single server test installs where ALL the systems run on one server and the Dmgr is also the HIS server and often they don’t bother to change the URL for the Connections setup. What you need in there is the C-Record your users will be putting into their browsers to get to Connections in in our example connections.example.com. Should the C-record point to the FQHN of a web server then you could input that address as well. That is why I generally map EVERYTHING, that way you have maximum flexibility should you need to finagle with your architecture and move functionality around.
Oops, you forgot something …
If you suddenly notice you have to add servers to the SPNEGO setup (maybe you are migrating) – DO NOT ADD MORE MAPPINGS TO THE SPNEGO AD ACCOUNT. That will invalidate the existing keytab files and you will have a n SSO outage. To add additional files you have to stop all WebSphere servers involved , add the mappings with the ktpass command using the [ADD] variable and use the existing keytab file from one of your WebSphere servers. Then recreate the config file using wsdmin and replace the old keytab files with the new one.