Configure LDAP Authentication

This section describes how to configure Conjur to use LDAP Authentication.

It is important to complete all the steps in the order they are described.

Step 1: Configure the LDAP connection and filter information

This step configures Conjur to connect to an LDAP server. It sets both connection information and the filters used to search the directory for valid users.

The method of configuration differs depending on the Conjur version, as follows: 

Version

Configuration method

v5.1.1 and below

Environment variables contain the configuration settings.

v5.2.3 and above

Security policy contains the configuration settings.

Continue with Step 2: Define an authentication service in policy.

Step 2: Define an authentication service in policy

This step creates and loads a security policy that defines an LDAP Authentication service.

The LDAP authentication service policy declares the following Conjur resources:

  • Creates a name (an id) for the service. The name is in the form <authenticator-type>/<serviceid>. The authenticator-type must be authn-ldap. You choose the serviceid by providing it in policy. For example:

     
    authn-ldap/my-ldap-server
  • Creates a webservice for the authenticator service. By default, the webservice inherits the name of the policy. If you want the webservice to have a different name, you can provide a unique ID for the webservice.

  • Creates a group that will be used to collect all of the users that need to authenticate using this authn-ldap service.
  • Gives read and authenticate permission to the group. This is a requirement for authentication.

On the Master, follow these steps: 

  1. Define a policy branch for the LDAP authenticator. The name of the branch name is required as shown here:

     
    - !policy conjur/authn-ldap
  2. Save as a .yml file.

  3. Load this policy under root, using the Client CLI:

     
    conjur policy load -b root -f <file-name>
     
    conjur policy load root <file-name>
  4. Copy and paste the following policy to use as a template: 

  5. Make the following changes to the above template:

    • Change the id.

      The id becomes the service name for this authenticator. This id is used in the CONJUR_AUTHENTICATORS variable, configured later, to list this service as one of the authentication services enabled on Conjur. In this example, the value to add to CONJUR_AUTHENTICATORS is authn-ldap/my-ldap-server.

    • Change the annotation values. The following table describes each annotation.

      This step is required for v 5.2.3 and above

      Annotation key

      Description

      ldap-authn/host

      Required. The hostname for the LDAP server. For example: 

      ldap-authn/host: dc1.cyberarkdemo.com

      If connect_type is SSL or TLS, this must match the host in the server certificate of the LDAP server.

      ldap-authn/port

      Required. The port is typically 389. For example: 

      ldap-authn/port: 389

      ldap-authn/connect_type

      Required for secure connections. Otherwise, defaults to plain. Values are plain, SSL, or TLS. For example:

      ldap-authn/connect_type: tls

      ldap-authn/base_dn

      Required. This is the location in the LDAP Directory tree to start authentication searches. For example: 

      ldap-authn/base_dn: dc=example,dc=org

      ldap-authn/filter_template

      Required. This is a filter template string used to translate a Conjur

      user ID into an LDAP bind expression. The template must include the expression %s which represents the Conjur username provided by the authenticator. For example: 

       
      ldap-authn/filter_template: (&(objectClass=person)(uid=%s))

      For more information and examples, see LDAP Authentication - Overview.

      ldap-authn/bind_dn

      Required. This is the user name for logging into the LDAP Server. For example:

      ldap-authn/bind_dn: cn=admin,dc=example,dc=org

    • The clients group in the policy template will be used to aggregate all user accounts that can use this LDAP authenticator service to authenticate to Conjur. If needed, you may change the group name but take care to follow through with the same change throughout your configuration.

  6. Save as a yml file.

  7. Load this policy under the conjur/authn-ldap policy branch: 

     
    conjur policy load -b conjur/authn-ldap -f <policy-file.yml>
     
    conjur policy load conjur/authn-ldap <policy-file.yml>

Step 3: Load secret variables required for connection

This step is required for v 5.2.3 and above

In v5.2.3 and later, the LDAP authentication policy includes declarations for two Conjur variables. This step loads values into Conjur for the following variables.

Variable name

Description

bind-password

Required. The password for the user identified in the ldap-authn/bind_dn annotation.

tls-ca-cert

Required when the ldap-authn/connect_type annotation is TLS and SSL connection. This is the PEM encoded CA certificate chain. On Windows this may also be called the “Base-64 encoded X.509” format.

This certificate is used to verify the authenticity of the LDAP server certificate. Following is an example:

 
-----BEGIN CERTIFICATE-----
…
<Base64 encoded certificate value>
…
-----END CERTIFICATE-----
  1. Load the value for the LDAP bind password. The following command uses an environment variable to load the password.

     
    $ conjur variable set -i conjur/authn-ldap/my-ldap-server/bind-password -v $LDAP_ADMIN_PASSWORD
     
    $ conjur variable values add conjur/authn-ldap/my-ldap-server/bind-password $LDAP_ADMIN_PASSWORD
  2. Load the TLS CA certificate chain into the tls-ca-cert variable.

     
    # Load the PEM encoded CA certificate chain
     
    $ cat ca.crt | conjur variable set -i conjur/authn-ldap/my-ldap-server/tls-ca-cert
     
    $ cat ca.crt | conjur variable values add conjur/authn-ldap/my-ldap-server/tls-ca-cert
  3. Continue with Step 4: Add groups into the LDAP authentication group.

Step 4: Add groups into the LDAP authentication group

This step adds groups of users to the LDAP authentication clients group you created in the previous step. Only users who are members of the group can authenticate using LDAP.

 

You can aggregate groups of users into a hierarchy, adding groups into larger groups to create the desired membership in the LDAP authentication group.

  1. Copy the following policy as a template: 

     
    - !grant
      role: !group my-ldap-server/clients
      member: !group /all-ldap-users 
  2. Make the following changes to the above template:

    • Make sure the role attribute matches your LDAP group name you declared in step 1. The first part of the name, /conjur/authn-ldap reflects the required policy structure for LDAP authentication and would not change.

    • Change the group name to your aggregated group name for LDAP users. You could alternatively choose to add multiple member statements to include additional groups.

  3. Save as a .yml file.

  4. Load the policy file.

     
    conjur policy load -b conjur/authn-ldap -f <policy-file>
     
    conjur policy load conjur/authn-ldap <policy-file>
  5. Continue with Step 5: Configure Conjur to use the service.

Step 5: Configure Conjur to use the service

This step configures Conjur to use one or multiple authenticator services.

  1. On the Leader , set the CONJUR_AUTHENTICATORS environment variable. This variable lists all of the authenticator services that are enabled for Conjur. It may include other types of authenticators in addition to the LDAP authenticator. If this variable is not set, the Conjur default authenticator, authn, is the only authenticator enabled.

    To set this variable, locate /opt/conjur/etc/conjur.conf on the node, and add the following line:

     
    CONJUR_AUTHENTICATORS="service,service,...."

    The service for LDAP authenticators is authn-ldap/service-id. The service id is set in policy. See Step 2: Define an authentication service in policy.

     

    For Docker only: If you set only the LDAP service, all UI, CLI, and API users are required to authenticate using LDAP credentials. To permit CLI and API users to choose which authentication to use, list both the LDAP Authentication and the Conjur default authenticator (authn). For example: 

    CONJUR_AUTHENTICATORS="authn-ldap/my-ldap-server,authn"
  2. On the Leader , restart the conjur service:

     
    $ sv restart conjur
  3. Continue with Step 6: Configure the Conjur UI to use the service.

Step 6: Configure the Conjur UI to use the service

This step configures the Conjur UI to authenticate using the LDAP authenticator service. Perform this step on the Leader node and on all Follower nodes where the UI is used.

  1. On the Leader, set CONJUR_AUTHN_URL. You already set CONJUR_AUTHENTICATORS on the Leader in the previous step.

  2. On each Follower, set both CONJUR_AUTHN_URL and CONJUR_AUTHENTICATORS.

    The following table describes the two variables.

    Variable

    Description

    CONJUR_AUTHENTICATORS

    This variable enables authentication services that are defined in policy. The variable lists all of the authenticator services that you want to enable for the appliance. If this variable is not set, the Conjur default authenticator, authn, is the only authentication in use.

    To set this variable, on each Follower, locate /opt/conjur/etc/conjur.conf, and add the following line: 

     
    CONJUR_AUTHENTICATORS="service,service"

    The service for LDAP authenticators is authn-ldap/service-id. The service id is set in policy. See Step 2: Define an authentication service in policy.

    For example:

     
    CONJUR_AUTHENTICATORS="authn-ldap/my-ldap-server,authn"

    CONJUR_AUTHN_URL

    This variable configures the API in the UI to use the desired authenticator instead of the default.

    To set this variable, on the Leader and each Follower, edit /opt/conjur/etc/ui.conf.

     

    This is a different file from the one used above for CONJUR_AUTHENTICATORS.

    Add the following line: 

     
    CONJUR_AUTHN_URL="http://localhost/authn-ldap/<service-id>"

    For example:

     
    CONJUR_AUTHN_URL="http://localhost/authn-ldap/my-ldap-server"

    The setting to localhost is required and refers to the UI accessing the Conjur Server within the same node. For more information, see the API documentation here: https://www.conjur.org/api.html#authentication

  3. On each node where you changed CONJUR_AUTHENTICATORS, restart the node services for the change to take effect.

     
    sv restart conjur
  4. On each node where you changed CONJUR_AUTHN_URL, restart the UI service for the change to take effect:

     
    sv restart conjur/ui
  5. Continue with Step 7: Verify configuration.

Step 7: Verify configuration

This section describes how to verify that LDAP authentication is working.

  1. Try to log into the Conjur UI with a Conjur account that is not in LDAP. The login should be rejected.

  2. Try to log into the Conjur UI with an LDAP user account and password. The login should be successful.

 

When LDAP authentication is configured on a node (the master node or a follower), all users of the Conjur web interface on that node must use their LDAP passwords to log in. The default Conjur authentication (passwords and API keys set in Conjur no longer works for the Conjur UI on that node.