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

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


EvaluateTicketLoginModule SUFFICIENT

amet, consectetaur

adpisicing elit, sed

SPNegoLoginModule

CreateTicketLoginModule

BasicPasswordLoginModule


OPTIONAL

amet, consectetaur


SUFFICIENT

amet, consectetaur


REQUIRED

amet, consectetaur


REQUIRED

amet, consectetaur


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



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”


Source: logon alias

The user account in the user store must have their “logonalias”

attribute equal to “sapdemo”


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

“[email protected]”


Source: logon alias

The user account in the user store must have their “logonalias”

attribute equal to “[email protected]”


Source: user attribute


“[email protected]”

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


“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



3. Select the realm whose encryption keys you wish to configure or modify


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”


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



3. Select the realm you want to enable


5. Press the “Enable” 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


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


EvaluateTicketLoginModule SUFFICIENT

amet, consectetaur


SPNegoLoginModule


BasicPasswordLoginModule


OPTIONAL

amet, consectetaur


SUFFICIENT

amet, consectetaur


REQUIRED

amet, consectetaur


REQUIRED

amet, consectetaur


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


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”

Sp Ne Go Documentation

Documents

adpisicing

save push

logonalias

logonid attribute

email attribute

java engines

administrator

java engine