Authentication

Conjur can authenticate both users and hosts.

Authentication flow

Almost all access to Conjur requires authentication, whether it is CLI requests from users, automated requests from hosts using the API.

Authentication to Conjur is based on credentials and automatically expiring access tokens. These ephemeral access tokens are required for all subsequent API requests after presenting credentials. They are cryptographically signed (RSA 2048) and expire after eight minutes.

Successful access to Conjur involves the following steps:

1. The requester presents credentials to prove identity.

   • Credentials for human users are the user name and password or API key. Human user authentication is also possible with OIDC ID tokens.

   • Credentials for machine identity are host id and API key. In ephemeral application environments, a Conjur host-factory service can auto-generate host IDs and API keys.

2. If Conjur verifies the credentials, it returns a short-lived access token.

3. The requester then presents the unexpired access token along with each request to access the Conjur database. A cached login simplifies this step in the background for . For API access, when the token expires, the machine must reauthenticate to get a new token.

4. A request must comply with Conjur RBAC authorization rules as recorded in policy. Access privileges to specific resources (secrets, for example) for both users and hosts are supplied in policy with permit statements.

Access tokens

Almost all requests to Conjur must include a valid access token. Exceptions include init, authn login, and pubkeys show.

Conjur issues a short-lived access token after authenticating a requester. The token is valid for 8 minutes by default.

The token is a JSON Web Token (JWT). It is cryptographically signed by a Conjur private key (RSA 2048), which includes the host or user id along with the expiration timestamp. Conjur uses OpenSSL to generate the RSA key pair, validate, and sign the tokens.

Both of the following conditions must be true to gain access:

1. The token must not be expired.
2. The token signature must be verified by the Conjur server.

Otherwise, the request is rejected immediately.

Typically, an end-user of the CLI does not need to worry about access token mechanics, since each CLI command automatically obtains a token using cached login information, and passes it with each HTTPS request.

When using the Ruby API, a new API object can be instantiated from an API key or password and it automatically obtains a token. After token expiration, a new API object must be created or the server will start to reject the requests.

Login cache

When logging in with a password or an API key, the credentials are checked with Conjur, and both the id and API key for the host or user logging in are stored in the operating system user's .netrc file (or the file to which optional directive netrc_path in .conjurrc points to).

NOTE: Conjur uses a persistent .netrc file by default and for convenience. For a more secure setup, we recommend that you change .conjurrc by adding a directive netrc_path pointing to a file in the /dev/shm directory (on the OSes that support such a filesystem). This way, credentials and authentication context are wiped out automatically on each reboot, and also are not part of any disk snapshots of the working environment.

On subsequent calls, the CLI automatically generates access tokens from the id and API key stored in .netrc.

Performing login again completely overwrites any previously cached credentials.

The conjur authn logout command removes appropriate credentials from .netrc.

Logging In and Who Am I

A user logs in to the CLI using the conjur authn login command.

After logging in, a user can display the current logged-in identity with the command conjur authn whoami.

$ conjur authn whoami
{"account":"myorg","username":"joe-tester"}

Get an Access Token for HTTP Requests

A logged in user can use conjur authn authenticate -H to get an access token that is pre-formatted for use as an HTTP authorization header. If you omit the -H option, you get the token as JSON.

$ conjur authn authenticate -H

Authorization: Token token="..."

You can use a token obtained on the command line for API or curl access:

$ token=$(conjur authn authenticate -H)
$ curl -H "$token" http://conjur/resources/myaccount
[
... json output
]

Industry-standard Authenticators

In addition to its default authenticator, Conjur supports other industry-standard authentication types. You can configure Conjur to use one or a combination of several authenticator types. See Configure authentication.

Authentication using the API

To authenticate and receive an access token, send a POST request and body as follows.

POST Request:

/:authenticator-type/:optional-service-id/:conjur-account/:username/authenticate

Request Body:

Send the password (or other credential relevant to your authenticator) as plain text in the request body.

Request Parameter Descriptions

authenticator-type: The default Conjur authenticator type is authn, and all other authenticator types begin with the prefix authn-. For example, authn-ldap.

optional-service-id: This is useful when you have two different instances of the same authenticator type.

conjur-account: The Conjur account you'll be issued a token for. This is the Conjur appliance identifier provided during Conjur configuration.

username: The username (from the point of view of the authenticator) of the person or machine requesting authentication.

• For default Conjur authentication, this is:

  • For a user, the id assigned when the user was created.

  • For a host, the id assigned when the host was created, prepended with the literal host/. When encoded for the URL request, a host username becomes host%2Fmy-host-id.

• For LDAP authentication, this is the LDAP username.

request body: The plain text password or other credential relevant to your authenticator. The value could be an ordinary password, an API key, or other token, depending on the type of authenticator.

Conjur can be configured to use the IP address of an API client as an additional layer of security by limiting authentication based on the network from which a request originates.

This is accomplished by comparing the IP address in the API request to the Host or Users restricted to attribute in a policy. It lets you limit the use of a Host or User authentication to a particular network or subnet where it should be used, mitigating unauthorized use of leaked or stolen credentials.