Configuring SAML single sign-on in the identity provider

Use SAML for single sign-on to allow applications to verify the identity of its users based on the authentication that is performed by Verify. The users are redirected to Verify for login. Verify verifies the users' identities, sends the information through a SAML assertion, and confirms with the service provider that the users are authorized to access and use the resource.

Before you begin

  • You must have administrative permission to complete this task.
  • Open at least two browser windows to complete the setup. One for the Verify administration console and the other for the administration console of the target application.
    • Log in to the IBM® Security Verify administration console.
    • Log in to the target application administration console with your Administrator account.
  • You must set up the basic information for the application instance in the General tab. See Setting the basic application details.

About this task

Verify can act as a single sign-on identity provider or a service provider. In this task, Verify is the identity provider, and the target application is the service provider.

If you are using a Custom Application template, see Custom application before you proceed.

Configure Verify and the service provider to talk to each other. To enable SAML single sign-on, you must provide:
  • Verify with certain data from the service provider.
  • The service provider with certain data from Verify.

If the service provider signs its SAML authentication request, you must first add the signer certificate in the Security > Certificates page. See Managing certificates.

If the service provider requires other attributes from the SAML assertion aside from the built-in attributes, add the required attribute sources in the Directory > Attributes page. See Managing attributes.

Note: Tenant administrators can view and update some SAML federation configurations through the new API end-point /v1.0/saml/federations/{federationName}, with manageFederations and readFederations API entitlements.
The configuration properties that are used for the identity sources are:
clockSkew
The tolerance in seconds when the received SAML assertion NotBefore and NotOnOrAfter is validated.
messageValidTime
The tolerance in seconds when the received SAML message IssueInstant is validated.
The configuration properties that are used for the applications are:
assertionSettings.assertionValidAfter
The tolerance in seconds that are added to NotOnOrAfter when the SAML assertion is issued.
assertionSettings.assertionValidBefore
The tolerance in seconds that are added to NotBefore when the SAML assertion is issued.
messageValidTime
The tolerance in seconds when the received SAML message IssueInstant is validated.
Configuration properties that are used for both the identity sources and applications are:
crlEnabled
Checks the certificate revocation list. Checking is done for all functions that use an external certificate. If your configuration does not require CRL checking, you can disable it. For example, if you use an internal certificate authority (CA), you might want to disable CRL checking. The crlEnabled property defaults to true.
keySelectionCriteria
Specify which key or certificate to use for signing, validating, encrypting, or decrypting various messages. If there are multiple keys or certificates with the same Subject DN as the key or certificate with the specified alias, this setting determines which one to use. Use one of the following selection methods:
only.alias
Select the key or certificate with the specified alias. This method is the default.
longest.lifetime
For signing, a valid key with the longest available lifetime is used. For validation, keys that have the same SubjectDN are sorted based on lifetime availability. The keys are tried sequentially starting with the key that has the longest lifetime availability until validation is successful.
shortest.lifetime
For signing, a valid key with the shortest available lifetime is used. For validation, keys that have the same SubjectDN are sorted based on lifetime availability. The keys are tried sequentially starting with the key that has the shortest lifetime availability until validation is successful.
  • Data type: String
  • Example: only.alias

Procedure

  1. Identify the service provider and the URLs that are necessary to establish single sign-on between the providers.
    Table 1. ID and URLs
    Information Descriptions
    Provider ID

    It is the target application provider ID that uniquely identifies the target application to Verify.

    You can get this information from the third-party application. Depending on the target application, this information might come from any of the following applicable sources:
    • On the Single Sign-On configuration page of the target application administration console.

      See Single Sign-on Configuration for instructions on how to access the page.

    • In the service provider metadata.
    • In the target application' SAML single sign-on setup documentation.
    • From the target application support team.
    The value depends on the third-party application. It can be:
    • Static or one of these formats:
      • https://{@domainName}.<application>.com
      • {@domainName}.<application>.com

      where {@domainName} corresponds to the only dynamic component in the Provider ID and is replaced automatically at runtime with the value you specified in the General tab.

      Important: If you update the Provider ID and then update the Domain Name in the General tab, the Provider ID value resets to its default value based on the specified Domain Name.
    • Dynamic

      The Provider ID has multiple dynamic components. As such, the field value is not automatically populated.

    Note: Only ASCII characters are supported. For more information, see https://ascii.cl/.
    Use unique ID This check box is available on some application.

    Creates a unique identifier for the application to avoid duplicate provider ID conflicts.

    Assertion Consumer Service URL (HTTP-POST)

    Specifies the endpoint at the service provider that receives the SAML authentication response.

    The identity provider redirects the SAML authentication response to this URL. This endpoint receives and processes the SAML assertion.

    The service provider can specify its preferred URL when it sends its SAML authentication request.

    The value depends on the third-party application. It can be:
    • Static or one of these formats:
      • https://{@domainName}.<application>.com/saml/consume
      • https://{@domainName}.<application>.com/saml/callback

      where {@domainName} corresponds to the only dynamic component in the Assertion Consumer Service URL and is replaced automatically at runtime with the value you specified in the General tab.

    • Dynamic

      The Assertion Consumer Service URL has multiple dynamic components. As such, the field value is not automatically populated.

    You can get this information from the third-party application. Depending on the target application, this information might come from any of the following applicable sources:
    • On the Single Sign-On configuration page of the target application administration console.

      See Single Sign-on Configuration for instructions on how to access the page.

    • In the service provider metadata.
    • In the target application' SAML single sign-on setup documentation.
    • From the target application support team.
    Note:

    For custom applications, you can have multiple assertion consumer service URLs. You can modify the index value of the URL, but each value must be unique. You can also select the URL you want to be the default URL.

    Name Identifier Management URL (HTTP-POST)
    Note: This option is available only in a Custom application template that is configured with Persistent as the NameID format, and the Name identifier is Not Specified.

    Specifies the endpoint at the service provider that receives the SAML Manage Name IDrequest and the SAML Manage Name ID response.

    The identity provider redirects the SAML Manage Name ID request and SAML Manage Name ID response to this URL. This endpoint receives and processes the SAML Manage Name ID request and SAML Manage Name ID response.

    The value depends on the third-party application.

    You can get this information from the third-party application. Depending on the target application, this information might come from any of the following applicable sources:

    • On the Single Sign-On configuration page of the target application administration console. See the application's Single Sign-on Configuration instructions for information about how to access the page.

    • In the service provider metadata.
    • In the target application's SAML single sign-on setup documentation.
    • From the target application support team.
    Use identity provider initiated single sign-on
    Note: This option is available only in a Custom application template.

    Select this option if the service provider supports identity provider-initiated sign-on. In this scenario, users directly sign in to the identity provider site and then access the service provider.

    If enabled, the identity provider initiated single sign-on URL constructs the URL to redirect to the IBM Security Verify user homepage. You do not need to provide the Service Provider SSO URL.

    If this option is not enabled, the Service Provider SSO URL is required and it constructs the URL to redirect to the IBM Security Verify user homepage.

    Target URL

    It is the user landing page in the target application, where the user is redirected after sign-on.

    It does not necessarily refer to the target application homepage. It can be any of the protected resources of the service provider that is the end destination of a single sign-on.

    This field is displayed only for these conditions:
    • The target application supports relay state.
    • The target application supports identity provider initiated single sign-on. This URL is used only when single sign-on is initiated by the SAML 2.0 identity provider.
    • The Target URL is dynamic or has more than one possible value.
    You can get this information from the third-party application. Depending on the target application, this information might come from any of the following applicable sources:
    • On the Single Sign-On configuration page of the target application administration console.

      See Single Sign-on Configuration for instructions on how to access the page.

    • From the target application website.
      1. Navigate to the target landing page.
      2. Copy and paste the URL in this field.
    Service Provider SSO URL

    It is the service provider endpoint that initiates the SAML authentication request from a user browser and returns a SAML authentication response to verify the user.

    This field is displayed only for these conditions:
    • The target application supports service provider initiated single sign-on.
    • The Service Provider SSO URL is dynamic or has more than one possible value.
    You can get this information from the third-party application. Depending on the target application, this information might come from any of the following applicable sources:
    • On the Single Sign-On configuration page of the target application administration console.

      See Single Sign-on Configuration for instructions on how to access the page.

    • In the target application' SAML single sign-on setup documentation.
    • From the target application support team.
  2. Configure the signature options. Use a digital signature to establish trust between Verify and the service provider.
    Table 2. Signature Options
    Information Descriptions
    Sign authentication response
    Note: This option is available only in a Custom application template.
    Indicates whether the identity provider signs the SAML assertion and authentication response.
    Note: Some service providers cannot accept a signed authentication response.

    When selected, both the SAML assertion and authentication response are signed.

    If this option is not selected, only the SAML assertion is signed. The SAML assertion is always signed regardless if the check box is selected or not.

    Signature Algorithm
    Note: This option is available only in a Custom application template.

    Signing algorithm digitally signs the SAML assertion or the SAML authentication response.

    Use a digital signature algorithm to digest the data and then encrypt that digest. Select from the following supported algorithms:
    • RSA-SHA1
    • RSA-SHA256

    Most applications use RSA-SHA256 as the default algorithm for signing the SAML assertion or authentication response.

    RSA-SHA1 is being deprecated and is only provided for use with legacy applications that do not support stronger encryption.

    Validate SAML request signature

    Indicates whether the service provider signs the SAML authentication request when it initiates the SAML single sign-on flow.

    Signing the SAML authentication request can be mandatory for some service providers and optional for others.

    When selected, you must select the signer certificate.

    Note: This option is not available for service providers that do not sign their SAML authentication request.
    Service Provider Signer Certificate

    Lists all of the signer certificates that are uploaded from the Settings > Certificates > Signer Certificates page.

    Select the signer certificate that you uploaded for the selected application.

  3. Configure the encryption options. Enable encryption to secure the content of the SAML assertion so only the intended recipient can access it.
    Table 3. Encryption Options
    Information Descriptions
    Encrypt assertion
    Encrypts the entire SAML assertion that is sent to the service provider. Only the intended service provider can decrypt and understand its contents.
    Note: This option is only available to service providers that supports encryption.
    SAML Assertion Encryption Algorithm

    The algorithm encrypts the SAML assertion content.

    Select from the following Advanced Encryption Standard (AES) or Data Encryption Standard (DES) algorithms:
    AES-128
    Uses a 128-bit key. Data transformation is repeated over 10 cycles.
    AES-256
    Uses a 256-bit key. Data transformation is repeated over 14 cycles. It is the default or commonly used encryption algorithm.
    AES-192
    Uses a 192-bit key. Data transformation is repeated over 12 cycles.
    Triple DES
    Uses a triple-length data key that consists of three 8-byte DES keys to encipher 8 bytes of data. It uses the following method:
    • Enciphers the data by using the first key.
    • Deciphers the result by using the second key.
    • Enciphers the second result by using the third key.
    Note: This option is available for all applications that supports encryption.
    Encryption Key Transport Algorithm The algorithm encrypts the assertion encryption key. Select from the following algorithms.
    RSA-OAEP

    Public-key encryption scheme. Designed to encrypt only short messages, typically secret keys for symmetric encryption.

    See http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p.

    RSA-v1.5
    Signature scheme.

    See http://www.w3.org/2001/04/xmlenc#rsa-1_5

    Note: This option is available for all applications that supports encryption.
    Service Provider Encryption Certificate

    Lists all of the service provider encryption certificates that are imported in Security > Certificates > Signer Certificates.

    Select the encryption certificate that Verify must use together with the selected SAML Assertion Encryption Algorithm to encrypt the SAML assertion content.

  4. Identify the identity provider attribute sources for the SAML assertion. See Configuring the SAML subject and mapping attributes.
  5. Select the policy that determines how users can access the application.

    You can continue to use the default access policy that is assigned, which is Allow access from all devices. Alternatively, you can clear the check box, and click the Edit to select from the list of predefined access policies. For more information, see Access policies.

  6. Click Save.

What to do next

  • Provide the service provider with information about Verify that is necessary to complete the SAML single sign-on configuration between Verify and the service provider. See the instructions that are provided in the user interface.
  • Add user or group entitlements to permit access to the configured applications. See Managing application entitlements (by administrator or application owner).
  • Enforce two-factor authentication for added security control on users when they sign on to the configured applications. See Configuring authentication factors.