External Authentication with SAML Integration (SSO) - Web Console

Table of Contents

Overview

Security Assertion Markup Language (SAML) is an XML-based standard that can perform single sign-on (SSO) exchanges. Use SAML if users logging on to the Web Console should be authenticated by an Identity Provider (IdP). In this case, user names, but not user passwords, are stored in the CommServe database. The SAML User Registration Workflow can be used to create user names in the CommServe database.

High-Level Process Flow for SAML Interactions

The process includes the following actors:

  • Service Provider (SP): The Web Console is the resource owned by the SP. The SP shares metadata with the IdP.
  • Identity Provider (IdP): The user credentials are maintained by the IdP. The IdP shares metadata with the SP.
  • Web Browser: The messages sent between the SP and IdP go through a web browser.

Service Provider Initiated Flow

  1. A user who is not logged in clicks a link for the Web Console on the customer's portal.
  2. The SP generates a SAML request.
  3. The SP redirects the user to the IdP URL and includes the SAML request.
  4. The IdP processes the request and prompts the user to enter login credentials.
  5. The IdP validates the user credentials.
  6. The IdP redirects the user to the Web Console URL and includes the SAML response.
  7. The SP validates the response and creates a login session for the user.

Identity Provider Initiated Flow

  1. A user goes to the IdP URL and logs on.
  2. The IdP validates the user credentials.
  3. The IdP redirects the user to the Web Console URL and includes the SAML response.
  4. The SP validates the response and creates a login session for the user.

High-Level View of the SAML Request and Response

SAML Request Contents

  • Issuer ID: the Entity ID in the SP metadata
  • Request ID: a randomly generated ID number
  • Assertion Consumer Service URL (ACS URL): the same ACS URL as in the SP metadata
  • Date and time the request is created

SAML Response Contents

  • Issuer ID: the Entity ID in the IdP metadata
  • Response ID: a randomly generated ID number
  • Date and time the response is created
  • Status of the response, for example, success or failure
  • saml:AuthnStatement assertion: confirms the user is authenticated
  • saml:AttributeStatement assertion: contains user attributes, for example, the user name and email address

Support

Security Assertion Markup Language (SAML) v2.0 is supported. For SAML specifications, go to the Oasis website, Security Assertion Markup Language (SAML) v2.0.

Creating URLs for Service Provider and Identity Provider Flows

Service Provider Initiated

The link to the Web Console from the customer's portal must be the URL of the Web Console appended with /initiateSaml.do?samlAppKey={Base64 encoded application key}, for example: http://client.mydomain.com:80/webconsole/initiateSaml.do?samlAppKey=RUSAMPIxRDQ1N0EzNENF. See Obtaining an Application Key.

Identity Provider Initiated

When the IdP redirects the user to the Web Console URL, the redirect must be the URL of the Web Console appended with /samlAcsIdpInitCallback.do?samlAppKey={Base64 encoded application key}, for example: http://client.mydomain.com:80/webconsole/samlAcsIdpInitCallback.do?samlAppKey=RUSAMPIxRDQ1N0EzNENF. See Obtaining an Application Key.

Obtaining an Application Key

Prerequisites

Configure the provider metadata. For information on configuring metadata, see Configuring Provider Metadata.

Procedure

  1. From the CommCell Console ribbon, click the Home tab, and then click Control Panel.
  2. Under the Others section, click External Application Settings.
  3. In the External Application Settings dialog box, select the SAML application and then click View to see the application key on the General tab.
  4. Use Base64 to encode the application key before using it as the samlAppKey value.

Configuring Provider Metadata

SAML metadata is used to share configuration information between the Identity Provider (IdP) and the Service Provider (SP). Metadata for both the IdP and the SP is defined in an XML file:

  • The IdP metadata XML file contains the IdP certificate, the entity ID, the redirect URL, and the post URL, for example, saml_idp_metadata.xml.
  • The SP metadata XML file contains the SP certificate, the entity ID, and the Assertion Consumer Service URL (ACS URL), for example, saml_sp_metadata.xml.

Before using SAML to log on to the Web Console, metadata from the IdP must be uploaded and metadata from the SP must be generated. After the SP metadata is generated, it must be shared with the IdP. Contact the IdP for instructions on sharing the SP metadata.

Prerequisites

  1. Add the bEnableExternalApplicationSettings additional setting so External Application Settings is visible in the Others section of the control panel. For information on adding the additional setting, see Enabling External Application Settings.
  2. Create an Identity Provider (IdP) metadata XML file using the SAML protocol. For SAML metadata specifications, go to the Oasis website, Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0.
  3. Create a keystore file. For information on keystore files, see Certificates.

Procedure

  1. From the CommCell Console ribbon, click the Home tab, and then click Control Panel.
  2. Under the Others section, click External Application Settings.
  3. In the External Application Settings dialog box, click Add.
  4. In the Add Application Info dialog box, click the General tab and enter an application name in the Application name box.
  5. From the Application Type list, select SAML.

    Once SAML is selected, the SAML tab automatically opens.

  6. On the SAML tab, select the Enable Signature verification check box so the request message is digitally signed.
  7. Upload the IdP metadata:
    1. On the SAML tab in the Upload IDP metadata section, click Browse next to the File Path box.
    2. Browse to the location of the XML file that contains the IdP metadata, select the file, and click Import.
    3. Review the values in the Entity ID, Redirect Url, and Post Url boxes. This information came from the imported IdP XML file.
  8. Generate the SP metadata:
    1. In the Reuse\Generate new metadata section in the File Path box, enter the location and file name of the keystore file, for example, C:\security\mykeystore.jks.

      For information on keystore files, see Certificates.

    2. In the Web Console list, click the Web Console to use with SAML authentication.
    3. Enter the keystore file values for Alias name, Key store password, and Key password.
    4. In the Destination file path box, enter a location and a file name for the SP metadata XML file, for example, C:\metadata\saml_sp_metadata.xml.

      Once OK is clicked, the SP metadata XML file is created using the location and name entered in the Destination file path box.

  9. Click OK to generate the SP metadata and to save the IdP metadata.

    After the SP metadata is generated, it must be shared with the IdP. Contact the IdP for instructions on sharing the SP metadata.

What to Do Next

Certificates

In Service Provider (SP) initiated SAML, a SAML request is prepare by the SP. The SP digitally signs the request using a private key. When the request is received by the Identity Provider (IdP), the digital signature is verified using the public key sent by the SP in a certificate. Certificates are self-signed or signed by a certification authority (CA).

A Java keystore file stores the certificate and the private key. To create the Java keystore file, use the keytool utility, the Java key and certificate management tool. For more information on the keytool utility, go to the Oracle Documentation website, keytool - Key and Certificate Management Tool.

Creating a Self-Signed Certificate and a Private Key

Use the keytool utility to create a keystore file that contains a private key and a self-signed certificate that holds a public key.

Procedure

  1. Run the following command from the C:\Program Files\Java\java_version\bin folder after substituting the parameter values.

    The command can be run from %JAVA_HOME%\bin if the %JAVA_HOME% environment variable is set.

    keytool -genkey -keyalg RSA -alias <aliasName> -keystore <file_path\keystoreFilename.jks> -validity <daysValid> -keysize 2048

    The following table displays the parameters for the keytool command:

    Parameter Description of Parameter Values
    alias The alias name for the certificate.
    keystore The file path and file name for the .jks file created by the keytool.
    validity The number of days the keystore file is valid starting from the day the keystore file is created.

    Example

    keytool -genkey -keyalg RSA -alias selfsigned -keystore "C:\mykeystore.jks" -validity 365 -keysize 2048

  2. When prompted, enter the information requested by the keytool command.
  3. Make note of the following values:
    • name and location of the keystore file
    • alias name
    • keystore password
    • key password

    Use these values to create the SP metadata XML file. For information, see Configuring Provider Metadata.

Creating a CA-signed Certificate and a Private Key

Use the keytool utility to create a keystore file that contains a private key and a CA-signed certificate that holds a public key.

Procedure

  1. Create a keystore file containing a local certificate:
    1. Run the following command from the C:\Program Files\Java\java_version\bin folder after substituting the parameter values.

      The command can be run from %JAVA_HOME%\bin if the %JAVA_HOME% environment variable is set.

      keytool -genkey -keyalg RSA -alias <aliasName> -keystore <file_path\keystoreFilename.jks>

      The following table displays the parameters for the keytool command:

      Parameter Description of Parameter Values
      alias The alias name for the certificate. The alias name is used to import the CA-signed certificate.
      keystore The file path and file name for the .jks file created by the keytool.

      Example

      keytool -genkey -keyalg RSA -alias casigned -keystore "C:\mykeystore.jks"

    2. When prompted, enter the information requested by the keytool command.

      For CA-signed certificates, the company and location information must be accurate, for example, when prompted for the Organization Name, enter the full legal name of your organization.

    3. Make note of the following values:
      • name and location of the keystore file
      • alias name
      • the keystore password
      • the key password

      After the CA-signed certificate is imported into the keystore file, use these values to create the SP metadata XML file. For information, see Configuring Provider Metadata.

  2. Generate a Certificate Signing Request (CSR) and submit it to the CA.
    1. Run the following command from the C:\Program Files\Java\java_version\bin folder after substituting the parameter values.

      The command can be run from %JAVA_HOME%\bin if the %JAVA_HOME% environment variable is set.

      keytool -certreq -keyalg RSA -alias <aliasName> -file <request_file_name.csr> -keystore <file_path\keystoreFilename.jks>

      The following table displays the parameters for the keytool command:

      Parameter Description of Parameter Values
      alias The alias name for the certificate. The alias name is used to import the CA-signed certificate.
      file The file name of the .csr file.
      keystore The file path and file name for the .jks file created by the keytool.

      Example

      keytool -certreq -keyalg RSA -alias casigned -file certreq.csr -keystore "C:\mykeystore.jks"

    2. Submit the .csr file to your CA according to their procedure.
  3. Import the CA-signed certificate into the keystore file according to the procedure provided by the CA.

    Run the following command from the C:\Program Files\Java\java_version\bin folder after substituting the parameter values.

    The command can be run from %JAVA_HOME%\bin if the %JAVA_HOME% environment variable is set.

    keytool -importcert -file <CertificateFileName> -keystore <keystoreFileName> -alias <AliasName>

    The following table displays the parameters for the keytool command:

    Parameter Description of Parameter Values
    file The file name of the .csr file.
    keystore The file path and file name for the .jks file created by the keytool.
    alias The alias name for the certificate.

    Example

    keytool -importcert -file certificate.cer -keystore "C:\mykeystore.jks" -alias casigned