Be sure to read the Important information, Cautions, and Notes as you configure MSS to use SAML.
IMPORTANT:The SAML authentication scheme in MSS relies on HTTP session cookies for proper operation. Consistent use of fully-qualified DNS names across all SAML entities is strongly recommended. In particular, any clients of MSS should be configured to access MSS using the same DNS name that is used for the Assertion Consumer Service prefix URL.
Follow these steps:
These steps are required before you can download the service provider’s metadata.
Import theto MSS (the service provider).
Clickand 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, clickto 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.
Enter the service provider SAML URL (preferred) or a URN for your installed Management and Security Server.. The entry can be either a
URN examples: com:company:hostname:sp , com:microfocus:mssprod:sp
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 value specified for the prefix URL must meet these requirements. If you encounter an error message, be sure these requirements are met:
The prefix URL value must end with the MSS server's .
For example, the default context is /mss.
The protocol must match the one used by MSS clients attempting to authenticate using SAML.
For example, when using SAML authentication in Host Access for the Cloud, the protocol specified in the management.server.url property in Host Access for the Cloud must match the protocol of the prefix URL defined in this field: http or https. A mix of protocols (http and https) is not supported.
Thebutton is enabled when these values have been specified and applied:
Identity Provider metadata
Service Provider SAML Entity ID
SAML Assertion Consumer Service prefix URL
. 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 the service provider (MSS) metadata and it to the identity provider.
Download or access the service provider (MSS) metadata.
Use thebutton or the HTTP endpoint defined in the field.
Export the service provider’s metadata to the identity provider.
Refer to your identity provider’s documentation to complete these steps:
Upload the service provider metadata to the identity provider.
Configure the identity provider to trust MSS (the service provider).
These properties can be set in MSS/server/conf/container.properties:
Default is 7200 (seconds). By default, the SAML client will accept assertions based on a previous authentication for 2 hours. This value should match the identity provider's session timeout value.
Default is true. By default, assertions are signed, but this property can be disabled by setting it to false.
Default is true. Set to false to use query parameter in the callback url.
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.
Choose a value from the SAML assertion. Note: The user identifier appears in the user interface.
. Use the SAML assertion’s Subject name identifier as the user identifier.
. Enter a SAML assertion attribute name to use as the source for the user identifier.
Choose whether to use the LDAP source or a value from the SAML assertion.
. Use LDAP when the user's identifier is unique within LDAP.
. Use the SAML assertion’s Subject name identifier as the user’s distinguished name for LDAP authorization.
. Enter a SAML assertion attribute name to use as the source for the user’s for LDAP authorization.
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.
NOTE:The SAML whitelist is restrictive by default. That is, if a user specifies a valid host name in the URL — but that host name is not in the whitelist — the end-user browser application will not be able to use SAML.
For example, the user may specify a numeric IP address in the browser, but by default, numeric IPs are not whitelisted. When an untrusted host name is specified in the browser URL, an HTTP 403 error is returned, and the browser content indicates that a technical error has occurred. The Trace log file will also contain a Warning message indicating that a request was received that is "not from a host in the SAML whitelist."
To configure the SAML whitelist:
For troubleshooting purposes, the SAML whitelist can be disabled.
Enterto 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.
Verify or edit the configuration of your.
If you encounter one of these issues, follow the steps to resolve it.
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," there is a mismatch between the session timeout values on the Service Provider and the Identity Provider (IdP).
Resolution:Find out what the Identity Provider’s session timeout value is. Adjust the Service Provider’s session timeout value to match the IdP’s session timeout value by setting saml.max.authentication.lifetime in the MSS container.properties.
(See Advanced SAML Service Provider Settings, above).
Session times out
The saml token expires when the Server Provider’s session timeout value doesn't match the one on the Identity Provider.
Resolution: Find out what the Identity Provider’s session timeout value is. Adjust the Service Provider’s session timeout value to match the IdP’s session timeout value by setting saml.max.authentication.lifetime in the MSS container.properties.
(See Advanced SAML Service Provider Settings, above).