Download - Sp Ne Go Documentation
SPNego Configuration Guide
Dimitar Dimkin 2011 SAP AG
2011/SAP AG
Table of Contents
1. INTRODUCTION
2. MIGRATION
3. KDC CONFIGURATION
4. UME CONFIGURATION
5. BROWSER CONFIGURATION
6. ADDING KERBEROS REALMS
7. CONFIGURE THE USER MAPPING
8. CONFIGURE THE ENCRYPTION KEYS
9. ENABLE THE REALM
10. ADJUST THE AUTHENTICATION STACK
11. LEGACY MODE
2011/SAP AG
1. INTRODUCTION
The SAP NetWeaver Application Server (AS) Java supports Kerberos with Simple and Protected Negotiation
Mechanism (SPNego) enabling authentication with Web clients such as Web browsers. SPNego functions on the AS
Java engine are available with the JAAS login module SPNegoLoginModule. In addition, the use of SPNego
authentication is not tied to the specific operating system of the AS Java engine host.
SPNego does not provide transport layer security. We recommend that you use transport layer security
mechanisms, such as SSL, to increase security for the SPNego communication with the AS Java engine.
Integration
Kerberos authentication requires several systems in your landscape, which negotiate the outcome transparently to
the user:
Web client - The Web client requests a service or a resource from the AS Java engine and authenticates against the
Kerberos Key Distribution Center. For example, users use a Web browser for a Web client to access Web
applications running on the AS Java engine
Kerberos Key Distribution Center (KDC) - The SPNegoLoginModule uses the Single Sign-On (SSO)
authentication mechanism integrated in Microsoft Windows 2000 and higher operating systems. A Microsoft
Windows Domain Controller (DC) acts as a KDC enabling Windows Integrated Authentication in a Windows
Domain. It authenticates the user and grants a ticket that is used for the communication between the AS Java engine
and the user’s Web client
AS Java engine - The AS Java engine uses a proprietary API to acquire the negotiated security context from the
Kerberos ticket issuer, and uses the user management engine (UME) to retrieve the identity management
information for the authenticated user. The AS Java engine provides access to the services or resources requested by
the Web client
For information about the integration of non-Windows server components in the Microsoft
Kerberos Infrastructure, see the documents available from the Microsoft Developer Network
(MSDN) at http://msdn.microsoft.com
2011/SAP AG
2. MIGRATION
Note that this guide is relevant if your AS Java engine is on one of the following versions or above only (if the
version of the engine is lower, follow the configuration guide attached to SAP Note 994791):
SAP NetWeaver AS Java 2004 (6.40) SP27
SAP NetWeaver AS Java 2004S (7.00) SP23
SAP NetWeaver AS Java 2004S EhP1 (7.01) SP08
SAP NetWeaver AS Java 2004S EhP2 (7.02) SP06
Depending on the means by which the AS Java engine was installed, select one of the options below:
Fresh installation
In case you installed the AS Java engine from scratch, skip this chapter and go to Chapter 3.
Upgrade with no SPNego
In case the AS Java engine was upgraded from an older version and SPNego was never configured, skip this
chapter and go to Chapter 3.
Upgrade with the original SPNego
In case the AS Java engine was upgraded from an older version and the original SPNego was configured, meaning
you never used the add-on solution from SAP Note 1457499, follow the instructions in this section.
In order to finish the migration you need to perform several steps:
1. Open the SPNego wizard at http://<host>:<port>/spnego and log on with a user with administrator privileges
2. Hit the “Migrate” button that is displayed at the top of the page
3. SPNego should now work
Upgrade with the SPNego add-on
In case the AS Java engine was upgraded from an older version and the SPNego add-on from SAP Note 1457499
was configured, follow the instructions in this section.
Before the upgrade, you undeployed the add-on solution as described in the note. As a result the login module that
was used, SPNEGOLoginModule (note the capital letters) is no longer available. Yet the configuration is still available
and can be used. In order to finish the migration you need to perform several steps:
1. Log on to the Visual Administrator and navigate to ServerXXX -> Services -> Security Provider Service
2. Select the “ticket” template and remove the SPNEGOLoginModule (capital letters) if it is still there. Either
way, add the SPNegoLoginModule at the appropriate position and with the appropriate flag
3. You can modify any policy configuration in the same manner, depending on the specific applications you want
to have configured to work with SPNego
4. SPNego should now work
EvaluateTicketLoginModule SUFFICIENT
amet, consectetaur
adpisicing elit, sed
SPNegoLoginModule
CreateTicketLoginModule
BasicPasswordLoginModule
CreateTicketLoginModule
OPTIONAL
amet, consectetaur
adpisicing elit, sed
SUFFICIENT
amet, consectetaur
adpisicing elit, sed
REQUIRED
amet, consectetaur
adpisicing elit, sed
REQUIRED
amet, consectetaur
adpisicing elit, sed
A typical authentication stack that relies on SPNego
for initial authentication with a user name and
password combination as a fallback might look like
this
2011/SAP AG
3. KDC CONFIGURATION
The Kerberos authentication process uses a Key Distribution Center (KDC) to authenticate a client and to issue the
Kerberos Client/Server Session Ticket. The configuration steps are specific to the KDC that you use. For more
information, see the documentation provided by your KDC vendor. However, in general you need to configure a service
user.
Procedure
1. Create a service user to identify the AS Java instance on the KDC. Choose a naming convention to help you
identify such users with their corresponding AS Java instances. For example, you can name the user “j2ee-
<SID>-<host>” (where <SID> is the system ID of the instance and <host> is the host where it is running).
The service user represents an AS Java instance running on a specific host and must meet the following
requirements:
a. The password of the service user must never expire
b. Disable Data Encryption Standard (DES) support for this account by ensuring that the “Use DES
encryption” check is not selected on the user account
2. Register a Service Principal Name (SPN) for the fully qualified host name and each of the DNS aliases that
you use to access the AS Java engine
Example
The following example shows the configuration steps when the KDC is a Microsoft Windows 2000 Domain
Controller (DC) that uses an Active Directory Server (ADS) for a user store.
Assumptions
The Windows domain name is IT.CUSTOMER.DE
The fully qualified domain name (FQDN) of the AS Java engine host is hades.customer.de
The AS Java engine has an additional alias su3x24.customer.de
The AS Java engine instance is D21
Configuration steps on the ADS
1. Create a service user named “j2ee-d21-hades”
2. Select the “Password never expires” check on the user’s account
3. Make sure the “Use DES encryption” check on the user’s account is not selected
4. From the command line, execute the following commands in order to register Service Principal Names (SPNs)
for the AS Java engine host name and alias to the service user “j2ee-d21-hades”
setspn –a HTTP/hades.customer.de j2ee-d21-hades
setspn –a HTTP/su3x24.customer.de j2ee-d21-hades
Doing so registers both the host name and the alias as SPNs of the service user in the ADS
5. In order to check the configuration, execute the following command from the command line for every SPN
that you registered
ldifde –r serviceprincipalname=HTTP/hades.customer.de –f out.txt
ldifde –r serviceprincipalname=HTTP/su3x24.customer.de –f out2.txt
When using a reverse proxy or an application-level gateway to access the AS Java, add an SPN for
the physical host name and each DNS alias of the reverse proxy or application-level gateway. For
this scenario, the Web client procures a Kerberos ticket from the KDC for the reverse proxy or
application-level gateway host and not for the AS Java host
2011/SAP AG
Execute the command for every single SPN you registered to the service user and check the generated files.
The output of each invocation must be only one entry – the service user created earlier, in the example – j2ee-
d21-hades. In other words, all SPNs must be unique
2011/SAP AG
4. UME CONFIGURATION
Kerberos authentication enables you to choose one from the following mapping modes:
Mapping mode
User resolution
Principal only
The user is resolved only by the principal part of the Kerberos Principal Name (KPN). The principal token can be mapped to the logon ID, to the logon alias or to another UME attribute of the user
Principal@REALM The user is resolved by the full KPN as a single token. This token can be mapped to the logon ID, to the logon alias or to another UME attribute of the user
Principal and REALM
The user is resolved splitting the KPN into principal and realm tokens. In case the UME data source is ADS, the user mapping is automatic. Otherwise both tokens can be mapped to UME attributes of the user
If you map the Kerberos token to a UME attribute, you must ensure that the attribute exists and contains data. The
UME has a set of standard attributes, such as the e-mail address. If you use such an attribute, there is no need to modify
the UME configuration. Otherwise you must ensure that the attribute mapping exists. In all cases, the attribute(s) used
for resolving a user must be unique.
2011/SAP AG
5. BROWSER CONFIGURATION
Kerberos authentication is negotiated in the background between the client, the AS Java engine and the Kerberos
KDC. To authenticate a client request to the AS Java engine using Kerberos, you also have to adjust the client
configuration. Below are the steps you need to follow in order to configure the client browser
Procedure for Microsoft Internet Explorer
1. Enable Windows Integrated Authentication: “Tools” “Internet Options” “Advanced” choose “Enable
Windows Integrated Authentication” (requires restart)
2. Enable automatic logon in the Intranet zone: “Tools” “Internet Options” “Security” “Local Intranet”
“Custom Level” choose “Automatic logon only in Intranet Zone” from the “User Authentication”
section
3. Add the AS Java engine’s host name to the list of local Intranet sites: “Tools” “Internet Options”
“Security” “Local Intranet” “Sites” “Advanced”
4. Add the AS Java engine’s host name to the list of sites bypassed by the proxy (if available): “Tools”
“Internet Options” “Connections” “LAN Settings” “Advanced”
Procedure for Mozilla Firefox
1. Add the AS Java engine’s host name to the list of sites bypassed by the proxy (if available):
2. Enable Integrated Authentication:
a. Type “about:config” in the address bar of the browser
b. Filter the entries by name using the prefix “negotiate”
c. Add the AS Java engine’s address (including the protocol) to the entries “network.negotiate-
auth.delegation-uris” and “network.negotiate-auth.trusted-uris”
Note: The detailed navigation steps related to browser configuration are examples only. Depending
on the version of your browser they may not be correct. In that case you must find out how those
settings are managed and make sure they are set correctly.
2011/SAP AG
6. ADDING KERBEROS REALMS
In this step you add the realm that you want to the SPNego configuration
Procedure
1. Start the SPNego configuration application by accessing http://<host>:<port>/spnego
2. Log on with a user with administrator privileges
3. Press the “Add” push button
4. Enter the name of the realm you are adding. This is a mandatory field
5. Enter the description of the realm you are adding. This is an optional field and has no functional meaning.
6. Press “OK”
2011/SAP AG
7. CONFIGURE THE USER MAPPING
In this step you configure or modify the user mapping that will be used to resolve the user for the selected realm
Procedure
1. Start the SPNego configuration application by accessing http://<host>:<port>/spnego
2. Log on with a user with administrator privileges
3. Select the realm whose user mapping you wish to configure or modify
4. Press the “Edit” push button
5. Select the “User Mapping” tab below the realm
6. Choose a user mapping mode from the “Mapping mode” drop-down menu. This is a mandatory field
7. Choose a user mapping source from the “Source” drip-down menu. This is a mandatory field
8. Press the “Save” push button
Example
We assume that the name of the user is “sapdemo” and it belongs to the “IT.CUSTOMER.DE” domain. In that
case, the Kerberos token that arrives at the engine will contain the Kerberos Principal Name (KPN)
“[email protected]”. It is also assumed that the first custom attribute is “email” and the second (if
necessary) – “age”
Mode: Principal only
Source: logon id
The user in the user store must have their “logonid” attribute equal to
“sapdemo”
Mode: Principal only
Source: logon alias
The user account in the user store must have their “logonalias”
attribute equal to “sapdemo”
Mode: Principal only
Source: user attribute
The user in the user store must have their “email” attribute equal to
“sapdemo”
Mode: Principal@REALM
Source: logon id
The user in the user store must have their “logonid” attribute equal to
Mode: Principal@REALM
Source: logon alias
The user account in the user store must have their “logonalias”
attribute equal to “[email protected]”
Mode: Principal@REALM
Source: user attribute
The user in the user store must have their “email” attribute equal to
Mode: Principal and REALM
Source: ADS Data Source
The user account in the user store must have their “principal”
attribute equal to “sapdemo” and their “realm” attribute equal to
”IT.CUSTOMER.DE”. The “principal” and “realm” attributes are
standard and come with the AS Java engine installation
Mode: Principal and REALM
Source: user attributes
The user in the user store must have their “email” attribute equal to
“sapdemo” and their “age” attribute equal to ”IT.CUSTOMER.DE”
2011/SAP AG
8. CONFIGURE THE ENCRYPTION KEYS
In this step you configure or modify the encryption key(s) that will be used to decrypt the Kerberos token that
arrives at the AS Java engine
Prerequisites
Before you start to configure the encryption keys for the selected realm, you must generate a keytab file. You can
use the “ktab” tool provided by Java 1.6. It is executed like this:
ktab –a <principal_name>@<REALM> -k <keytab_file_name>
The parameters are as follows:
<principal_name> - the name of the service user
<REALM> - the realm of the service user
<keytab_file_name> - the name of the keytab file to be created
You will be asked to provide the user’s password when creating the keytab file. It is very important that you enter
the correct one – the command makes no checks and will always create a file, even if the password is incorrect.
However, during runtime SPNego authentication will fail as the Kerberos token will not be decrypted.
Example
If we assume that the name of the service user is “j2ee-d21-hades”, their realm is “IT.CUSTOMER.DE” and we
want to create the keytab file “keytab”, then the command would have the following syntax:
ktab –a [email protected] –k keytab
Procedure
1. Start the SPNego configuration application by accessing http://<host>:<port>/spnego
2. Log on with a user with administrator privileges
3. Select the realm whose encryption keys you wish to configure or modify
4. Press the “Edit” push button
5. Select the “Keys” tab below the realm
6. Press the “Add” push button
7. Browse to the keytab file generated earlier
8. Press the “Import” push button
9. Select the keys you want to use. By default all of them are selected and it is recommended that you do not
change that. At least one key must be selected.
10. Press “OK”
11. Press the “Save” push button
The AS Java engine’s versions 6.40, 7.00, 7.01 and 7.02 support DES and RC4-HMAC encryption
algorithms. If you want to use AES you must upgrade the engine to 7.20 or above.
2011/SAP AG
9. ENABLE THE REALM
In this step you enable the selected realm
Procedure
1. Start the SPNego configuration application by accessing http://<host>:<port>/spnego
2. Log on with a user with administrator privileges
3. Select the realm you want to enable
4. Press the “Edit” push button
5. Press the “Enable” push button
6. Press the “Save” push button
You can enable a realm only if you have already configured its user mapping and encryption keys.
Otherwise it must stay disabled until you complete its configuration.
A realm can be disabled in the same way it can be enabled. If a realm is disabled, it will not be
used during authentication even if it is configured correctly and a request from a user that belongs
to that realm arrives.
2011/SAP AG
10. ADJUST THE AUTHENTICATION STACK
In this step you add the SPNegoLoginModule to the respective authentication stack (s) in order to configure the
required applications to use Kerberos authentication
Procedure
1. Log on to the Visual Administrator and navigate to ServerXXX -> Services -> Security Provider Service
2. Select the “ticket” template and remove the SPNEGOLoginModule (capital letters) if it is still there. Either
way, add the SPNegoLoginModule at the appropriate position and with the appropriate flag
3. You can modify any policy configuration in the same manner, depending on the specific applications you want
to have configured to work with SPNego
4. SPNego should now work
EvaluateTicketLoginModule SUFFICIENT
amet, consectetaur
adpisicing elit, sed
SPNegoLoginModule
CreateTicketLoginModule
BasicPasswordLoginModule
CreateTicketLoginModule
OPTIONAL
amet, consectetaur
adpisicing elit, sed
SUFFICIENT
amet, consectetaur
adpisicing elit, sed
REQUIRED
amet, consectetaur
adpisicing elit, sed
REQUIRED
amet, consectetaur
adpisicing elit, sed
A typical authentication stack that relies on SPNego
for initial authentication with a user name and
password combination as a fallback might look like
this
2011/SAP AG
11. LEGACY MODE
The SPNegoLoginModule login module can work in the so-called legacy mode. This means that it will use the old
implementation even though the new one is also available. This mode is not recommended and should be used only in
very specific and urgent situations when for some reason the new configurations cannot be performed.
The login module can work in legacy mode only if the following requirements are fulfilled:
At some point in time the old SPNego wizard was used to configure SPNego
The old SPNego configuration was working without any problems
Procedure
1. Log on to the Visual Administrator and navigate to ServerXXX -> Services -> Security Provider Service
2. Switch to Edit mode and select the “User Management” tab
3. Hit the “Manage Security Stores” button at the bottom of the screen
4. Make sure that the “UME User Store” is selected in the “User Stores” column and then select the
SPNegoLoginModule module from the list of login modules
5. Hit the “View/Change Properties” button at the bottom of the screen
6. Enter a new property with name “com.sap.security.spnego.legacy” and value “true”