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.

Environment variables inside the Conjur node define the connection and filter information. The recommended way to provide the environment variable settings is to set the values in a configuration file on the node. In a high-availability cluster, this configuration is required on every node in the cluster, including Leader and Standbys, and also on all Followers. 

  1. In each Conjur node, edit the following file:

      
    /opt/conjur/etc/conjur.conf

  2. Add environment variables into the file. The following table describes the variables.

    Variable name

    Description

    LDAP_URI

     

    Required. Construct a properly formatted URI. This is the connection information for the LDAP server. For example: 

    LDAP_URI=ldap://dc1.cyberarkdemo.com:389

    LDAP_BASE

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

    LDAP_BASE=dc=cyberarkdemo,dc=com

    LDAP_FILTER

    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 a Conjur username provided by the authenticator. For example: 

    'LDAP_FILTER=(sAMAccountName=%s)'

    For more information and examples, see The LDAP filter template.

    LDAP_BINDDN

    Required. This is the user name to use to log into the LDAP Server. For example:

    'LDAP_BINDDN=CN=Conjur Bind,OU=Vault Bind & ScanAccounts,OU=CyberArk,DC=CyberArkDemo,DC=com'

    LDAP_BINDPW

    Required. This is the password for the Bind user.

    Provide the string here or use an environment variable on the host platform to pass in the value. For example: 

    LDAP_BINDPW=Cyberark1

  3. Save the conf file.

  4. Restart the conjur service:

    To restart the service, stop and restart the Conjur containers on the host server.

  5. Repeat the process on each server that Standby or Follower nodes.

    On each server: 

    1. Prepare the conf file using the same environment variable values.

    2. Restart the conjur service:

      To restart the service, stop and restart the Conjur containers.

Change connection values

If needed, you can change the connection or filter values in all of the conf files. To implement the changes, restart the conjur service on every Conjur node.

Alternate method:  using -e arguments with the docker run command

An alternate method of providing the environment variable settings is to use the -e flag on the docker run command that creates the container. This method is acceptable for test situations. However, it presents a challenge if you need to change the configuration settings later. Changing the settings would require a backup and restore operation in conjunction with creating new containers.

Here is an example of a startup command that sets the required variables:

  
docker run --name conjur -d --restart=always 
--security-opt seccomp=unconfined
-v /opt/conjur/backup:/opt/conjur/backup -p 443:443 -p 5432:5432 -p 1999:1999 
-e LDAP_URI=ldap://dc1.cyberarkdemo.com:389 
-e LDAP_BASE=dc=cyberarkdemo,dc=com 
-e 'LDAP_FILTER=(sAMAccountName=%s)' 
-e 'LDAP_BINDDN=CN=Conjur Bind,OU=Vault Bind & Scan Accounts,OU=CyberArk,DC=CyberArkDemo,DC=com' 
-e LDAP_BINDPW=Cyberark1

The LDAP Authentication policy defines the connection and filter information. The policy includes annotations that contain the configuration values.

The next section, Step 2: Define an authentication service in policy, describes how to create the policy and set the annotation values.

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>

  4. Copy and paste the following policy to use as a template: 

      
    - !policy
  id: my-ldap-server
  body:
  - !host
  - !webservice
    owner: !host

  - !group clients

  - !permit
    role: !group clients
    privilege: [ read, authenticate ]
    resource: !webservice
      
    - !policy
  id: my-ldap-server
  body:
  - !host
  - !webservice
    owner: !host
    annotations:
      ldap-authn/base_dn: dc=example,dc=org
      ldap-authn/bind_dn: cn=admin,dc=example,dc=org
      ldap-authn/connect_type: tls
      ldap-authn/host: ldap-server
      ldap-authn/port: 389
      ldap-authn/filter_template: (&(objectClass=person)(uid=%s))

  - !group clients

  - !permit
    role: !group clients
    privilege: [ read, authenticate ]
    resource: !webservice

  - !variable
    id: bind-password
    owner: !host

  - !variable
    id: tls-ca-cert
    owner: !host
     

    The values in the annotations above are for example only and should be updated for your environment and LDAP server details.

  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>

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

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

  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.