Enabling SAML as an identity provider

Jazz® Authorization Server supports Security Assertion Markup Language (SAML) web browser single sign-on (SSO) in the WebSphere Application Server Liberty profile, which enables web applications to delegate user authentication to a SAML identity provider instead of a configured user registry.

1. Enable the Jazz Authorization Server to support SAML 2.0.
   1. Open the JazzAuthServer_install_dir/wlp/usr/servers/jazzop/server.xml file in an editor.
   2. Locate the SAML xml section and follow the instructions between the <!-- SAML> and <!-- end of SAML> comments to enable the SAML and SSL features.
   3. Open the JazzAuthServer_install_dir/wlp/usr/servers/jazzop/appConfig.xml file in an editor.
   4. Locate the SAML xml section between the <!-- SAML> and <!-- end of SAML> comments. Uncomment the <samlWebSso2.0> and <authFilter> elements.
      Note: The mapTouserRegistry="User" property ensures that users are recognized by the Jazz Authorization Server. You need this property only if your deployment includes Rational solution for Collaborative Lifecycle Management (CLM) clients that are based on Eclipse technology. If you are using CLM web clients only, which retrieve group information directly from SAML, you do not need to use the mapToUserRegistry="User" property.

      Example: The following sample code shows the SAML section of an appConfig.xml file that is edited to support SAML 2.0.

      <samlWebSso20 
         id="defaultSP" 
            spCookieName="jazzop_sso_cookie_idp"
            forceAuthn="true"
            authFilterRef="samlAuthFilter">
      </samlWebSso20>
      
      <authFilter id="samlAuthFilter">
         <requestUrl id="samlRequestUrl" urlPattern="/authorize" matchType="contains" />
         <userAgent id="samlUserAgent" agent="Mozilla|Opera" matchType="contains" />
      </authFilter>
      

   5. Save your changes and close the file.
2. Export the spmetadata.xml file from the Jazz Authorization Server (SAML SP) by following the instructions in step 2 of Configuring SAML web browser SSO in the Liberty profile.
   Tip: The spmetadata.xml file contains the keystore pairs that allow secure communication between the SAML IdP and the Jazz Authorization Server (SP).

   1. In a browser window, export the spmetadata.xml file by using the following URL:

      https://host_name:ssl_port/ibm/saml20/defaultSP/samlmetadata

      Note: The port number is defined in the appConfig.xml file.
   2. Save the file and record the location.
      Important: If you are not prompted to save the file, then there is a problem with the SAML configuration in the Jazz Authorization Server and the spmetadata.xml file is not exported. Check the SAML settings in the appConfig.xml and server.xml files.
3. For the Jazz Authorization Server to communicate with the SAML IdP, the server must be registered as a partner in the IdP. Registering and enabling a partner depends on the SAML implementation in your IdP. Follow the SAML documentation to register and enable the partner.
4. Export the SAML IdP metadata file so that you can add it to the Jazz Authorization Server. Follow the steps to export the metadata file for the IdP.
5. Copy the metadata file that you exported in step 4 to the following location:

   JazzAuthServer_install_dir/wlp/usr/servers/jazzop/resources/security/idpmetadata.xml

6. Test the Jazz Authorization Server connection to the SAML IdP by using the following URL:

   https://JazzAuthServer:port/oidc/endpoint/jazzop/authorize

   Note: The port number is defined in the appConfig.xml file.

   If you configured the Jazz Authorization Server correctly, the SAML IdP login window opens.

   Note: Logging in now generates an error, which you can ignore. The purpose of this step is to ensure that the SAML login window is displayed.
7. If your deployment includes a mix of Eclipse and web clients, you must configure the Jazz Authorization Server to support either a file-based user registry server or a Lightweight Directory Access Protocol (LDAP) server. This step provides a mechanism for Eclipse clients to authenticate.
   Remember: Web clients retrieve group information directly from the SAML IdP.

   • For instructions about using a file-based registry server, see Configuring the Jazz Authorization Server to use a file-based user registry.
     Important: The user passwords that are stored in the IdP supersede any user passwords that are defined in the Jazz Authorization Server.
     Note: Assign group roles to users by creating members in the JazzAdmins, JazzUsers, JazzGuests, and JazzProjectAdmins groups.
   • For instructions about using an LDAP server, see Configuring the Jazz Authorization Server to use an LDAP user registry.
   • For more information about configuring SAML, see the following WebSphere Liberty documentation:
     • Configuring SAML Web Browser SSO in Liberty
     • SAML web single sign-on version 2.0
8. Start the Jazz Authorization Server, as described in Managing users on Jazz Authorization Server.
9. Validate the Jazz Authorization Server configuration.
   1. Open a browser window outside the Jazz Authorization Server host environment and go to the following URL:

      host_name:ssl_port/oidc/endpoint/jazzop/.well-known/openid-configuration

   2. Verify that the user registry is configured correctly by going to the following URL:

      host_name:ssl_port/oidc/endpoint/jazzop/registration