Enable SAML Authentication on CMS UI

This topic explains how to set up SAML login and logout on standalone CMS UI. For general information about using SAML with UCMDB and to learn how to set up SAML on the UCMDB server and embedded CMS UI, see Enable SAML Authentication on UCMDB Server

Note

  • The SAML version used is SAML 2.0.

  • This functionality has been verified with Active Directory Federation Services (AD FS) 3.0 as Identity Provider (IdP).

Prerequisites

  • Active Directory Domain Services (AS DS) and a DNS Server 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 <Domain name of the AD FS machine>/ucmdb-browser/login?samlLogin as the trusted URL and that uses POST binding

    • Add a SAML Assertion Logout Endpoint that uses <Domain name of the AD FS machine>/ucmdb-browser/logout?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 authorization.

Enable SAML Login and Logout

To enable SAML login and logout on CMS UI, follow these steps:

  1. Import the IdP certificate to UCMDB Server truststore.

    1. Copy the IdP certificate to the following directory:

      <CMS UI home>\conf

    2. Run the following command to import the certificate alias into the saml_configuration.properties file (<CMS UI home>/conf/saml_configuration.properties):

      <JDK home>\bin\jre\bin\keytool.exe -import -v -keystore <CMS UI home >\conf\security\server.truststore -file <certificate> -alias <certificate alias>

    3. Enter the default password ("hppass").

    4. When asked Trust this certificate?, press Y, and then press 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 <CMS UI home>/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:

      <JDK home>\bin\jre\binkeytool -export -alias hpcert -keystore CMS UI home\conf\server.keystore -rfc -storepass hppass -file <CMS UI home>\conf\hpcert_public.cer

    2. Copy the <CMS UI home>/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. Update the saml_configuration.properties file (<CMS UI home>/conf/saml_configuration.properties) as described in the following table.

    Property Value Example
    mam.server.sso.saml.auth.enabled "true" mam.server.sso.saml.auth.enabled=true
    mam.server.sso.saml.auth.idp "https://<ADFS url>/adfs/ls" mam.server.sso.saml.auth.idp=https://<ADFS url>/adfs/ls
    mam.server.sso.saml.auth.username.claimtype

    "http://schemas.xmlsoap.org/claims/CommonName"

    mam.server.sso.saml.auth.username.claimtype=http://schemas.xmlsoap.org/claims/CommonName
    mam.server.sso.saml.auth.customer.claimtype Leave this property blank. mam.server.sso.saml.auth.customer.claimtype=
    mam.server.sso.saml.auth.groups.claimtype "http://schemas.xmlsoap.org/claims/Group" mam.server.sso.saml.auth.groups.claimtype=http://schemas.xmlsoap.org/claims/Group
    mam.server.sso.saml.auth.sync.groups "true" mam.server.sso.saml.auth.sync.groups=true
    mam.server.sso.saml.auth.default.group

    A group in your UCMDB server. This group should have rights to log in to UCMDB server.

    mam.server.sso.saml.auth.default.group=saml
    mam.server.sso.saml.auth.certificate.alias The certificate alias that you used in step 1.d. mam.server.sso.saml.auth.certificate.alias=token_signing

    mam.server.sso.saml.logout.certificate.alias

    The alias of your own certificate, or "hpcert" if you use the default certificate.

    mam.server.sso.saml.logout.certificate.alias=hpcert

    mam.server.sso.saml.auth.request.issuer The UCMDB server (for embedded) or UCMDB browser (for standalone) URL. mam.server.sso.saml.auth.request.issuer=https://<UCMDB host>:8443/

    mam.server.sso.saml.response.issuer

    The ADFS URL.

    mam.server.sso.saml.response.issuer=http://<ADFS URL>//adfs/services/trust

    mam.server.sso.saml.time.skew

    The desired time skew (in seconds) between the AD FS and UCMDB hosts.

    mam.server.sso.saml.time.skew=60
  4. Create a group with permissions in UCMDB Server. The group must have the same name as the value of the "mam.server.sso.saml.auth.default.group" setting.

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

    Note This step is only required if you have not already enabled SAML on UCMDB Server.

  5. Create a configproperties.txt file. To do this, follow these steps:

    1. Open the <CMS UI home>\conf directory, delete the configproperties.bin file, and then create a configproperties.txt file.
    2. Open the configproperties.txt file, and then enter the following lines:

      truststorepassword=hppass
      keystorepassword=hppass
    3. Save the configproperties.txt file.

  6. Configure LW-SSO. To do this, follow these steps:
    1. In UCMDB Server, open JMX Console and search for "retrieveLWSSOConfiguration".

    2. Select Invoke, and then make a note of the value of the "mam.server.sso.init.string" setting.

    3. Open the <CMS UI home>\conf directory, and open the ucmdb_browser_lwsso_config.xml file.

    4. Update the value of the initString parameter in the file with the value that you noted from the "mam.server.sso.init.string" setting, as follows:

      <lwssoValidation id="ID000001">
      <domain>ucmdb browser domain name</domain>
      <crypto cipherType="symmetricBlockCipher"
      engineName="AES" paddingModeName="CBC" keySize="256"
      encodingMode="Base64Url"
      initString="Replace this value"></crypto>
      </lwssoValidation>
  7. Restart CMS UI.

Example Active Directory Installation and Configuration

The following procedure demonstrates how to install and configure the various Active Directory components in order to set up an IdP to use with SAML authentication.

1: Install AD DS and a DNS Server

  1. Open Windows Server Manager, and then select the Add roles and features link in the main panel to start the Add Roles and Features wizard.

  2. On the Installation type page, select the Role-based or feature-based installation option, and then select Next.
  3. On the Server Selection page, select the Select a server from the server pool option, select the local machine from the list, and then select Next.

  4. On the Server Roles page, select the Active Directory Domain Services and DNS Server options, and then select Next.
  5. On the Features page, select Next to accept the default values.
  6. On the AD DS page, select Next to accept the default values.
  7. On the DNS Server page, select Next to accept the default values.
  8. On the Confirmation page, select Install. When the wizard has installed AD DS and the DNS server, select Close to exit the wizard.

2: Configure AD DS

  1. Open Server Manager, and then select the Post Deployment Configuration task notification.
  2. On the Deployment Configuration page, select the Add a new forest option, enter a domain name in the Root domain name field, and then select Next.
  3. On the Domain Controller Options page, select the functional level of the forest and domain, enter a password for Directory Services Restore Mode, and then select Next.
  4. On the DNS Options page, select Next without selecting any options.
  5. On the Additional Options page, select Next to accept the default values.
  6. On the Paths page, select Next to accept the default values.
  7. On the Review Options page, select Next, and then select Install. The wizard automatically restarts the server after installing the forest.

3: Set the IP address and DNS address

Open Network and Sharing Center, and make sure that the local machine's IP address and DNS address are both static.

4: Install Active Directory Certificate Services

  1. Open Server Manager, and then select the Add roles and features link in the main panel to start the Add Roles and Features wizard.
  2. On the Server Roles page, select the Active Directory Certificate Services option, and then select Next.
  3. On the Features page, select Next to accept the default values.
  4. On the AD CS page, select Next.
  5. On the Role Services page, select the following options, and then select Next:
    • Certification Authority
    • Certificate Enrollment Web Service
    • Certification Authority Web Enrollment
  6. On the Web Server Role page, select Next.
  7. On the Role Services page, select Next to accept the default values.
  8. On the Confirmation page, select Install. When the wizard has installed AD DS and the DNS server, select Close to exit the wizard.

5: Configure AD CS

  1. Open the AD CS Configuration wizard.

  2. On the Credentials page, enter <AD FS domain name>administrator in the Credentials field, and then select Next.
  3. On the Role Services page, select the following options, and then select Next:

    • Certification Authority
    • Certification Authority Web Enrollment

  4. On the Setup Type page, select the Enterprise CA option, and then select Next.
  5. On the CA Type page, select the Root CA option, and then select Next.
  6. On the Private Key page, select the Create a new private key option, and then select Next.
  7. On the Cryptography for CA page, select RSA#Microsoft Software Key Provider as the cryptographic provider. Select SHA1 as the hash algorithm, and then select Next.
  8. On the CA Name page, enter a common name for the CA and a distinguished name suffix, and then select Next.
  9. On the Validity Period page, select 5 years, and then select Next.
  10. On the Certificate database page, enter the certificate database location and the certificate database log location, and then select Next.
  11. On the Confirmation page, select Configure. When the wizard asks you if you want to configure additional role services, select Yes.
  12. On the Credentials page, enter <AD FS domain name>administrator in the Credentials field, and then select Next.
  13. On the Role Services page, select the Certificate Enrollment Web Service option, and then select Next.
  14. On the CA for CES page, select the CA name option, enter the target CA (<domain name\CA name>), and then select Next.
  15. On the Authentication Type for CES page, select the Windows integrated authentication option, and then select Next.
  16. On the Service Account for CES page, select the Use built-in application pool identity option, and then select Next.
  17. On the Server Certificate page, select the certificate that you created in steps 1-11, and then select Next.
  18. On the Confirmation page, select Configure. When the wizard has configured the role service, select Close to exit the wizard.

6: Install AD FS

  1. Open Server Manager, and then select the Add roles and features link in the main panel to start the Add Roles and Features wizard.
  2. On the Server Roles page, select the Active Directory Federation Services option, and then select Next.
  3. On the Features page, select Next to accept the default values.
  4. On the AD FS page, select Next to accept the default values.
  5. On the Confirmation page, select Install. When the wizard has installed AD FS, select Close to exit the wizard.

7: Configure AD FS

  1. Open Server Manager, and then go to Tools > Configure Active Directory Federation Services.

  2. On the Welcome page, select the Create the first federation server in a federation server farm option, and then select Next.
  3. On the Connect to AD DS page, select Next to accept the default value.
  4. On the Specify Service Properties page, enter a display name for the Federation Service, and then select Next.
  5. On the Specify Service Account page, select the Use an existing domain user account or group Managed Service Account option. Enter <AD FS domain name>administrator in the Account name field, enter the password, and then select Next.
  6. On the Specify Database page, select the Create a database on this server using Windows Internal database option, and then select Next.
  7. On the Review Options page, select Next.
  8. On the Pre-requisite Checks page, select Configure when the wizard has finished performing the prerequisite checks. When the wizard has configured AD FS, select Close to exit the wizard.

8: Add and configure a relying party trust in AD FS

Important You must add a relying party trust for both the UCMDB server and for the standalone CMS UI.

  1. Open AD FS 2.0 Management Console, right-click Trust Relationships in the left-hand pane, and then select Add Relying Party Trust to start the Add Relying Party Trust wizard.
  2. On the Select data Source page, select the Enter data about the relying party manually option, and then select Next.
  3. On the Specify Display name page, enter a display name for the relying party trust, and then select Next.
  4. On the Configure Certificate page, select Next without configuring an optional token encryption certificate.
  5. On the Configure URL page, select the Enable support for SAML 2.0 WebSSO protocol option, set the AD FS URL as the relying party SAML 2.0 SSO service URL, and then select Next.
  6. On the Configure Identifiers page, set the UCMDB server URL as the relying party trust identifier, and then select Next.
  7. On the Choose Access Control Policy page, select Next to accept the default values, and then continue to accept the default values until the wizard has finished.
  8. Right-click Relying Party Trusts in the left-hand pane, and then select Properties.
  9. On the Identifiers tab, confirm that the relying party identifier is set to the UCMDB server URL.
  10. Go to the Endpoints tab, and then delete any existing endpoints.
  11. Select Add WS-Federation Passive Endpoints. Enter the UCMDB server URL in the Trusted URL field, and then select OK.
  12. Select Add SAML Assertion Consumer Endpoints. Enter <Domain name of the AD FS machine>/ucmdb-browser/login?samlLogin in the Trusted URL field, select POST in the Binding drop-down list, and then select OK.
  13. Select Add SAML Assertion Logout Endpoints. Enter <Domain name of the AD FS machine>/ucmdb-browser/logout?samlLogout in the Trusted URL field, select POST in the Binding drop-down list, and then select OK.
  14. Select Apply, and then select OK.
  15. Right-click Relying Party Trusts in the left-hand pane, and then select Edit Claim Issuance Policy....
  16. Select Add Rule to start the Add Transform Claim Rule Wizard.
  17. On the Choose Rule Type page, select Send LDAP Attributes as Claims in the Claim rule template drop-down list, and then select Next.
  18. On the Configure Claim Rule page, create the following three rules.

    Claim rule name Attribute store LDAP attribute Outgoing claim type
    UserName Active Directory SAM-Account-Name Common Name
    Group Active Directory Token-Groups - Qualified by Domain Name Group
    NameID Active Directory SAM-Account-Name Name ID
  19. Select Apply, and then select OK.
  20. Right-click AD FS in the left-hand pane, and then select Edit Federation Service Properties.

  21. On the General tab, make sure that the value of the Federation Service identifier field is <AD FS server URL>/services/trust.
  22. Check that the AD FS server system clock is set to a time later than that of the CMS UI server. If this is not the case, you must set a time skew in the saml_configuration.properties file when you enable SAML authorization.

You have now set up the IdP and are ready to enable SAML authentication.

Related Topics

Troubleshoot SAML Authentication

Enable SAML Authentication on UCMDB Server