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. You choose the <SERVICE_ID> value, but use it consistently in the configuration steps below.

Here are some examples of optional Service IDs appended to:

  
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: Allowlist the authenticators

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

Step 2: 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