Use > Hardening > Universal CMDB Login Authentication > Enabling Login to Universal CMDB with SAML

Enabling Login to Universal CMDB with SAML

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).

Note

  • Currently, the SAML authentication supports UCMDB UI login only. (UCMDB Browser login is not supported.)

  • The SAML version used is SAML 2.0.

  • This functionality has been verified with ADFS 3.0 as Identity Provider.

Enable SAML Authentication on UCMDB Server

To enable SAML Authentication on UCMDB Server, do the following:

  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. 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.

    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).

  3. Restart UCMDB Server.

Important (Multi-customer environment only) Since the Default Group is currently a global setting, in a multi-customer environment, the Default Group must be updated on each customer with the desired roles (the roles assignment are customer-dependent). Once this is done and the Customer claimType is set in JMX console, the IdP authenticated user will be able to log in to UI on the customer received in the SAML Response.

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.

Note For starters, we suggest leaving this log on DEBUG in order to resolve possible problems more easily.

SAML Authentication and LW-SSO

When SAML authentication is enabled, enabling LW-SSO for UCMDB UI allows the users to log in to UCMDB Browser based on the SAML authentication (even though UCMDB Browser does not support SAML Authentication currently) 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 UCMDB Browser, the LW-SSO cookie is found and the login is made based on this.

SAML Authentication and FIPS

There are no additional changes required for enabling SAML Authentication support with FIPS. The only thing important is that the IdP certificate’s alias must be added in lower cases into the server-fips.trustore file (in the <UCMDB_Server>\conf\security folder).

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

Send Help Center feedback