Skip to content

Configuring SAML for TFIM in WebSphere Application Server

Configure SAML for IBM Tivoli Federated Identity Manager in IBM WebSphere Application Server by following the simplified steps in this topic.

  • This deployment scenario uses the version of IBM Tivoli Federated Identity Manager (TFIM) that is supported for HCL Connections™. For more information, see the Tivoli information center for additional information about TFIM.

  • If you are using MS-ADFS - Microsoft ADFS 2.0, refer to the WebSphere documentation for configuring your TAI.

  • Using the WebSphere Application Server administrative console, install the SAML ACS application into your WebSphere Application Server Dmgr. Install the app_server_root/installableApps/WebSphereSamlSP.ear file to your application server or cluster.

    For more information, see Enabling your system to use the SAML web single sign-on (SSO) feature in the WebSphere Application Server information center.

  • Enable SAML TAI using the administrative console as follows:

    1. Log on to the WebSphere Application Server administrative console.
    2. Click Security > Global security.
    3. Expand Web and SIP security and click Trust association.
    4. Under the General Properties heading, select the Enable trust association option, and then click Interceptors.
    5. Click New and enter com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor in theInterceptor class name field.

    6. Under Custom properties, complete 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 Server is installed and sslport is the web server SSL port number WC_defaulthost_secure, for example:

      https://websphere.company.com:9443/samlsps/acs

    7. Click New and enter the following custom property information:

      • Name:sso_1.sp.idMap
      • Value: "localRealm" or "idAssertion". Typically, "localRealm" is used.
    8. Navigate to Global security, and then click Custom properties > General properties to create, or modify, the following custom properties and assign them the specified values:

    Name: : ``` com.ibm.websphere.security.DeferTAItoSSO 

        Value:
    :   ```
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor

    Name: : ``` com.ibm.websphere.security.InvokeTAIbeforeSSO 

        Value:
    :   ```
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor,com.ibm.ws.security.oauth20.tai.OAuthTAI

    Name: : com.ibm.websphere.security.performTAIForUnprotectedURI

    Assign this property the value `true`.

    Note: Be sure to include a comma separating the two values.

  • Configure single sign-on (SSO) partners as follows:

    For more information, see Configuring single sign-on partners in the WebSphere Application Server information center.

    1. From the SAML IdP, export the following items:
      • metadata file
      • SAML token signer certificate

    2. Import the IdP metadata file into WebSphere Application Server as follows:

      1. Start the WebSphere Application Server.

      2. Start the wsadmin command-line utility from the app_server_root/bin directory by entering the command: wsadmin -lang jython

        ``` cd /opt/IBM/WebSphere/DeploymentManager/bin ./wsadmin.sh -lang jython -username administrator -password password WASX7209I: Connected to process "dmgr" on node dubxpcvm603CellManager01 using SOAP connector; The type of process is: DeploymentManager WASX7031I: For help, enter: "print Help.help()"

        wsadmin>AdminTask.importSAMLIdpMetadata('-idpMetadataFileName /opt/saml/ICIDP_IBM_metadata.xml -idpId 1 -ssoId 1 -signingCertAlias idpsamlcert') 'true'

        wsadmin>AdminConfig.save() wsadmin>quit ```

        .

      3. Restart the WebSphere Application Server.

        1. Import the IdP SAML token signer certificate into WebSphere Application Server as follows:
      4. Log on to the WebSphere Application Server administrative console.
      5. Click Security > SSL certificate and key management > Key stores and certificates > NodeDefaultTrustStore > Signer certificates. Use CellDefaultTrustStore instead of NodeDefaultTrustStore for a deployment manager.
      6. Click Add and complete the certificate information, for example, /opt/saml/idp-cert.pem.
      7. Click Apply.
        1. In the WebSphere Application Server administrative console, add inbound trust as follows:
      8. Click Global security.
      9. Under User account repository, click Configure.
      10. Click Trusted authentication realms - inbound.
      11. Click Add External Realm.
      12. Enter the External realm name and save.
      13. Click OK and then Save to preserve your changes to the master configuration.
      14. Create the SP metadata file and import it into the IdP as follows:

    3. Export the SP metadata file from the WebSphere Application Server system as follows:

      ``` cd /opt/IBM/WebSphere/DeploymentManager/bin ./wsadmin.sh -lang jython -username administrator -password password WASX7209I: Connected to process "dmgr" on node dubxpcvm603CellManager01 using SOAP connector; The type of process is: DeploymentManager WASX7031I: For help, enter: "print Help.help()"

      wsadmin>AdminTask.exportSAMLSpMetadata('-spMetadataFileName /tmp/spdata.xml -ssoId 1') ```

      Note: This command creates the /tmp/spdata.xml SP metadata file.

    4. Copy /tmp/spdata.xml to the IdP server and then import it into the IdP.

    5. Restart the IdP.

    6. Remove any TAI (Trust Association Interceptors) that are not needed to avoid conflict with the SAML TAI as follows:

    7. Log on to the WebSphere Application Server administrative console.

    8. Click Security > Global security.
    9. Expand Web and SIP security and then click Trust association.
    10. Click Interceptors.
    11. Delete any TAIs that are not needed and save the changes.

    12. Navigate to Global security > Trust association > Interceptors > com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor to verify that the following, case-sensitive properties in the SAML TAI have the exact spelling of uppercase and lowercase as shown:

      • sso_1.idp_1.EntityID Be sure the letters that are shown in uppercase are in fact uppercase.
    14. sso_1.idp_1.SingleSignOnUrl Be sure the letters that are shown in uppercase are in fact uppercase.
    15. Navigate to Global security > Trust association > Interceptors > com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor to add the following properties in the SAML TAI:

    Name: sso_1.sp.trustAnySigner Value: true Name: sso_1.sp.charEncoding Value: UTF-8 Name: sso_1.sp.disableDecodeURL Value: true

  • Set up SAML support as follows:

    1. From the WebSphere® Application Server Integrated Solutions Console, navigate to Global security > Trust association > Interceptors > com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor to set the Custom property sso_1.sp.login.error.page to com.ibm.connections.concerto.services.ADFSIdPMapping if Microsoft™ Active Directory Federation Services (ADFS) is used. Otherwise, use com.ibm.connections.concerto.services.TFIMIdPMapping.

      • TFIMIdPMapping is used for TFIM 6.2.2, SAML 2.0 IdP only.

        Note: When TFIM is in place, it can rely on either WebSphere or WebSEAL as a single point of contact for the SAML IdP implementation.

      • ADFSIdPMapping is used for MS ADFS 2.0, SAML 2.0 IdP only.

        1. Obtain the com.ibm.connections.concerto.services.jar from the connections_root/Concerto directory and copy this file into the WebSphere Application Server’s library extension folder. For example, copy com.ibm.connections.concerto.services.jar to:
      • Windows™: C:\IBM\WebSphere\AppServer\lib\ext
      • Linux™: /opt/IBM/WebSphere/AppServer/lib/ext
      • Note: For a multi-node ND deployment, all the nodes must have this redirection service JAR available for the SAML TAI to pick up.

  • Restart the deployment as follows:

    1. Stop all clusters, servers, and applications.
    2. Stop the Dmgr.
    3. Restart the Dmgr and then restart the Node agents.
    4. Verify that all nodes are synchronized.
    5. Start the appropriate clusters, servers, and applications.

Parent topic:Configuring SAML redirection services for web SSO