This Wiki describes how to configure identity federation for Security Assertion Markup Language (SAML) 2.0 so that the users can attain federated identities for authentication. It also gives some example scenarios that would help the user federate identities.

The features described in that Wiki are valid for the following releases:

• NetWeaver (NW) 7.2 SP8 or later versions.
  NW 7.2 SP8 is released on September 14, 2012.
• NW 7.3 SP8 or later versions.
  NW 7.3 SP8 is released on October 05, 2012. You can also use NW 7.30 SP7 before the SP8 release date. For more information, see Latest SAML 2.0 functionality downported to 7.30 SP7.
• NW 7.31 SP4 or later versions.

Table of Contents

Definition of Identity Federation

The identity federation provides the means to share identities between partners. Such identities are federated between partners when there is an agreement between the providers on a set of identifiers or identity attributes. To share information about a user, partners must be able to identify the user, even though they may use different identifiers for the same user.

The SAML 2.0 standard defines the name identifier (name ID) as the means to establish a common identifier. Once the name ID has been established, the user is said to have a federated identity. When you decide to use the federated identities, you have to know whether the establishment or termination of the federated identity for the user is done dynamically or it is pre-established, whether identity attributes about the users are exchanged, whether the identifier is transient and it will expire at the end of the user session, and whether the information should be encrypted for higher security.

Identity Federation Process

The identity federation process can be viewed as a system that comprises three blocks: SAML Subject Identifier, User Identifier, and final User. The service provider receives the SAML subject identifier with the specified assertion subject name ID or assertion attributes. The service provider uses the assertion subject name ID or the assertion attributes to specify the user identifier. Then the service provider checks the user ID mapping mode to determine how to find the user in its user management engine (UME). When the service provider finds the local user, it authenticates the user.

Name ID Formats

The system supports the following name ID formats: E-mail, Kerberos, Persistent, Transient, Unspecified, Windows Name, X509 Subject Name. The settings of any of these formats do not affect the configuration of the others.

Federation Types

The system supports three federation types for the configuration of a trusted identity provider: Persistent Users, Persistent Users (Advanced), and Virtual Users.

Persistent Users

The meaning of the Persistent Users type is to establish permanent user IDs in the user management engine (UME). The UME acts as a database for the service provider that is used to authenticate assertions from the identity provider. In this case the identities of users in different systems are identified and agreed upon ahead of time between the administrators of the systems. This kind of agreement is also supported by SAML 1.x. The administrator of the identity provider and the service provider agree how the name ID used for the user in the identity provider maps to the user in the service provider.

Use this kind of federation to support most scenarios where you need to map user identities across domains.

Persistent Users (Advanced)

The configuration of federation type Persistent Users (Advanced) is necessary if you know that the identity of the user is not configured ahead of time, but on the fly. The federation type Persistent Users (Advanced) offers the following options:

• Allowing the identity provider to create a name ID

The identity provider may have the authorization to generate a new identifier for the user, should one not already exist. The service provider sets the AllowCreate attribute on the NameIDPolicy element to 'true” for that permission.

• Allowing interactive federation

You can enable users to interactively establish federation between existing accounts or even create their own accounts on the target system with self-registration. Such a federation is established on the fly. In this mode, if there is no pre-existing federation or no user is found on the service provider with the same name ID, the service provider prompts the user to log on. When the user logs on, the service provider prompts the user to federate the accounts. If the user accepts, the service provider writes the name ID from the user account on the identity provider to the user attribute configured for the name ID on the service provider. If the user declines, the service provider logs the user on as usual, but does not federate the accounts.

• Allowing automatic account creation

In this mode, if there is no pre-existing federation or no user is found on the service provider for the same name ID, the service provider creates a user account. To create the account, the service provider uses the SAML 2.0 attributes sent by the identity provider.

• Updating attributes, roles, and groups at login

This option is a possibility to set attributes, roles, and groups as configured on the service provider side. That way you enable the service provider to overwrite existing user attributes with data sent as SAML 2.0 attributes. Only attributes, roles and groups configured during SAML 2.0 authentication will be modified in this case. Attributes, roles and groups configured by the administrator in the UI of the user administrator will not be changed.

• Filtering user IDs passed from the identity provider

This field defines what pattern the service provider can accept as user ID source. The pattern is defined in the form of a Java regular expression. The first group of the regular expression will be used as user ID source for further authentication.

• Adding a prefix and/or suffix to a user ID

This field helps the service provide to configure the right user ID by making this ID unique for the system. Through these fields the administrator can add a fixed prefix and suffix to the user ID source before it is used for authentication.

• Configuring a mapping between SAML 2.0 attributes and UME attributes

You can create a mapping between the SAML 2.0 attributes sent with the SAML assertion and the UME attributes the service provider writes. These UME attributes provide the basis for the user on the service provider. SAML 2.0 attributes marked as mandatory must be present in the received assertion and have values. Otherwise the service provider rejects the entire authentication attempt. The service provider does not create or update the user account without the mandatory values. You can also create a mapping between SAML attributes, roles and groups or predefine the roles and groups to which users belong.

Virtual Users

The meaning of federation type Virtual Users is to have a user in the service provider’s database temporarily. The name ID for such a user is created for the duration of the user session or as long as the user is logged on only. Identity federation with the type Virtual Users enables you to provide authenticated users with access to your system without needing to know specific details about those users.

Values for the User ID Mapping Mode

The user ID mapping mode defines how the service provider can identify the user by specifying how the user identifier maps to the user in its database. This information tells the service provider how to search for the respective user in its UME.

User ID mapping mode values:

Scenario of Type Persistent Users

Donna wants to configure her system to use a name ID that is set ahead of time and resides permanently in the database. She also decides to use an e-mail address as name ID for the identity federation. That way she knows that the e-mail name ID will be mapped to an e-mail attribute at the service provider. For her implementation, Donna follows the following configuration steps:

1. She chooses Configuration → Authentication and Single Sign-On → SAML 2.0 → Trusted Providers from the SAP NetWeaver Administrator system.
2. She selects the option Show: Identity Providers and picks the name of her trusted identity provider.
3. She chooses the Identity Federation tab.
4. After choosing the Edit button, she adds the E-mail name ID format with federation type Persistent Users.
5. For a User ID Source, she selects the value Assertion Subject NameID.
   In that case she specifies that the user ID source should be obtained from the subject name ID attribute of the assertion.

   Note

   You can use another attribute in the assertion by selecting the option Assertion Attribute. 

   
6. For a user ID mapping mode, she specifies Email.
   The user ID mapping mode defines which attribute of the user at the service provider is mapped to the user ID source. Because Denise has an e-mail address as user ID, she selects such an option for the mapping mode.
7. After the settings are complete, she saves her entries.
8. Because her identity provider is not active, she chooses the Enable button.

Donna decides to test her system with one of her customers Denise. Denise’s service provider receives a subject name ID in the assertion with a value Denise.Smith@example.com, and for the service provider settings she sets her E-mail attribute with a value Denise.Smith@example.com.  When Denise accesses the identity provider in an identity provider initiated single sign-on, she is prompted to provide credentials. After a successful log-on, the identity provider provides the subject name ID in the assertion. The service provider searches for the user with an e-mail address that matches the subject name ID and finds the Denise’s account. Because the e-mail address in the service provider is unique, the service provider logs the user on and completes the authentication.

Scenario of Type Persistent Users (Advanced)

Julie Armstrong has decided to configure her system to use persistent pseudonyms that are not specified ahead of time, but on the go. She also uses many identity providers as trusted providers that communicate with her service provider, and she wants to be sure that the user ID source evaluated by her system is unique so that the authentication will not fail. She only knows that each identity provider has unique user IDs in its database. Julie would like to set her system to inform what department the users come from. For that purpose she requires the name of the department to be included in the assertion. Also, she hopes that her system will authenticate a user any time this user tries to log in, and she won’t have to do any manual work for the configuration of these users. For that purpose, she updates her system to support SAML 2.0 and configures it to use federation type Persistent Users (Advanced) by implementing the following steps:

1. She chooses Configuration → Authentication and Single Sign-On → SAML 2.0 → Trusted Providers from the SAP NetWeaver Administrator system.
2. She selects the option Show: Identity Providers and picks the name of her trusted identity provider which is currently active.
3. She chooses the Identity Federation tab.
4. After choosing the Edit button, she selects the Persistent name ID with federation type Persistent Users (Advanced).
5. She also selects the automatic account creation option so that the service provider will create a user if it cannot find a local user based on the received SAML 2.0 assertion and the configuration.
6. For a User ID Source, she selects the assertion subject name ID. She also sets the User ID Mapping Mode to use the logon ID.

   Note

   You can use another attribute in the assertion by selecting the option Assertion Attribute. 

   
7. Because Julie wants to allow only a range of users to be authenticated, she sets the regular expression (.+)\Q@company.de\E. That way she defines that for this identity provider only users with subject name ID <name>@company.de will be allowed and only the <name> part will be used as name ID source.
8. However, it is possible that two users in two different companies have the same first name. For example, we could have john@acme.com at the second provider and john@company.de at the first provider. This would create a conflict, and Julie wants to avoid it. For that purpose she sets “Provider1_” as prefix in the configuration of the first trusted provider. This configuration adds the string “Provider1_” as prefix to the user ID source of the first trusted provider. That way the final user ID source for john@acme.com would be Provder2_john and for john@company.de would be Provider1_john, which values are unique.
9. She finally decides to update the user attributes every time a user logs in. For that purpose she selects Update attributes, roles and groups at login. She also wants to know from which department of the partner company the user comes. For that she configures that the value of the assertion attribute department is set to the user attribute Department and that this attribute is mandatory. This means that if this SAML 2.0 attribute is empty or missing, the service provider rejects the SAML response and the authentication fails. In that case the identity provider must send this attribute for a successful authentication.
10. She saves her entries so that the system will update her configuration.
11. She follows steps 2 through 10 for each trusted identity provider.
    For the fifth trusted provider she sets the e-mails to be received from the company Pinnacle, and she allows users with an e-mail address <name>@pinnacle.de only.
    Configuration of the fifth identity provider

Now Julie is gratified that her system can manipulate the identities of her users securely and reliably. She is happy that she can restrict the users logging in to her system just by setting the regular expression and the suffix and/or prefix values. She also knows that she does not need to enter the name ID of each user in her system manually because she has enabled the automatic account creation. Whenever a user logs on to the system for the first time, the service provider creates an account for that user if it does not exist.

Scenario of Type Virtual Users

John Miller has a company that sells electronics. John’s company has users from different trust companies. Each trust company has its own identity provider and the users of these companies order from John’s company at different times. If John decides to add users from another trust company, he just needs to add another trusted identity provider. Because users change constantly, he does not need to keep a database of them all permanently. That is why John sets his system to use temporary user IDs. For that purpose, John configures his service provider with the following steps:

1. He chooses Configuration → Authentication and Single Sign-On → SAML 2.0 → Trusted Providers from the SAP NetWeaver Administrator system.
2. He selects the option Show: Identity Providers and picks the name of his trusted identity provider.
3. He chooses the Identity Federation tab.
4. After choosing the Edit button, he selects the Transient name ID with federation type Virtual Users.
5. For a User ID Source, he selects the value Assertion Subject NameID so that the subject identifier is obtained from the subject name ID attribute of the assertion.

   Note

   You can use another attribute in the assertion by selecting the option Assertion Attribute. 

   
6. He adds a default user attribute Company for each trusted identity provider.
   That way John is able to recognize what company corresponds to a specific trust.
   Example Configuration of the Second Trusted Identity Provider
7. After saving his entries, John tests his new configuration with some customers.

After a client authenticates at the identity provider of Company1, the identity provider creates a subject identifier that is provided to the service provider in the SAML 2.0 assertion. The service provider creates a virtual user with logon ID equal to the subject name ID in the assertion. In that case the user identifier takes the same value as the subject name ID value passed in the assertion because no filters, prefixes, and suffixes are set. The authentication succeeds and the customer accesses the ordering system to place an order. When another customer from Company2 accesses the ordering system, the service provider authenticates this user by creating another temporary user ID. The system does not care about the identities of the users from the two companies. From the settings of Default User Attributes, it only knows what goods a user from Company1 and a user from Company2 ordered so that John’s company can ship these goods to both companies.