SAML Configuration Steps

Be sure to read the Important information, Caution, and Notes as you configure MSS to use SAML.

Follow the steps in these sections.

Configure MSS as a SAML Service Provider

These steps are required before you can download the service provider’s metadata.

1. Import the identity provider’s metadata to MSS (the service provider).

   Click IMPORT and enter the file name or the HTTP endpoint (a URL). You may need to consult with your SAML administrator to locate the metadata.

   After importing, click APPLY to store the metadata.

   Note

   The colored box under the IMPORT button displays the status of the identity provider (IdP) metadata: not stored, imported, or stored.

2. Enter the service provider SAML Entity ID. The entry can be either a URL (preferred) or a URN for your installed Management and Security Server.

   URN examples: com:company:hostname:sp , com:microfocus:mssprod:sp

3. Enter the SAML Assertion Consumer Service prefix URL.

   This entry is the prefix URL for the MSS endpoint that handles SAML assertions. At runtime, this prefix is used to build the web endpoint for the SAML assertion consumer service (SACS) and will resolve to <prefix URL>/callback.

   For example, if your prefix is https://hostname.domain.com/mss, then at runtime, the assertion consumer service will be https://hostname.domain.com/mss/callback

   Caution

   The prefix URL value must end with the MSS server's web application context. For example, the default context is /mss.

   If you encounter an error message, be sure this requirement is met.

4. Click APPLY.

   The Download button is enabled when these values have been specified and applied:

   • Identity Provider metadata

   • Service Provider SAML Entity ID

   • SAML Assertion Consumer Service prefix URL

5. Sign Requests. Check this box to sign the SAML service provider requests made by MSS.

   Note

   If needed, a different private key and/or certificate may be specified in the keystore named saml.bcfks, located in the MSSData directory. You can manage this keystore with Java's KeyTool.

   When the saml.bcfks keystore is changed, restart MSS, and then repeat the steps to Download the service provider (MSS) metadata and EXPORT it to the identity provider.

6. Download or access the service provider (MSS) metadata.

   Use the Download button or the HTTP endpoint defined in the Export service provider’s metadata field.

7. Export the service provider’s metadata to the identity provider.

   Refer to your identity provider’s documentation to complete these steps:

   a. Upload the service provider metadata to the identity provider.

   b. Configure the identity provider to trust MSS (the service provider).

Advanced SAML Service Provider Settings

Set these values in MSS/server/conf/container.properties:

• saml.max.authentication.lifetime

  Default is 86400 (seconds), which equals 24 hours. By default, the SAML client will accept assertions based on a previous authentication for 24 hours.

  Note

  There are two types of timeouts on the identity provider (IdP) side:

  • session timeout, based on the last login timestamp

  • idle timeout, based on the last user's action timestamp

  To prevent user sessions from timing out unexpectedly, use one of the recommended values for saml.max.authentication.lifetime.

  Recommended Values:

  Platform	saml.max.authentication.lifetime (seconds)
  ADFS	28800
  Okta	2592000
  Azure	2592000

• saml.wants.assertions.signed

  Default is true. By default, assertions are signed, but this property can be disabled by setting it to false.

• saml.path.parameter.callback.url.enabled

  Default is true. Set to false to use query parameter in the callback url.

Identity Mapping

The SAML assertion provides values that can be used as the source for the user identifier. When LDAP authorization is enabled, you could use the LDAP user identifier.

Choose your preferred sources to identify and authorize each user.

User identifier source

Choose a value from the SAML assertion. Note: The user identifier appears in the user interface.

• Assertion subject. Use the SAML assertion’s Subject name identifier as the user identifier.

• Assertion attribute. Enter a SAML assertion attribute name to use as the source for the user identifier.

Distinguished name source (for LDAP authorization)

Choose whether to use the LDAP source or a value from the SAML assertion.

• LDAP. Use LDAP when the user's identifier is unique within LDAP.

• Assertion subject. Use the SAML assertion’s Subject name identifier as the user’s distinguished name for LDAP authorization.

• Assertion attribute. Enter a SAML assertion attribute name to use as the source for the user’s distinguished name for LDAP authorization.

SAML whitelist

MSS uses a whitelist composed of trusted host names to mitigate a potential security vulnerability when using SAML authentication. By default, the SAML whitelist is enabled and contains the registered Host Access for the Cloud session servers and the MSS host itself.

To configure the SAML whitelist:

1. Check Enable SAML whitelist (the default).

   For troubleshooting purposes, the SAML whitelist can be disabled.

2. Enter alternative host names to include in the SAML whitelist.

   Specify any alternate host names for the SAML client application hosts, such as a short host name, a fully-qualified DNS name, or a numeric IP address. Separate the host names with a space.

LDAP Servers

Verify or edit the configuration of your LDAP Servers.

Troubleshooting SAML setup

Issue: Unable to log in or authenticate

• Look for error messages in the MSS trace log: \MSS\MSSData\log\trace.<n>.log.
• If you see, "Authentication issue instant is too old or in the future," the saml token has expired.

Resolution: 

1. Close all the browser instances and try to log in again. This action creates a new saml token.

2. Update the saml.max.authentication.lifetime, according to the recommended values in the Advanced SAML Service Provider Settings.