Enable SAML Authentication on UCMDB Server

SAML Authentication Overview

Security Assertion Markup Language (SAML) is an XML-based, open-standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. SAML is a product of the OASIS Security Services Technical Committee.

Using SAML Authentication, UCMDB allows users to access the UCMDB UI based on the authentication assertion received from the Identity Provider (IdP). So, instead of authenticating the user based on the username and password entered on the UCMDB UI login page, the UCMDB server passes the authentication responsibility to IdP and the users automatically log in to the UCMDB UI when a successful response is received from IdP.

When SAML Authentication is enabled, on the UCMDB splash screen a new option is available: UCMDB SAML Login. This allows users to choose in which way the UCMDB UI login will be made:

• the standard way by entering the username and password, or,
• by delegating the authentication responsibility to the Identity Provider and enabling users to log in based on the SAML response received (and so bypassing the login page).

Prerequisites

• Active Directory Domain Services (AS DS) and DNS Service must be installed. A new forest must be set up in AD DS, using default values where applicable.

• The IP address and DNS must be a fixed IP address.

• Active Directory Certificate Services (AD CS) must be installed with the Certification Authority, Certificate Enrollment Web Service, and Certification Authority Web Enrollment role services.

  The Certification Authority and Certification Authority Web Enrollment role services must be configured as follows:

  • The role service setup type is "Enterprise CA"
  • The role service CA type is "Root CA"
  • You must create a new private key, with a validity period of five years

  The Certificate Enrollment Web Service role service must be configured to use the same CA certificate as the Certification Authority and Certification Authority Web Enrollment role services.

• AD FS must be installed, and a Relying Party Trust must be added as follows.

  Important If you enable SAML on both UCMDB Server and standalone CMS UI, you must add a separate Relying Party Trust for both.

  • When prompted, do not specify an optional token encryption certificate

  • Select a profile that uses the SAML 2.0 protocol, and set the AD FS URL as the relying party SAML 2.0 SSO service URL

  • Set the UCMDB Server URL as the relying party trust identifier

  • Use the default access control policy settings

  When the Relying Party Trust is created, configure it as follows:

  • Add a WS-Federation Passive Endpoint that uses the UCMDB Server URL as the trusted URL and that uses POST binding

  • Add a SAML Assertion Consumer Endpoint that uses <UCMDB Server URL>/ucmdb-ui/login_page.jsp?samlLogin as the trusted URL and that uses POST binding

  • Add a SAML Assertion Logout Endpoint that uses <UCMDB server URL>/ucmdb-ui/logout.jsp?samlLogout as the trusted URL and that uses POST binding

  • Add the following three claim rules:

    • Show user login name in Common Name attribute in SAML response

    • Show user group list in Group attribute in SAML response

    • Show user login name in NameID attribute in SAML response

  Update AD FS to use the SHA-1 secure hash algorithm.

• The AD FS server system clock must be set to a time later than that of the UCMDB Server or CMS UI server. If this is not the case, you must set a time skew to offset the time difference when you update the saml_configuration.properties file when you enable SAML authroization.

Enable SAML login and logout on UCMDB Server

To enable SAML login and logout on UCMDB Server, follow these steps:

1. Import the IdP certificate to UCMDB Server truststore.

   1. Copy the IdP certificate to the following directory on UCMDB:

      <UCMDB_Server>\conf\security

      For example, C:\UCMDB\UCMDBServer\conf\security.

   2. Run the following command:

      C:\UCMDB\UCMDBServer\bin\jre\bin\keytool.exe -import -v -keystore C:\UCMDB\UCMDBServer\conf\security\server.truststore -file <certificate> -alias <certificate alias>

   3. Enter the UCMDB Server Truststore password.

   4. When asked Trust this certificate?, press Y and then Enter.

   5. Make sure the output Certificate was added to the truststore.

2. The SAML logout request must be signed before it is sent to the IdP. Therefore, you must import your own private key into <UCMDB_Server>/conf/server.keystore, and then import the public key into the IdP (for example, in AD FS, do this in the Signature tab of Relying Party Trust in the AD FS Management tool).

   If you want to use the out of box certificate, follow these steps:

   1. Run the following command as an Administrator:

      <UCMDB_Server>\bin\jre\bin\keytool.exe -export -alias hpcert -keystore server.keystore -rfc -storepass hppass -file hpcert_public.cer

   2. Copy the <UCMDB_Server>/conf/hpcert_public.cer file to an IdP folder.
   3. Import the hpcert_public.cer file into the IdP (for example, in AD FS, do this in the Signature tab of Relying Party Trust in the AD FS Management tool).

3. Set SAML authentication as described in the table below via the JMX Console in the UCMDB:service=SAML Authentication Configuration Services category.

   Make sure you set all mandatory fields required for a valid SAML authentication.

   JMX Method (* mandatory if SAML enabled)	Description
   * setSamlAuthentication	Enables or disables SAML authentication. Setting Is enabled to True enables SAML authentication. Null for true if not specified.
   * setIDPEndpointForSAMLAuthen- tication	Sets the IDP Endpoint used in SAML Authentication, mandatory field if SAML Authentication is enabled. To this endpoint the SAML Authentication Request will be sent. Example: https://something.domain.local/adfs/ls
   setIdpCertificateAlias	Sets the IdP certificate alias that will be searched in server truststore. This certificate will be used to validate the response received from IdP. If no certificate alias was configured, by default the certificate with samlCertif alias will be searched. If another alias is set instead of the default one (samlCertif), then this alias must be set using this JMX method.
   * setSAMLClaimTypeContaining- UserName	Sets the SAML UserName claimType containing user's login name, mandatory field if SAML Authentication is enabled. Example: http://schemas.xmlsoap.org/claims/CommonName
   setSAMLClaimTypeContaining- UserCustomer	Sets the SAML Customer claimType containing customer selected username for login, optional field if SAML Authentication is enabled (if not set, the default customer will be used).
   setSAMLAuthSyncGroups	Setting Sync groups to True enables IdP authenticated users to be automatically added to the UCMDB Groups that exist in both UCMDB and the user's groups list received in the SAML Group Claim response. The User's groups claimType parameter in this JMX method also allows you to configure the claimType that contains users' groups in SAML response. At least a default group should be configured to make sure the users will be able to access the UCMDB UI.
   * setSamlUserDefaultGroup	Sets the UCMDB Default Group, in which the user should be automatically added in case the Sync groups option is set to False or no user group has been received from IdP or the user groups received from IdP do not exist in UCMDB. Important The users authenticated through SAML will be automatically added to the default group configured in JMX. If the UCMDB Default Group does not exist in UCMDB or is not configured, then the users will not be able to log in to UCMDB UI.
   * setAuthRequestIssuer	The SAML Request Issuer (service provider – UCMDB Server as it is configured in ADFS)
   * setSamlResponseIssuer	The issuer from which the SAML response is expected. This value is case sensitive. In AD FS, you can find this value in the Federation Service identifier field of the Federation Service Properties. Example: http://something.domain.local/adfs/services/trust
   retrieveSAMLAuthenticationConfi- gurations	Lists the current SAML authentication configurations. The values listed by this method are not taken from the settings (these are the settings already configured when the UCMDB Server has been last restarted).
   retrieveSAMLAuthenticationConfig- urationsFromSettings	Lists the current SAML authentication configurations. The values listed by this method are taken from the settings (these are the settings configured after the UCMDB Server has been last restarted). These settings are the ones that should be used (since they are the latest ones configured), and if these are different from the retrieveSAMLAuthenticationConfigurations listing, then the UCMDB Server should be restarted (the values are reloaded only on reboot).
   * setSamlLogoutCertAlias	The certificate alias that is used to sign the SAML Logout Request. By default, the method uses an OOB certificate that is available for testing purposes.
   setSamlTimeSkew	Sets the system clock time skew between the Admin UI server and the AD FS server (measured in seconds). By default, the value of this method is 0.

4. Create a group with permissions in UCMDB Server. The group must have the same name as the value of the setSamlUserDefaultGroup JMX method.

   To do this, in UCMDB Server, click Security > Users and Groups, and then create a group and assign it the desired role (for example, SuperAdmin).

5. Configure LW-SSO. To do this, follow these steps:

   1. In UCMDB Server, open JMX Console and search for "setDomain".

   2. Set the value of the method to the domain name of your environment, and then click Invoke.
   3. In JMX Console, search for "setEnabledForUI", and then click Invoke.

   4. In JMX Console, search for "retrieveLWSSOConfiguration", click Invoke, and then check that the value of the "mam.server.sso.is.enabled" setting is "true" and that the value of the "mam.server.sso.domain" setting is your environment domain name.

6. Restart UCMDB Server.

SAML Authentication Log

cmdb.samlAuthentication.log

This log file contains all log information related to SAML Authentication. The generated log file is located in the <UCMDB_Server>\runtime\log folder. By default, the log level is to set to DEBUG. You can change the log level in the conf/log/cmdb.properties file by updating the following line:

samlAuthentication= DEBUG

For more details about this log, see UCMDB Log Files.

SAML Authentication and LW-SSO

When SAML authentication is enabled, enabling LW-SSO for UCMDB UI allows the users to log in to CMS UI (UCMDB Browser in the previous release) based on the SAML authentication by using the LW-SSO cookie created when the users logged in to UCMDB UI.

In this scenario, the users are first authenticated by IdP when they want to log in to UCMDB UI. After the response from IdP is validated, the users are logged in to UCMDB UI and also the LW-SSO token is created. When the users want to open the CMS UI, the LW-SSO cookie is found and the login is made based on this.

ADFS Server Specific Configuration

When configuring the UCMDB Service Provider as a Relying Party Trust in the ADFS (Active Directory Federation Services) server, the endpoint for SAML Assertion Consumer must be set as follows:

<protocol>://<UCMDB_SERVER:PORT>/ucmdb-ui/login_page.jsp?samlLogin

For example,

https://ucmdb.mydomain.net:8443/ucmdb-ui/login_page.jsp?samlLogin

Related Topics

Troubleshoot SAML Authentication

Enable SAML Authentication on CMS UI