Enabling your system to use the SAML web single sign-on (SSO) feature

Before you begin

This task assumes that you are familiar with the SAML SSO feature.

About this task

Before you can use the SAML Web SSO feature, you must install the SAML Assertion Consumer Service (ACS) and enable SAML TAI.
Note: The SAML ACS application should be installed on each application server that has been or will be configured to accept SAMLResponses from the IdP. These servers will be referenced on the URLs specified on the sso_.sp.acsUrl SAML TAI custom properties.

Procedure

  1. Install the SAML ACS application.
    Choose one of the following approaches:
    • Using the administrative console, install the app_server_root/installableApps/WebSphereSamlSP.ear file to your application server or cluster.
    • Install the SAML ACS application by using the python script.
      1. Navigate to the app_server_root/bin directory.
      2. Run the installSamlACS.py script.
        wsadmin -f installSamlACS.py install <nodeName> <serverName>
        or
        wsadmin -f installSamlACS.py install <clusterName>
        where nodeName is the node name of the target application server, serverName is the server name of the target application server, and clusterName is the name of the application server cluster.
  2. Enable SAML TAI.
    You can enable SAML TAI by using either the wsadmin command utility or the administrative console.
    • Enable SAML TAI using the wsadmin command utility.
      1. Start the WebSphere Application Server.
      2. Start the wsadmin command utility from the app_server_root/bin directory by entering the command: wsadmin -lang jython.
      3. At the wsadmin prompt, enter the following command: AdminTask.addSAMLTAISSO('-enable true -acsUrl https://<hostname>:<sslport>/samlsps/<any URI pattern string>') where hostname is the host name of the system where WebSphere Application is installed and sslport is the Web server SSL port number (WC_defaulthost_secure).
      4. Save the configuration by entering the following command: AdminConfig.save().
      5. Exit the wsadmin command utility by entering the following command: quit.
      6. Restart the WebSphere Application Server.
    • Enable SAML TAI using the administrative console.
      1. Log on to the WebSphere Application Server administrative console.
      2. Click SecurityGlobal security.
      3. Expand Web and SIP security and click Trust association.
      4. Under the General Properties heading, select the Enable trust association check box and click Interceptors.
      5. Click New and enter com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor in the Interceptor class name field.
      6. Under Custom properties, fill in the following custom property information: Name: sso_1.sp.acsUrl and Value: https://<hostname>:<sslport>/samlsps/<any URI pattern string> where hostname is the host name of the system where WebSphere Application is installed and sslport is the Web server SSL port number (WC_defaulthost_secure).
        Note: If you need to have multiple, similar entry points for your SAML workflows, you can specify a wildcard value instead of a specific URI pattern string at the end of the URL specified as the value of this property. Specifying a wildcard as part of the value of this property eliminates the need to separately configure each of the similar entry points.

        Following are some examples of valid ways to include a wildcard as part of the value for this property:

        https://<server>/<context_root>/ep1/path1/p*
        https://<server>/<context_root>/ep1/path1/*
        https://<server>/<context_root>/ep1/*
        Avoid trouble: If you are using metadata to configure your SSO, wildcards cannot be used in the acsUrl definition.
      7. Click New and enter the following custom property information: Name: sso_1.sp.idMap and Value: idAssertion.
      8. Click OK.
      9. Go back to SecurityGlobal security and click Custom properties.
      10. Click New and define the following custom property information under General properties: Name: com.ibm.websphere.security.DeferTAItoSSO and Value: com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor.
        Note: The property com.ibm.websphere.security.DeferTAItoSSO, was previously used in the default configuration of all installed servers. Now it is only used as part of the SAML configuration. Therefore, even if this property already exists in your system configuration, you must change its value to com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor. Multiple values, separated with commas, cannot be specified for this property. It must be set to a single SAML TAI.
      11. Click New and define the following custom property information under General properties: Name: com.ibm.websphere.security.InvokeTAIbeforeSSO and Value: com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor.
      12. Click OK.
      13. Restart WebSphere Application Server.

Results

Avoid trouble: When users receive an LtpaToken2 cookie from a web SSO login, and use that same LTPA cookie to authenticate to a different WebSphere cell than the cell that created it, the server that receives the cookie needs to make a SOAP request back to the server where the cookie originated. Then, it can retrieve the full security attributes for the user. This process is called security attribute propagation. If you intend to use LTPA cookies in this manner, ensure that the network onto which your WebSphere cells are hosted can facilitate a connection between the two cells. For more information about security attribute propagation, see Security attribute propagation.
The SAML TAI is now enabled for WebSphere Application Server.

What to do next

After enabling the SAML Web SSO feature, you must configure WebSphere Application Server as a service provider (SP) partner to participate in the IdP-initiated single sign-on scenarios with other identity providers.