Configuring single sign-on (SSO) partners

Before you can use WebSphere® Application Server as a service provider partner to identity providers (IdPs) for IdP-initiated single sign-on, you must establish partnerships between the WebSphere Application Server SAML service provider and external SAML identity providers.

1. Add an IdP SAML service provider for single sign-on.
   
   

   Complete the steps in one of the following topics:

   • Adding an IdP signer certificate to a SAML trust store

     Extract a SAML IdP signer certificate from the SAML IdP metadata file or get a certificate file from your IdP administrator, and then import the SAML Assertion signer certificate.

   • Adding a SAML IdP by using a metadata file

     Run the AdminTask.importSAMLIdpMetadata wsadmin command to import the SAML IdP metadata file and add the IdP information to the SAML TAI configuration.

     If you get an error from running the command, you must complete the steps in the other topic, Adding an IdP signer certificate to a SAML trust store, instead.

   After you add an IdP to the SAML service provider, return to this topic and proceed to step 2.

2. Make your application trust the realm of your IdP. Perform one of the following actions:
   • If your application does not require knowledge of the original realm name, you can hardcode the realm name that the SAML TAI specifies for core security to use while creating the subject.
     1. Click Security > Global Security.
     2. Under User account repository, get the realm name from the Realm name field.
     3. Set the sso_<id>.sp.useRealm SAML TAI property to the realm name acquired in the previous step.
   • If your application must have access to the original realm name in the Subject, grant inbound trust to all the realms that the identity provider uses.

     For each Identity provider that is used with your WebSphere Application Server service provider, you can grant inbound trust with either the administrative console or the wsadmin command utility.

     • Add inbound trust by using the administrative console.

       1. Click Global security.
       2. Under user account repository, click Configure.
       3. Click Trusted authentication realms - inbound.
       4. Click Add External Realm.
       5. Click OK and Save changes to the master configuration.

     • Add inbound trust by using the wsadmin command-line utility.

       1. To add a single identity provider to the inbound trust, use the addTrustedRealms command, with realmName the name of the realm that needs to be granted inbound trust.

          AdminTask.addTrustedRealms('[-communicationType inbound -realmList realmName]')

       2. To add a list of realms to the inbound trust, use the addTrustedRealms command, with realm1, realm2, and realm3 the realms that need to be added as trusted realms.

          AdminTask.addTrustedRealms('[-communicationType inbound -realmList realm1|realm2|realm3]')

3. Optional: Configure the WebSphere Application Server security context using the sso_<id>.sp.idMap,sso_<id>.sp.groupMap, and sso_<id>.sp.groupName attributes.
   
   

   The WebSphere Application Server service provider intercepts a SAML protocol message from the identity provider and establishes the security context. The security context is created by mapping the SAML assertion. The security context mapping in the service provider is very flexible and configurable. The following is a list of available mapping options:

   idAssertion

   Map the SAML assertion to the WebSphere Application Server platform Subject without using a local registry. This is the default behavior. In this default implementation, the SAML NameID is mapped to the principal, the issuer is mapped to the realm, and selected attributes can be mapped to group members. ID assertion can be further customized. For example, you can configure a SAML attribute as a principal, realm, accessId, or a list of group members. You can also configure NameQualifier from NameID as a realm, or use a predefined realm name.

   localRealm

   Configure the WebSphere Application Server service provider to map the NameID from a SAML assertion to the local registry of the service provider, and build the subject from the registry. With this option, you can directly search the SAML NameID against the registry, or use a plugin point for custom mapping of the assertion, and then use the new mapped ID to build the subject from the registry.

   localRealmThenAssertion

   Map the NameID to the registry, and fall back to ID assertion if the NameID cannot be mapped to the registry.

   AddGroupsFromLocalRealm

   Combine ID assertion and local registry. This option enables you to reevaluate group membership while doing ID assertion. Consider a SAML assertion from a partner lab, containing user Joe with a group attribute of X-ray Techs. At the service provider, the group X-ray Techs is a subgroup of group Technicians, but Joe is not necessarily in the user registry of the service provider. The authorization policy of the service provider application allows access to the Technicians group. To achieve this, the SAML TAI needs to look up the asserted groups X-ray Techs in the registry and then include the parent groups Technicians in the Subject.

   When doing ID assertion to create a security context, a custom security realm is chosen. You must explicitly add the custom realm as a trusted realm. In a default ID assertion implementation, the SAML issuer name is used as the security realm. You must explicitly add the issuer name to the list of inbound trusted authentication realms in current user registry. After adding the custom realm to the inbound trusted realms, you are ready to do role mapping with this custom realm.

   To add a custom realm as a trusted realm, see the Add IdP realms to the list of inbound trusted realms step.

4. Add the WebSphere Application Server SAML service provider to the identity providers for SSO.
   
   

   Each identity provider that is used with your WebSphere Application Server service provider needs to be configured to add the service provider as an SSO partner. The procedure for adding the service provider partner to an identity provider depends on the specific identity provider. Refer to the documentation of the identity provider for instructions on how to add a service provider partner for SSO.

   You can either export the WebSphere Application Server service provider metadata, and import it to the identity provider, or manually configure the identity provider to add the service provider.

   To add the service provider as a federation partner to an identity provider, you must provide the URL of the Assertion Consumer Service (ACS) of the service provider, which is the -acsUrl parameter used when enabling the SAML trust association interceptor (TAI).

   If an identity provider can use a metadata file to add the service provider as a federation partner, you can use the wsadmin exportSAMLSpMetadata command to export the service provider metadata.

   wsadmin -lang jython
   AdminTask.exportSAMLSpMetadata('-spMetadataFileName /tmp/spdata.xml -ssoId 1')

   This command creates the /tmp/spdata.xml metadata file.

   If the SAML token is encrypted, you must provide the public key certificate that you want the identity provider to use for encrypting the SAML token, and the certificate must exist in the WebSphere Application Server default KeyStore before performing an export.