Setting Up Active-Directory Access to Key Manager

Key Manager supports active-directory (AD) access. This allows existing AD users to log in to Key Manager, and to perform management tasks using Key Manager. This section instructs how to set up access to Key Manager for your AD users.

Setting up AD access involves the following procedures:

1. Set up TLS certificates on the Key Manager front ends

2. Configure Key Manager to connect to the AD server (One time only)

3. Grant Key Manager permissions for certain AD groups.

Setting up AD access is an optional procedure for setting up a Key Manager deployment. It is also possible to provide access to the Key Manager system using Key Manager accounts.

We recommend readers to familiarize themselves with Key Manager accounts, roles, and permissions, before reading this chapter. For more information about these subjects, see the Administrator Manual.

Prerequisites

Before you set up Key Manager to use AD, you must have set up a functioning Key Manager deployment. A minimal functioning Key Manager deployments consists of the following system components:

• One Key Manager Database

• One Key Manager Server that runs the Key Manager back end

• One Key Manager Server that runs the Key Manager front end

For instructions about setting up the required system components, see Setting Up Key Manager Servers.

TLS Setup for AD Connections

Key Manager front ends need to be configured to connect to your AD server(s) using TLS-secured connections. To enable TLS for AD connections, do the following on all of your Key Manager front ends:

1. Gain root terminal access to the Key Manager front end.

2. Set the CA certificate of the AD server as a trusted certificates on the Key Manager front end. This is done by copying the CA certificate of the AD server to the following path on the Key Manager front end:

   /etc/adauth-ca.crt

   When using multiple AD servers, the /etc/adauth-ca.crt file must contain the CA certificates of all the AD servers.

   note

   If your AD server provides its intermediate-CA certificates during connections, then it is sufficient to just add the trusted root-CA certificate to /etc/adauth-ca.crt. Otherwise, you must add the CA certificate of the AD server, and the entire CA-certificate chain up to a trusted root CA.

Configuring Key Manager to Connect to the AD Server

To provide access to Key Manager for AD users, you must first allow Key Manager to connect to the AD server.

To do this, perform the following configurations via the Key Manager GUI:

1. On the Settings→Active Directories page, and click on Create a New LDAP Domain. Specify the settings as appropriate for your AD server. The required settings are the following:

   • Domain name: The active-directory domain name.

   • LDAP connection URLs: The address of the AD service. For example, ldaps:// ad.example.com:636/, or ldap://ad.example.com:389/ (using STARTTLS for non-LDAPS addresses). To specify multiple AD service addresses, separate each entry with a space. For example:

     ldaps://ad.example.com:636/ ldap://ad.example.com:389/

   • Distinguished name used to do initial bind to fetch data with: The distinguished name of the AD user used for connecting to the AD server. For example, johndoe@ad.example.com

     note

     The bind user should not have administrator privileges, read privileges are enough.

   • Password used to do initial bind to fetch data with: The password of the above AD user.

   • LDAP Query for groups mappable to roles: The ldapsearch-equivalent filter matching to group objects. By default this is (objectClass=group)

   • Distinguished name for the PrivX Key Manager administrator's group (Optional): A filter that matches to a group. Only the members of this group may be used for performing actions in the Key Manager system. For example: CN=UKM Administrators,CN=Users,DC=ad,DC=example,DC=com.

   After you have specified the settings, click Confirm to save the settings.

2. On the Settings→General page, under the Authentication settings section, specify the following AD settings:

   • Active Directory domain name: Select the AD you want to use for Key Manager user authentication. Note that only one AD at a time can be used for Key Manager authentication.
     note

     Changing the active AD could prevent users from logging in to Key Manager. For more information see Changing Active AD.

   • Validate Active Directory server certificates: If set to Yes, connections are established only if the AD certificate is valid and trusted. If set to No, connections are allowed even if the AD certificate is invalid.

   For each modified setting, click the associated Apply button to save the changes.

3. Optional: You may test your AD settings by running a ldapsearch command from the Key Manager front end.

   Verify that you have the necessary packages for running ldapsearch, and install them if necessary:

   # yum install openldap-clients

   Test your settings with a command similar to the following:

   # ldapsearch -M -LLL -D initial_bind_user -H ldap_url -b base_dn \
   -W -s sub '(&(group_query)(memberof=admin_group_dn)'

   In the example command, replace the placeholder values with the AD settings you specified:

   • initial_bind_user: Distinguished name used to do initial bind to fetch data with.

   • ldap_url: LDAP connection URL.

   • base_dn: Base distinguished name for all objects.

   • password: Password used to do initial bind to fetch data with.

   • (group_query): LDAP Query for groups mappable to roles.

   • admin_group_dn: Distinguished name for the PrivX Key Manager administrator's group.

   Full example:

   # ldapsearch -M -LLL -D johndoe@ad.example.com -H ldaps://ad.example.com:636 \
   -b 'DC=ad,DC=example,DC=com' -W -s sub \ '(&(objectClass=group)\
   (memberof=CN=UKM Administrators,CN=Users,DC=ad,DC=example,DC=com))'

   If your AD settings are correct, the command returns a list of the sub groups and users that belong to the Key Manager administrators group.

   note

   If you are using STARTTLS connections, or in other words, if you are connecting using a non-ldaps URL, add the -ZZ option to the ldapsearch command.

User groups in the AD should now be imported to Key Manager. You can verify this as follows:

1. On the Accounts→Roles page, click Create New Role to display the role-creation dialog.

2. In the role-creation dialog, display the Active domain group drop-down menu. If the Active domain group menu displays the groups and the users that are part of your Key Manager administrator AD group, you have successfully configured Key Manager to connect to your AD server. If the Active domain group drop-down menu is empty, or otherwise displays wrong information, verify that you have provided the correct AD settings, and then run this test again.

Users belonging to imported AD groups do not initially have any permissions to the Key Manager system, which means that users in AD groups cannot initially perform any actions in the Key Manager system (not even log into the GUI). For information about granting permissions to AD groups, see Granting Key Manager Permissions to AD Groups.

Granting Key Manager Permissions to AD Groups

You must grant Key Manager permissions to AD users, before they can be used to perform operations using Key Manager. This is achieved by mapping Key Manager roles to AD groups.

To map an existing Key Manager role to AD groups:

1. Access the Key Manager GUI using a web browser. Log in with an account that has the permissions to Edit site configuration.

2. On the Accounts→Roles page, click the role you want to map to AD groups.

3. Provide the name of the AD group in Active Domain Groups.

4. Click Save to apply the changes.

Changing Active AD

You can change the AD used for Key Manager user authentication.

In Key Manager GUI, navigate to Settings→Authentication, select a new AD from the Active Directory domain name list, and click Apply.

note

Changing the active AD could prevent users from logging in to Key Manager. Make sure the new AD has a group for Administrator Role users with the same name as the old AD, and all the users intended for Key Manager access are found in that group. Alternatively, you can log in to the Key Manager after the change using the superuser account, and change the Role mapping on Accounts→Roles page to map a new AD group to the Administrator Role.

After you have changed the selected AD, configure additional AD settings on the Settings→Active Directories page to finalize AD setup as instructed in Configuring Key Manager to Connect to the AD Server.

Troubleshooting AD Setup

This section describes some of the common problems and solutions of AD setup.

In some situations, Key Manager fails to update the AD settings until the Key Manager front ends have been restarted. If you are experiencing issues with your AD setup, try restarting your Key Manager front ends by running the following command on all the Key Manager front ends:

# supervisorctl restart frontend

If the problem persists, consider trying some of the following solutions.

Symptom: Socket SSL wrapping error: [SSL: CERTIFICATE_VERIFY_FAILED]

This error may be encountered upon updating your settings on the Settings→Active Directory page.

• This error indicates that the AD-certificate chain configured for the Key Manager front end does not validate the server certificate provided by the AD server. AD connections fail automatically because the AD server cannot be trusted.

  1. Verify the contents of the AD-certificate file against the certificates that are presented by the AD server. You can display the AD server certificates with a command similar to the following (replace ldaps://ad.example.com:636 with the address of your AD service):

     # openssl s_client -showcerts -connect ldaps://ad.example.com:636

     The AD certificate used by the Key Manager front end is located at /etc/adauth-ca.crt

  2. After the Key Manager front ends are restarted, ensure that the settings on the Settings→Active Directory page are valid, then click Update to retry connecting to the AD.

Symptom: Socket SSL wrapping error: Hostname does not match

This error may be encountered upon updating your settings on the Settings→Active Directory page.

• Ensure that the AD service names (defined in the LDAP connection URLs setting on the Settings→Active Directory page) match the Common Names (CN) specified in the AD server certificate.

  You can acquire the CN provided in your AD server certificate with a command like the following (replace ldaps://ad.example.com:636 with the address of your AD service):

  # openssl s_client -showcerts -connect ldaps://ad.example.com:636

  In the command output, look for the CN under the first entry in the Certificate chain section, which looks somewhat similar to the following:

  ---
   Certificate chain
    0 s:/C=US/ST=California/L=Mountain View/O=Example/CN=ad.example.com
      i:/C=US/O=Google Inc/CN=Google Internet Authority G2
    1 ...
   ---

  Change the LDAP connection URL setting, then click Update to verify whether the error has been fixed.

  note

  If your AD server has multiple addresses, be sure to use the address specified in the certificate.

  Quite often, certificates may only be valid for the FQDN or the IP address of a host (not for both). For example, if the certificate is valid only for the domain of the AD server, connections using the equivalent IP address will fail.

Symptom: Key Manager is unable to connect to the AD server

• On the Settings→Active Directory page, ensure that you have provided valid credentials in the settings Distinguished name used to do initial bind to fetch data with, and Password used to do initial bind to fetch data with. Update the settings to verify whether the problem was resolved.

• Ensure that the Key Manager front end machines have network connectivity to the AD server. You can use the commands ping and telnet to verify this (replace the example addresses and port numbers with those of your AD server):

  # ping ad.example.com

  # telnet ad.example.com 636

  If you can ping the AD server, but are unable to telnet to the AD service, check the firewall settings on your AD server. If you can ping and telnet to the AD server/service, then verify your certificate settings according to the troubleshooting topic Symptom: Socket SSL wrapping error: [SSL: CERTIFICATE_VERIFY_FAILED]

Symptom: Loading failed when displaying Active domain groups

This error may be encountered when setting roles and permissions for AD groups and users (after you have successfully configured Key Manager to connect to the AD server).

• Configure the AD query parameters so that only Key Manager administrator groups and members are returned.

  Verify that you have the necessary packages for running ldapsearch. Install them if necessary:

  # yum install openldap-clients

  Test your settings with a command similar to the following:

  # ldapsearch -M -LLL -D initial_bind_user -H ldap_url -b base_dn \
       -W -s sub '(&(group_query)(memberof=admin_group_dn)'

  Full example of the command:

  # ldapsearch -M -LLL -D johndoe@ad.example.com -H ldaps://ad.example.com:636 \
       -b 'DC=ad,DC=example,DC=com' -W -s sub \ '(&(objectClass=group)\
       (memberof=CN=UKM Administrators,CN=Users,DC=ad,DC=example,DC=com))'

  Update your AD settings, then restart the Key Manager front ends. After this, verify whether the issue was resolved by adding roles for AD users.

Symptom: After changing the AD, the administrators can not log in to Key Manager

Key Manager searches the Active Directory set in Settings→General→Authentication for groups. The Administrator role has the group mapped to it in Accounts→Roles as explained in Granting Key Manager Permissions to AD Groups.

You must make sure the new AD has a group set for Administrator use with the same group name as the old one. All users who are inteded to have Key Manager access need to be found from this group.

Alternatively, you can log in to the Key Manager with the superuser account, and change the Role mapping on Accounts→Roles page to map a new AD group to the Administrator Role.

If you want to restore a removed AD, make sure that the AD you want to restore is selected as the active one in Active Directory domain name setting on the Settings-Authentication page, re-map the role mappings manually, and restore the application owner mapping ldap_domain field using the command- line like in the following example:

# ssh-mgr-client modify-application-owner-mapping -i l ldap_domain=EXAMPLE_AD

Symptom: Log in to User Portal using AD takes minutes

An error in setting up AD for Key Manager may cause excessive login time in User Portal. To make sure login works correctly, verify that your AD setups are correct in both Key Manager and User Portal. For more information about User Portal and AD, see the PrivX Key Manager User Portal Manual.