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
}
|
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:
|
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:
|
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 qualifiedhost id.A fully qualified id is the entire policy namespace that describes where the
hostis declared in the hierarchy of policy branches. For example,hostsdeclared in a policy branch namedawshave a fully qualified id ofaws/my-hostand the login name for that host ishost/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
hostresource 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:
|
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_LOGINandCONJUR_AUTHN_API_KEYare used. -
For short-lived applications, such as some containers or temporary VMs, Host Factory tooling or Conjur integrations are used to manage identity.
