Configuring and troubleshooting SPNego -- Part 1

In the last few weeks I was asked by several customers and here on SDN about configuring and troubleshooting the SPNego-login module for the J2EE Engine. So I decided to write my first blog. Actually, since there are already several blogs available that deal with setting up SPNego I am planning to write at least three parts about SPNego

• the first part will be about the configuration of SPNego and some general tips (this was dealt before quite some time, but I think it belongs to a complete troubleshooting series)
• the second part will deal with common problems and some tools to figure out what went wrong
• the third part will deal with a more detailed troubleshooting which you might find helpful when you were not able to solve the problem with the tools from part two

Even if you are not able to solve the problem with these three blogs, I hope to be able to shed some light on what is going on. And the logs and information you will collect here will most certainly help speed up messages you might have to create.

Documentation

First of all let me say that I think the documentation about the SPNego login module is rather good. I have been working on SPNego ever since it was first developed for a customer project at SAP. From that time (of course updated since then) is the documentation you can find here on help.sap.com.
But for several months now the SPNego Wizard is available which made configuring SPNego much easier. Instead of working on several sections in the Visual Admin, on files with a text editor and so on you can use a simple web based wizard -- and are (hopefully) done within about 30 minutes. I would always recommend to use the wizard and this is what this first part is all about. Of course it is not always that simple – I had plenty of installations where something did not work right away and then you have to troubleshoot.

SPNego Wizard

Take a look at Note 994791 - SPNego Wizard.
Here you can download the SPNego Wizard (if it is not already contained with your J2EE installation). There is also a ZIP file I strongly recommend containing videos about the installation. It is fast, but with the help of the pause button of your video-player you can see everything you need to know. Also contained in the ZIP files is a PDF document and sample dataSourceConfiguration files that you can use to configure your UME to connect to your LDAP directory.
[if you are using Sun JDK for your J2EE engine, please make sure that you are using a JDK with 1.4.2_13 and not _14, _15 or _16. Unfortunately all these versions contain a bug that fails Kerberos to work, see Note 1057474 - NullPointerException in KRB5LoginMoule]

Create SPNego Service User

The first step is to configure a service user in your LDAP directory. For my screenshots I used a J2EE engine that I (will) attached to a Microsoft ADS.
Create a user in the ADS and make sure that the properties
* Password never expires
* Use DES encryption types for this account
are set.

Now set the service principal names (SPN) for this user. The SPN has to be every URL / DNS-Alias you are going to use to access the J2EE Engine -- and of course the fully qualified computer name has also to be created. Simply repeat the steps
setspn -A HTTP/servername username

for each URL. You can do a quick check via setspn –L to see if your settings were successful (all entered SPNs should be returned)

Connect the UME

Then you have to connect the usermanagement engine of the J2EE engine to the ADS. In order to do this, upload the dataSourceConfiguration file attached to the Note via the configtool [click on Browser, select the file and click on Upload]:

Then select it from the drop down list and enter all the data required.

Now you can click on Browse to select the User and the Group path where your users and groups are stored in the LDAP directory:

Make sure to test the connection and the authentication.

After that restart the J2EE Engine.

Run the wizard

Now you are all set to start the SPNego Wizard. Simply open the URL http://servername:port/spnego

The first screen is just to remind you of what you have to do as a prerequisite.

Now you have to tell the wizard something about your Kerberos setup and the LDAP attached.

(you can use either Enter Principal or Retrieve Principal. Both options should work just fine)

In the next step you tell the wizard how the lookup will work. The J2EE Engine gets the Kerberos ticket which usually is the SAMAccountName and the Domain. So in order to find the user in the UME the best way is to split the name and first search for the first part (kerbprefix, e.g. SAMAccountName) and if the result is not unique the second part (KPN-Suffix, domainname). Of course you can also try the other options simple and basic, but I would first go with prefixbased.

The first thing I would do is select the "Create new" option in order to create a new template that can be used more flexible (e.g. if you want to use SPNego with the Portal and Duet). So create a new template "spnego" (this is the default option anyway), and if you want to you can now deselect Enable Basic Password Fallback (but make sure that "Enable SSO with SAP Logon Ticket" *is* enabled.

And we are done.

Now restart the J2EE Engine.

Assign the template to the components

The final step is to assign the template you created to the login component you are using (for the Portal usually this is the ticket stack, for Duet it is the osp_TicketIssuserComponent):

Test it…

OK. If you are lucky :-) everything is fine. When you try to test your configuration make sure to do this from another computer (and not the server) and using the fully qualified domain name. If it is not working then maybe my next blog will be of use.

Stay tuned…