Conjur Default Authenticator

API Key

An API key is an alphanumeric string with length of 51 to 56 characters. It is generated randomly by Conjur when a user or application is created. It can be rotated at a later time using the CLI or API.

User credentials

User credentials are assigned when the user is created:

  • id - An id that you assign to a user in policy or the username from an external directory sync.

  • API key - Conjur generates an API key for every user when the user resource is created.

The initial API key must be saved because it is required to log in the first time. Here is the output from loading a simple policy on the command line:

 
$ conjur policy load -b root -
- !user ben
Loaded policy 'root'
{
"created_roles": {
"org2:user:ben": {
"id": "org2:user:ben",
"api_key": "26g52y3jn9qc328dq2c812bwwen23447g43r84f9e3byyyta193gv03"
}
},
"version": 1
}
 
$ conjur policy load root -
- !user ben
Loaded policy 'root'
{
"created_roles": {
"org2:user:ben": {
"id": "org2:user:ben",
"api_key": "26g52y3jn9qc328dq2c812bwwen23447g43r84f9e3byyyta193gv03"
}
},
"version": 1
}

Change the Password or API Key for Users

A user authenticates to Conjur the first time with the id and the API key value as password. After authenticating successfully with the API key, the user can set a password using the conjur user update_password command as described below:

 
conjur user change-password -p <New password value>
 
conjur user change_password --p password=<New password value>

The only way a password on a user account can be changed is by the logged in user. Users cannot change the password of another user.

Authorized users can rotate the API key for other users. Use the following command-line command for API key rotationconjur user rotate_api_key

 
conjur user rotate-api-key
 
 conjur user rotate_api_key

To recover from a forgotten password, an admin can rotate the API key, and then the user can log in with the API key and change the password.

The differences between the password and API key are:

  • The password is stored using bcrypt on the Conjur server. It cannot be recovered, only reset by the user.

  • The API key cannot be changed by a user to any predefined value. It is always a random string.

  • Authentication by API key is somewhat faster than authentication by password.

Application credentials

An application (host) authenticates to Conjur using the following credentials:

  • The login name is the literal value host/ followed by the fully qualified host id.

    A fully qualified id is the entire policy namespace that describes where the host is declared in the hierarchy of policy branches. For example, hosts declared in a policy branch named aws have a fully qualified id of aws/my-host and the login name for that host is host/aws/my-host.

    In an API request, the "/" characters must be encoded as %2F, so for the example host name above it would be encoded as host%2Faws%2Fmy-host.

  • The password equivalent for a host is the host's current API key.

    An administrative user who has the appropriate permissions on the host resource can reset (rotate) the API key if it is lost or compromised. Authenticated users with appropriate permission can get the current API value of a host using the API or CLI.

The API key is a randomly generated secret assigned by Conjur when the host is created. When you load policy that creates a host, the output from the load command includes the API key for each host that was created. Here is partial command output from a policy load that created two hosts:

 
{
"dev:host:frontend/frontend-01": "33f0ppq25sy3kx1qx630b2mvth2126nscms28bk7qy3hrw
dmna86fh",
"dev:host:frontend/frontend-02": "2w7dkpv2eszx6nvgvgvy2q2z5seq6n3gk33z1fem3z7f64
93dqtwhm"
}

A host needs access to its credentials to authenticate to Conjur and get access to secrets. Credentials are typically located in files or in environment variables.

  • For applications that are long-running, such as servers and VMs, the typical way to store the credentials is in a file accessible to the application. For example: /etc/conjur.identity.

  • For applications that can accept configuration through the environment, such as Docker containers, CI jobs, Heroku applications, the environment variables CONJUR_AUTHN_LOGIN and CONJUR_AUTHN_API_KEY are used.

  • For short-lived applications, such as some containers or temporary VMs, Host Factory tooling or Conjur integrations are used to manage identity.