Configure WebSphere Application Server as a SAML service provider for an identity provider

1. Enable the SAML Web SSO feature.
2. Import SAML Idp metadata into WAS SAML service provider as a partner
3. Add IdP realms to the list of inbound trusted realms
4. Add the WAS SAML service provider to the identity providers
5. Configure the WAS security context

Import SAML Idp metadata into WAS SAML service provider as a partner

Add an identity provider, such as ISIM or ForgeRock, to the WAS SAML service provider as a partner...

• Add using IdP metadata...

  1. Start wsadmin...
     cd app_server_root/bin
     wsadmin -lang jython

  2. At the wsadmin prompt, enter:
     AdminTask.importSAMLIdpMetadata('-idpMetadataFileName IdPMetaDataFile -idpId 1 -ssoId 1 -signingCertAlias idpAlias')

     ...where IdpMetaDataFile is the full path name of the IdP metadata file, and IdpAlias is any alias name specified for the imported certificate.

  3. Save the configuration:
     AdminConfig.save()
     quit

  4. Restart WAS servers.

• Add by importing IdP signer into WAS truststore...

  For each identity provider, import the SAML token signer certificate.

  The minimum requirement to configure the WAS SAML service provider as an SSO partner to an identity provider is to import the SAML token signer certificate from the identity provider to the trust store of the service provider.

  Import the SAML token signer certificate...

  • Using the administrative console:
    1. Log on to the WAS administrative console and click...
       Security > SSL certificate and key management > Key stores and certificates > NodeDefaultTrustStore > Signer certificates> Add

       Use CellDefaultTrustStore instead of NodeDefaultTrustStore for a deployment manager.

    2. Fill in the certificate information.

    3. Click Apply.

  • Using wsadmin:

    1. Start the WAS appservers.

    2. Start wsadmin:
       cd app_server_root/bin
       wsadmin -lang jython

    3. At the wsadmin prompt, enter:
       AdminTask.addSignerCertificate('[-keyStoreName NodeDefaultTrustStore -certificateFilePath <certFile> -base64Encoded true -certificateAlias <certAlias>]')

       ...where certFile is the full path name of the certificate file and certAlias is the alias of the certificate. Use CellDefaultTrustStore instead of NodeDefaultTrustStore for a deployment manager.

    4. Save the configuration:
       AdminConfig.save()
       quit.

Add IdP realms to the list of inbound trusted realms

For each Identity provider used with our WAS service provider, grant inbound trust to all realms used by the identity provider.

• Add inbound trust using the administrative console.
  Global security > user account repository > Configure > Trusted authentication realms - inbound > Add External Realm > external realm name

• Add inbound trust using wsadmin:

  • Add a single identity provider to the inbound trust:
    AdminTask.addTrustedRealms('[-communicationType inbound -realmList <realmName>]')

    realmName is the name of the realm to be granted inbound trust

  • Add a list of realms to the inbound trust:
    AdminTask.addTrustedRealms('[-communicationType inbound -realmList <realm1|realm2|realm3>]')

    realm1, realm2, and realm3 are the realms to be added as trusted realms.

Add the WAS SAML service provider to the identity providers

Each identity provider used with our WAS 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.

We can either export the WAS 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, 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, we can 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, provide the public key certificate that we want the identity provider to use for encrypting the SAML token, and the certificate must exist in the WAS default KeyStore before performing an export.

Configure the WAS security context using the attributes

• sso_id.sp.idMap
• sso_id.sp.groupMap
• sso_id.sp.groupName

The WAS service provider intercepts a SAML protocol message from the identity provider and creates the security context by mapping the assertion.

SAML assertion mapping options...

• idAssertion

  Map the SAML assertion to the WAS platform Subject without using a local registry. Default.

  1. The SAML NameID is mapped to the principal
  2. The issuer is mapped to the realm
  3. Selected attributes can be mapped to group members

  ID assertion can be further customized. For example, we can configure a SAML attribute as a principal, realm, accessId, or a list of group members. We can also configure NameQualifier from NameID as a realm, or use a predefined realm name.

• localRealm

  Configure the WAS 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, we 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

  This option combines ID assertion and local registry and allows us 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. We 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. We 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, we are ready to do role mapping with this custom realm.

See also

1. Use the SAML web single sign-on (SSO) feature
2. SAML web single sign-on (SSO) TAI custom properties