SAML Single Sign-On (SSO) Authentication for Key Manager

You may set up SAML Single Sign-On (SSO) for Key Manager administrators. This allows users with valid SAML logins to access the Key Manager GUI without needing additional credentials.

Setting Up SAML SSO

1. Run the following to install the required packages to all Key Manager front-ends that you want to enable SAML authentication on:

   ~# yum install libffi-devel xmlsec1 xmlsec1-openssl

2. Configure Key Manager as a Service Provider in your Identity Provider. Allow HTTP POST and HTTP Redirect for SAML binding. Consult your vendor documentation for more instructions about configuring your Identity Provider.

   The SAML2 endpoint in Key Manager is the following. Note that the end slash is required:

   /accounts/saml2/acs/

   Your IdP must provide the following attribute statements for matching Key-Manager accounts:

   • Statement matching Key Manager users' username

   • Statement matching Key Manager users' email

   • Assertion Consumer Service URL as POST: /api/provider/saml2/acs

   note

   The attributes passed by the Identity Provider need to be signed, and the SAML response must not be encrypted.

   Establish a trust relationship between your Identity Provider and Key Manager: export the TLS signing certificate from your Identity Provider and add it to the trusted certificates on all Key Manager front ends that will use SAML authentication.

3. Configure the SAML SSO settings in Key Manager.

   Navigate to Settings→General→Authentication and set the SAML Attribute mapping in the following format:

   {ukm_attribute1:attribute_statement1,ukm_attribute2:attribute_statement2,...}

   You must provide a mapping for the Key Managers users' username, or email.

   For example, if the IdP sends the attribute statement username for matching the Key-Manager-account username, specify:

   {"username":"username"}

   Alternatively, if the IdP sends the attribute statement mail for matching the Key-Manager-account email:

   {"email":"mail"}

   You may optionally map the fields firstname and lastname. Neither of these are required, but can be used for informational purposes.

   note

   The mapped value must uniquely define users in Key Manager. SAML authentication is denied if any mapped attribute corresponds to more than one Key Manager account.

Navigate to System→Management Servers and edit the Settings of each Key Manager front end where you want to enable SAML:

• Set the Entity ID that the Identity Provider will use to recognize Key Manager.

• Key Manager also needs XML formatted metadata from the Identity Provider. Either provide the SAML metadata automatic configuration URL or SAML metadata local file location. If both metadata settings are provided, the local setting takes precedence. If a local file is used, ensure the user sshmgr has read permission to it. We recommend the local file is stored in the sshmgr home directory at /var/lib/sshmgr.

4. Optional: You may allow users to log in using SAML without having to manually create the corresponding Key Manager accounts. To set this up, :

   i. Set the Identity Provider to send the groups attribute statement in the SAML assertion. The groups statement will be used to give Key Manager roles to the newly created user accounts.

   ii. In Key Manager GUI navigate to Settings→General→Authentication, and edit the following settings:

   • SAML Allow creation of new users: Set to Yes.

   • SAML role mapping: Grant Key-Manager roles to user groups. For example:

     {
         "CN=ukmadmins,DC=example,DC=com":["Administrator","API User"],
         "CN=ukmuser,DC=example,DC=com:["Deployers"]
     }

     In the previous example, the user group ukmadmins is mapped to the Key Manager roles Administrator, and API Users; and the user group ukmuser is mapped to the Key Manager Deployers role.

   • SAML attribute mapping: Add a mapping for the groups found in the SAML assertion, like in step 3 previously. Example:

     {"username":"userPrincipalName","email":"email","groups":"memberof"}

     note

     Key Manager AD users' username is always mapped to UPN. To prevent duplicate accounts, the same "username":"userPrincipalName" mapping should be used if such accounts are also imported via SAML.

Testing SAML SSO

You can test your SAML-SSO setup as follows:

1. Create a local Key Manager account that satisfies either of the following, depending on your SAML attribute mapping:

   • Username for matching username statements.

   • Email for matching email statements.

2. Access the Key Manager login page and click SAML Single Sign On. You will be required to authenticate against your IdP.

   Upon successful login you will be logged into Key Manager, as the previously-created user.

Troubleshooting SAML Setup

In case of issues related to SAML authentication, you may gain additional information about potential causes as follows:

• If the SAML Single Sign On button is missing from the Key Manager login page, ensure that the Entity ID is set for that front end. Note that this setting must be configured separately for each front end where SAML support is needed.

• To see what the SAML assertion includes, consider using a browser extension that traces SAML requests. This can be particularly useful for confirming what your IdP sends to Key Manager.

• Ensure using browser-developer tools that the request sent to /accounts/saml2/acs is of POST type.

• For detailed logs about SAML authentication, run the following on the front end where SAML is being

  # supervisorctl tail -f fronted