Workload authentication in Conjur

Access to Conjur Cloud requires authentication, whether it is CLI requests from users or automated requests from workloads using the API.

Authentication flow

Authentication to Conjur Cloud is based on a workload's identifying parameters, that is, credentials or underlying workload parameters and Conjur Cloud's ephemeral (short-lived) access tokens.

After the host presents its identifying parameters, a Conjur Cloud access token is returned in response. This access token is required for all subsequent API requests.

Conjur Cloud access tokens are cryptographically signed (RSA 2048) and expire after eight minutes.

Successful access to Conjur Cloud involves the following steps:

  1. The workload presents credentials (workload identity (host id) and API key) to prove identity.

    In ephemeral workload environments, the Conjur Host Factory service can auto-generate these credentials.

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

  3. The workload presents the unexpired access token along with each request to access Conjur Cloud. A cached login simplifies this step in the background for CLI access. For API access, when the token expires, the workload must re-authenticate to get a new token.

    A request must comply with Conjur RBAC authorization rules as recorded in policy. Access privileges to specific resources (secrets, for example) are granted using permit statements in policy.

For more information about Conjur Cloud authentication and supported Conjur authenticators, see Authenticate workloads.

Access tokens

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

Conjur Cloud issues a short-lived access token after authenticating a requester. The token is valid for 8 minutes for a workload identity, and 60 minutes for a user identity.

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

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

  • The token must be valid (unexpired)
  • The token signature must be verified by Conjur Cloud

If these conditions are not met, the request is rejected immediately.

An end-user of the CLI does not need to worry about access token mechanics because each CLI command automatically uses the short-lived access token stored in the CLI cache, and passes it with each HTTPS request until invalid and the user is requested to log in.

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

Authenticate workloads