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.
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
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:
This section describes how to configure authenticators.
If your implementation uses only the Conjur default authenticator (authn), no special configuration is required.
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>.
authenticatepermission 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
You can find the
- Add each authenticator to
conjur.ymlin the following format:
evoke configuration apply
If validation is successful, a Conjur server reboot is initiated and the new configuration is applied.
If validation is not successful,
evoketerminates 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.
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
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
The following example allowlists an LDAP authenticator as well as the default Conjur authenticator:
Here is another example for two Kubernetes services and the default Conjur authenticator:
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 service IDs do not support nesting. For example, the service ID
authn-ldap/sysadminsis supported, but
JWT Authenticators do not support claims that use the forward-slash (/) character.