Configure authentication

Almost all access to Conjur requires authentication. Conjur can authenticate both users and hosts in the form of CLI requests from users, automated requests from hosts using the API, or access to the UI.

This topic describes the authenticators supported by Conjur and the function of service IDs when allowlisting a single type of authenticator or multiple instances of the same authenticator type, each supporting different services.

Authenticator service IDs

A Conjur appliance can also use multiple instances of the same authenticator type. For example, you might have more than one LDAP directory, or more than one Kubernetes cluster or Kubernetes service type. Each instance is a separate service.

To identify each service, append a service ID to the authenticator type throughout the configuration, using the format <authenticator-type>/<opt-service-id>, where opt-service-id is the service ID value. You choose the service ID value and must use it consistently in the following configuration steps.

Some examples of optional service IDs appended to the authenticator type are:

authn-ldap/sysadmins

authn-k8s/GKE

authn-k8s/cluster1

Configure authenticators

This section describes how to configure authenticators.

If your implementation uses only the Conjur default authenticator (authn), no special configuration is required.

Step 1: Create authenticator policy

Except for the default Conjur authenticator, each authenticator/<SERVICE_ID> needs Conjur policy that defines the following:

Creates a webservice for the authenticator/<SERVICE_ID>.
Gives authenticate permission to the roles that need to authenticate using the service.

Following is the syntax for an authenticator policy. An id that starts with conjur is required.

- !policy
  id: conjur/authenticator-type/opt-service-id   
    
  body:
    - !webservice    
      #if id is not assigned, 
      #it inherits the id from the policy
 
    #declare a group to collect all entities that will authenticate using this service 
    - !group         
      id: role-name
	  
 #give the group authenticate privilege on the service 
    - !permit
      resource: !webservice
      privilege: [ authenticate ]
      role: !group role-name

Use grant statements to add member roles to the authenticator group. The member roles can be users, hosts, groups, and layers. For example, for IAM or K8 authentication, you might create a layer to collect one or more hosts, and add that layer to the authenticator group.

An example policy is shown below:

- !policy
  id: conjur/authn-ldap/sysadmins
  body:
    - !webservice 

    - !group
      id: clients
      annotations:
        description: This group uses the authn-ldap/sysadmins service.

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

Open the conjur.yml file.

You can find the conjur.yml file in /etc/conjur/config.
Add each authenticator to conjur.yml in the following format: <authenticator type>/<SERVICE_ID>.

The following sample conjur.yml allowlists three authn-k8s authenticators and the default Conjur authenticator:

#List of authenticators enabled for this node
authenticators:
    - authn-k8s/cluster1
    - authn-k8s/cluster2
    - authn-k8s/cluster3
    - authn

Run:
```
evoke configuration apply
```
If validation is successful, a Conjur server reboot is initiated and the new configuration is applied.

If validation is not successful, evoke terminates the command, issues an error code to the console, and displays the incorrect variable. The configuration of the target node is not updated and Conjur services continue to operate with the prior configuration.

For more information, see Manage Conjur configuration.

For Conjur on Docker, we strongly recommend allowlisting authenticators using the conjur.yml file. You can still use the CONJUR_AUTHENTICATORS environment variable and evoke variable commands, but your configuration is not preserved. Click the Configuration file tab to continue.

Enable authenticators by allowlisting them in the CONJUR_AUTHENTICATORS environment variable.

When the environment variable CONJUR_AUTHENTICATORS is set, only the authenticators listed are allowed. CONJUR_AUTHENTICATORS is a comma-separated list of authenticator/<SERVICE_ID>.

The following example allowlists an LDAP authenticator as well as the default Conjur authenticator:

CONJUR_AUTHENTICATORS=authn-ldap/sysadmins,authn

Here is another example for two Kubernetes services and the default Conjur authenticator:

CONJUR_AUTHENTICATORS=authn-k8s/prod/gke,authn-k8s/dev/gke,authn

The CONJUR_AUTHENTICATORS variable can be set on the machine running Conjur, using the evoke variable set command. For more details, see the reference documentation for this command.

For example, to enable the authn-k8s/prod/gke authenticator, run this command:

evoke variable set CONJUR_AUTHENTICATORS authn-k8s/prod/gke

evoke variable set modifies the current (running) Conjur machine only. If you are upgrading to a new version of Conjur, previously configured variables DO NOT persist because a new image is used for the new release. Be sure to reapply your configured variables (e.g. authenticators) after you've finished the upgrade.

In addition, there is a known issue with Conjur cluster promotions/failovers. When a Standby is promoted to Leader, the configuration that was set using evoke variable set is lost. If you need configuration settings to persist, set environment variables instead when launching the Conjur machine with the docker run command. For more information, see the Docker Command Summary.

The value for this variable should be identical to the name given to the authenticator policy ID, excluding the conjur/ prefix.

For example, to allowlist the conjur/authn-k8s/dev-cluster endpoint, allowlist authn-k8s/dev-cluster.

Authenticator limitations

Authenticator service IDs do not support nesting. For example, the service ID authn-ldap/sysadmins is supported, but authn-ldap/sysadmins/new is not.
JWT Authenticators do not support claims that use the forward-slash (/) character.