Single Sign-On for Java with SPNego

Do I Need to License SAP NetWeaver Single-Sign (NWSSO)?

That depends.

If you are planning to implement an SSO scenario involving your ABAP system, then yes, you will need to implement NWSSO as described in the many blogs and documents over in the SAP Single Sign-On space. This is a versatile tool that can help you implement SSO for SAPGUI, for WebGUI, and for the various web-based applications you might run on an ABAP system (such as SRM, for instance).

NWSSO can also provide your SSO solution for your Java-based systems, such as Enterprise Portal, but it’s not absolutely necessary for this scenario.

That’s where this blog comes in. I’m going to describe for you how to configure Single Sign-On to your Enterprise Portal for your Windows domain-based users using only the tools that come with a NetWeaver Java 7.x system and Active Directory (and a typical JRE, such as that supplied by Oracle). No extra product required. The method described should work on AS Java 7.00 from sp23, 7.01 from sp8, and 7.02 from sp6. It will also work on 7.1 and higher versions with some slight adaptation (mainly the use of NetWeaver Administrator instead of Visual Administrator). If you are still working with an AS Java below the above-mentioned support pack levels, then there is an add-on available to enable this functionality (see Note 1457499).

In other words, no, for SSO from Windows domains to Enterprise Portal, you do not need NWSSO.

What is SPNego?

SPNego is Simple and Protected Negotiation Mechanism. It has been around since the days of Microsoft Internet Explorer 5.01 and Internet Information Services 5.0, and today it is supported by Firefox and Chrome as well as IE11. It is a “pseudo” implementation of GSSAPI, or Generic Security Services Application Programming Interface. While it used to depend upon NTLM, an older Microsoft-specific authentication protocol, today it mostly relies upon Kerberos, a standard ticket-based protocol utilized by Windows and UNIX systems alike.

SAP NetWeaver Java can utilize most Kerberos Key Distribution Centers, but in this blog we will focus on what is arguably the most common: Microsoft Active Directory.

What are the Client Browser Requirements?

Internet Explorer

For the most part, the default setup will work:

• Integrated Windows Authentication must be enabled:
  • Tools… Internet Options… Advanced… Security… Enable Integrated Windows Authentication
    • This is usually enabled by default.
• Automatic Logon must be enabled for the Local Intranet Security Zone:
  • Tools… Internet Options… Security… Local intranet… Custom level… User Authentication… Automatic logon only in Intranet zone
    • This setting is enabled with the Medium-low security level, which is the default level for the Local intranet zone.
• If you use a proxy server for web browsing, it must be bypassed for local addresses:
  • Tools… Internet Options… Connections… LAN settings… Proxy server:
    • Either Use a proxy server for your LAN must be UNchecked, or if it is checked, then Bypass proxy server for local addresses must be checked.
• Your Java system must be included in the Local Intranet security zone:
  • Tools… Internet Options… Security… Local intranet… Sites:
    • Various options: typically, Automatically detect intranet network is checked, and beneath that the other options as well (Include all local (intranet) sites not listed in other zones, Include all sites that bypass the proxy server, and Include all network paths (UNCs)). Alternatively, or in addition, in Advanced you can specifically add your Java system to the zone, or you can add a range of IP addresses or your local domain (*.domain.com). This is often controlled via Group Policy.
    • You can confirm if your Java system is properly showing up in the right zone by right-clicking on the login page and choosing Properties. There you should see Zone: Local intranet | Protected Mode: Off.

Firefox

In the address bar enter about:config to see the various configuration settings. Filter them by typing negotiate in the search bar, then modify network.negotiate-auth.delegation-uris to add the URL of your Java system. Do the same for network.negotiate-auth.trusted-uris.

Again, your Java system must be included in the list of sites that bypass your proxy, if used.

Active Directory Service User

If you’re the Basis Administrator, chances are you are not also the Active Directory Administrator. So, you may be thinking to yourself, I’ll never convince them to make changes to Active Directory if this requires something like a schema extension…

Well, fear not! No schema extension or heavy modification of AD is required. Indeed, all you require is a very simple service user account, and the configuration of an SPN, or Service Principal Name, for that service user.

So, the first decision (or negotiation) is to determine the name of the service user. My recommendation is to choose something along the lines of SAPSSO-<SID>, i.e. if your Java System ID is PLQ, then your service user will be SAPSSO-PLQ. However, the naming convention is not a hard rule, unlike the service accounts used for running and managing the SAP system itself, so if your organization’s convention for service accounts requires something different, that is fine.

The service user does not require any special privileges or permissions, but it does require these two account options:

• Password never expires must be CHECKED;
• Use Kerberos DES encryption types for this account must be UNCHECKED.
  • Note that older versions of the SPNego implementation in SAP Java actually called for DES to be enabled, but that is no longer true. DES is an older encryption algorithm that is no longer considered secure, and thus it is better to ensure that it is not enabled here.

Service Principal Name

The small bit of extra configuration that must be done for the service user is setup of the Service Principal Name, or SPN. This can be done with Microsoft’s ADSI Edit tool, or via the command-line from any domain member Windows workstation. The SPN must follow the format of:

HTTP/<FQDN of Java host>

In other words, if your Java system is portal.domain.com (highly original, I know), then the SPN is HTTP/portal.domain.com.

To configure the SPN from the command-line, type (or have your AD administrator set):

setspn -a HTTP/<FQDN> <service-user>

In our above example, that would be “setspn -a HTTP/portal.domain.com SAPSSO-PLQ”.

If your portal or Java system has multiple DNS aliases, i.e. it’s known by a “technical” hostname such as “s1x37bz.domain.com” as well as a “friendly” name like “portal.domain.com” then you must set both SPNs against the service user. It’s still just one service user, but the user will have two registered SPNs. Likewise, if your portal system has multiple hosts, for load-balancing purposes for instance, plus a web dispatcher to provide the load balancing, then you must set an SPN against the service user for each host.

Also, even though you are surely using HTTPS and not HTTP to connect to your portal, you will specify HTTP in the SPN.

What’s important here is that each SPN must be uniquely assigned to only a single service user, but each service user may have multiple SPNs.

Check SPN Configuration

This part you can do yourself, even if you are not the AD administrator, so you can confirm that the SPN is correctly setup and unique. From a command-line on your workstation type:

ldifde -r serviceprincipalname=HTTP/<FQDN> -f out.txt

Remember, put in the actual host and domain name, i.e., portal.domain.com in place of <FQDN>. If all goes well, you should see messages something like:

Connecting to “<domain-controller.domain.com>”

Logging in as current user using SSPI

Exporting directory to file out.txt

Searching for entries…

Writing out entries.

1 entries exported

The key here is that 1 entries exported (grammar rules notwithstanding). There can be only one! Now, look in the current folder (wherever you were in command prompt when you ran ldifde) for out.txt and examine the contents. You will see a bunch of information, most of which you can safely ignore. The key lines you are looking for, close to the end, are:

userPrincipalName: SAPSSO-PLQ@domain.com (or whatever the correct service user account name is plus your domain)

servicePrincipalName: HTTP/<unfriendly-hostname.domain.com>

servicePrincipalName: HTTP/<friendly-hostname-alias.domain.com>

etc for however many SPNs you configured for the user (perhaps only one).

Encryption Keytab

Now that you have a service user, you must create a keytab file that contains the encryption key required to decrypt the Kerberos tokens supplied by the browser to the AS Java. The easy way to do this is with the JRE you probabably have installed on your workstation. Any Java 1.6 or higher JRE should do (note, this will definitely not work with JRE 1.4, even though the KTAB utility exists; I tried).

Open a command prompt and navigate to the bin folder of your JRE, i.e. C:\Program Files (x86)\Java\jre1.8.0_65\bin, etc. From there, type the following command:

ktab -a <service-user>@<domain> -k ssokeytab<sid>

So, if your domain is mycompany.com and your service user is SAPSSO-PLQ (because your Java SID is PLQ), then you would type ktab -a SAPSSO-PLQ@mycompany.com -k ssokeytabplq.

You will be asked to enter the password for the service account. Be careful, as ktab does not validate the password with Active Directory; it just uses it to create an encryption key. If you type in the wrong password key, the encryption key won’t work.

Move or copy ssokeytab<sid> to an appropriate location other than your JRE program folder.

SPNego Wizard

In your web browser, logon to your AS Java with the following URL. Make sure your user account has administrative privileges on the Java system.

https://<host.domain.com>:<port>/spnego

For example, the URL might be https://portal.mycompany.com:50001/spnego. This launches the SPNego Wizard.

Note, if your system is NetWeaver 7.1 or higher, you can access the wizard from NetWeaver Administrator via the path Configuration -> Security -> Authentication and Single Sign-On and then choose the SPNEGO tab. A few of the steps are different in a very minor way from the below, but it is essentially the same after this and you should be able to follow along with these instructions.

You will see a list of Kerberos Realms configured for access. Assuming this is the first time you’ve used the wizard, there won’t be any.

• Click Add.

You will see a New Realm pop-up. In the Name field enter the name of your realm. Oh, and if you aren’t sure what a realm really is or what the name should be… it’s the same as your Active Directory domain, i.e. mycompany.com. You can enter anything you like in the Description field or just leave it blank. Click OK.

Now your list of realms includes the one you just created, but it’s not yet enabled and it doesn’t have any details.

• With your new realm selected, click Edit.

In the Details of realm section below, there are two tabs, User Mapping and Keys. In the User Mapping tab, select the following:

• User Mapping
  • Mapping Mode = Principal only
  • Source = Logon ID

One note here: this mode assumes that usernames for your Portal users match their usernames in Active Directory. If you are using AD as an LDAP source for users, that is probably the case. If you are using your ABAP backend as the source for users, you may have some mismatches. At a later time I will follow up with a blog about how you can set up SSO to work for mismatched usernames as well, but for now we are going to assume all usernames match.

Second note: this works just fine if you are using your ABAP system as the user source; using LDAP for your users is not a requirement.

• Now select the Keys tab and click on Add. The Add Keys dialog will pop up.
• Click Browse and browse to the ssokeytab<sid> keytab file you created in the Encryption Keytab step.
• Click Import.

In the Add Keys dialog you should now see one or more keys displayed in a list (probably just one, but if you are enabling other encryption protocols besides RC4, you might see a couple). You’ll also notice that your AD service user is listed in the Principal field. Ensure the Selected checkbox is checked for all keys in the list, and click OK.

• You just need to Enable the realm and Save it.

When you’re done the Status field should show a green light. You’re done with the wizard.

Authentication Stack

If you are on NetWeaver 7.1 or higher, you can remain in the NetWeaver Administrator for this next step. You just need to click over to the Authentication tab after completing the SPNEGO tab.

If you are on NetWeaver 7.0x, you’ll need to access your server console and start up Visual Administrator.

• Navigate to Cluster -> Server 0 -> Services -> Security Provider.
• Under Runtime -> Policy Configurations -> Components select the ticket component, then click the Edit mode button.

If you see a Login Module called SPNEGOLoginModule (with capital letters just like that), remove it (select and click Remove at the bottom of the screen). That is an out-of-date module. Most likely, however, you won’t see this here.

Most likely you will see three login modules as shown in the screenshot above. You will leave these three and add to them (and potentially make some minor modifications to options).

• At the bottom of the screen, click Add New. In the Available Login Modules popup dialog, scroll down through the list and select SPNegoLoginModule (notice how the capitalization is different from the out-of-date module we talked about above). Click OK.

• Click Add New again and this time select and add CreateTicketLoginModule (yes, I know you have one in there of this name already; you need two of them).

Your stack now should have five login modules:

• com.sap.security.core.server.jaas.EvaluateTicketLoginModule
• BasicPasswordLoginModule
• com.sap.security.core.server.jaas.CreateTicketLoginModule
• SPNegoLoginModule
• CreateTicketLoginModule

We need to rearrange their order and adjust their flags, and possibly options.

• Select SPNegoLoginModule and click Modify at the bottom. The Edit Login Module dialog should pop up.
• Change Position to 2 and change Flag to Optional. Click OK.

• Select CreateTicketLoginModule (the one you just added, at the bottom of the list) and Modify.
• Change Position to 3. The Flag should already be Sufficient, but if not, adjust it.
• Under Options, type ume.configuration.active into the Name field, and true into the Value field. Click OK.

You’ll note that your new CreateTicketLoginModule just gained a prefix of com.sap.security.core.server.jaas just like the other one already had.

• Select the other com.sap.security.core.server.jaas.CreateTicketLoginModule (the one that you didn’t just edit, and which should be at the end of the list) and click Modify.
• Change Flag to Required and click OK.

When you are done editing the authentication stack, it should look like this:

Make sure the modules appear in this order, and that their flags are set this way.

Login Modules and Flags

Ok, so that was a neat bit of work, but what does it all mean? What do the login modules do, and how do the flags influence things? And why do we need two CreateTicket login modules?

Login Module Order

The authentication stack represents an order of processing, and the flags represent decisions as to where the processing should go next based upon a pass or fail of the module, much like a workflow decision tree or program logic. When a user attempts to login to the AS Java, the modules are called in the order they appear in the stack.

1. EvaluateTicket
   1. Is the user coming to the system from another trusted SAP system, such as another Enterprise Portal, or perhaps from an external portal such as Sharepoint, and did that system pass an SSO2 login ticket with a valid SAP authentication? This is the same scenario you encounter when accessing reports or webdynpros, etc, in your backend system via an iFrame in your Portal, or when you access any other system in your landscape (SRM, perhaps) from your Portal. The Portal passes on your credentials to the next system so you don’t have to keep logging in each time you click a link in the Portal. These are the same SSO2 login tickets you have probably dealt with in the STRUSTSSO2 transaction in your ABAP system.
   2. If this is the case, then obviously we want the SSO2 login-ticket-based authentication to work silently in background without interrupting the user. Thus, we evaluate to see if there is such a ticket (and that it’s valid) first.
2. SPNego
   1. Assuming the user did not have an SAP-system-generated SSO2 login ticket (meaning this is probably first entry into the Portal), then we look to see if there is a valid Kerberos token indicating the user has already been authenticated by Active Directory. If there is, then we match that token against our Portal user store according to the rules we configured in the SPNego Wizard, and if there’s a match, we accept the token and authenticate the user. No login screen need be presented.
3. CreateTicket
   1. Once the user has been let in to the Portal, whether by existing SSO2 login ticket or by SPNego/Kerberos token, it is likely he/she will want to use resources from other systems that the Portal is a front end for, such as our ABAP system. Thus, we create an SSO2 login ticket for the user which will be passed on to downstream systems to use in their own EvaluateTicketLoginModule.
4. BasicPassword
   1. On the other hand, if there was not a valid SSO2 or SPNego ticket, then we want to give our user an opportunity to type in a username and password in the old-fashioned way. That’s what this login module does.
5. CreateTicket
   1. Again, if our user logged in with username and password instead of a ticket/token, we still want to give him/her an SSO2 login ticket for the downstream systems. Thus, we need this module again.

I know what you’re thinking. Why don’t we just put CreateTicket in only once, at the very end? Well, I think you’ll understand the answer to this when we examine the Flags on the login modules.

Flags

We saw four different flags in use:

1. Sufficient
   1. If the login module succeeds, authenticate the user and exit processing of the stack here. If it fails, proceed to the next item in the stack. However, the user can still be authenticated by a later module in the stack.
2. Optional
   1. Whether the login module succeeds or fails, continue processing with the next item in the stack. If successful, the user is at this point authenticated even though we’re still processing, whereas if it fails, the user can still be authenticated by a later module.
3. Requisite
   1. If the login module succeeds, authenticate the user and proceed to the next item in the stack (just like Optional). If it fails, exit processing here, and the user is not authenticated. This is essentially the opposite of Sufficient.
4. Required
   1. Whether the login module succeeds or fails, continue processing with the next item in the stack. However, if it failed, there is no further chance to authenticate, regardless. This is similar to Optional except for that last point.

So, our processing flow is as follows:

1. EvaluateTicket, Sufficient
   1. If the user has a valid SSO2 ticket, authenticate the user and exit processing the stack. The user is logged in.
   2. If the user does not have an SSO2 ticket, proceed to the next item.
2. SPNego, Optional
   1. If the user has a matching Kerberos token, authenticate the user and proceed to the next item.
   2. If the user does not have a Kerberos token, proceed to the next item.
3. CreateTicket, Sufficient
   1. If the user is already authenticated by the previous module (SPNego), create an SSO2 ticket and exit processing the stack. The user is logged in.
   2. If the user did not authenticate via SPNego, do not create an SSO2 ticket, and proceed to the next item.
4. BasicPassword, Requisite
   1. If the user enters a valid username and password, authenticate the user and proceed to the next item.
   2. If the user’s username or password is invalid, exit processing the stack. The user is not logged in (and gets an error and remains on the login screen).
5. CreateTicket, Required
   1. If the user is already authenticated by the previous module (BasicPassword), create an SSO2 ticket and proceed with the next item. This is the last item, however, so the user is logged in.
   2. If the user is not yet authenticated, they won’t have reached this step. However, if that did happen somehow, no SSO2 ticket would be created, and although processing could in theory proceed to a later step (if there was one), because of the Required flag no further step could authenticate the user. They’re done at this point.

For more details about authentication stack processing, see the SAP Help at Login Module Stacks – User Authentication and Single Sign-On – SAP Library.

Logoff Redirect URL

At this point your Single Sign-On should be working. However, there is one additional configuration item you should attend to if you don’t want to annoy both users and system administrators, and this is the Logoff Redirect URL.

By default (meaning if this parameter is not set), when a user logs out of the AS Java they are sent to the login screen. Normally there is nothing wrong with that, but if SSO is active (and if you’ve been following along, it is now in your system), what do you think happens when the user clicks that Logoff button and is sent to the login page?

That’s right. SSO logs them right back in again. It’s almost like an endless loop. The Logoff button essentially does nothing.

This is very easy to change, but the unfortunate point is that this change, believe it or not, requires a restart of the Java stack. That’s right, everything you’ve done up to now took effect immediately, with no service interruption — you could have turned all this on during business hours, even — but for this last little piece of configuration you’ll need to schedule a brief downtime.

So, let’s get to it. You can do this in either the Config Tool or the Visual Administrator, but you’re already in Visual Administrator, so we’ll do it from there. The key is to make sure you are updating the Global Configuration and not an individual server instance.

Side note: the configuration of the authentication stack in the Security Provider Service replicates to all server instances in the cluster. You don’t need to repeat these changes in each instance. However, the logoff redirect URL is server instance specific unless you make sure to edit the global configuration (or use the Config Tool).

• In Visual Administrator, select Global Configuration -> Server -> Services -> UME Provider.
  • If you prefer to use Config Tool instead, the path is cluster-data -> Global server configuration -> services -> com.sap.security.core.ume.service.
  • If you are using NetWeaver Administrator, the path is Configuration -> Infrastructure -> Java System Properties -> Services -> User Management Engine.
• Scroll to the property key ume.logoff.redirect.url and select it.
• In the Value field, enter the URL of the website you want to send users to (perhaps a corporate intranet homepage).
• Click Update.
• At the top of the list of properties, click Save Properties (the standard floppy disk icon).

A pop-up dialog will open asking Apply these changes to cluster elements? There will be a list of all the server instances, and by default they will all be checked. Almost certainly this is what you want to do, so click Yes.

Another pop-up will open warning you that Service UME Provider on Server x x_xxxxx is a core service. Restart of Server x x_xxxxx is needed for the properties changes to take effect. Click OK. The pop-up will repeat for each server instance you have, so click OK to all of them until there are no more.

Exit the Visual Administrator and restart the cluster (with SAPMMC).

What if I Need to Login as Different Users for Testing or Administration? (Bypass SSO)

Fear not! A simple addition to the login URL of your Portal will bypass the SPNego module, thus taking you straight to BasicPassword. Simply enter your URL as follows:

https://portal.domain.com/irj/portal?spnego=disabled

That’s it. You’ll go straight to the login page.

Further Information

• Note 1488409 (New SPNego Implementation) has the latest SPNego Configuration Guide as an attachment. Currently the latest one is dated 2011. There are also some links to further troubleshooting Notes.
• Note 968191 (SPNego: Central Note) has further links to troubleshooting Notes.

Do not be confused by Note 994791 (SPNego Wizard). That Note is for older support pack levels of the AS Java which do not already have the wizard incorporated, and it provides the wizard as a downloadable EAR fileto deploy on your system. You don’t need this unless you are actually using such an old system.