Authenticate JWT

JWT authentication is a generic, secure way for applications running on various platforms to authenticate to Conjur Cloud using a JSON Web Token—a unique identity token or a third-party machine identity signed by a JWT provider.

Applications are represented in Conjur Cloud as application identities, or app IDs. For JWT authentication, the Conjur Cloud app ID can be established with varying granularity, allowing for a collection of resources to be identified to Conjur Cloud as one, or for individual workloads to be uniquely identified.

JWT authentication assumes your application works with a JWT, and that the JWT is signed.

For a use-case scenario with GitLab, see Use-case example: Using JWT Authentication to integrate Conjur Cloud and GitLab.

How it works

  1. An application requests an identity token from a JWT provider.

  2. The JWT provider sends a JWT back to the application.

  3. The application sends an authentication request to Conjur Cloud using the JWT Authenticator REST API.

  4. Conjur Cloud fetches a public key from the JWT provider and saves it for later use.

  5. Conjur Cloud attempts to authenticate and authorize the request. If successful, Conjur Cloud sends a short-lived access token back to the application.

  6. The application can use the Conjur Cloud token to retrieve secrets stored in Conjur Cloud.

JSON Web Token (JWT)

A JWT is provided by a JWT provider, and MUST be signed.

  • The following algorithms, defined in the JWT's header, are supported by the JWT Authenticator.

    Signing method Algorithm

    RSA

    • RS256 - RSA using SHA-256 hash algorithm

    • RS384 - RSA using SHA-384 hash algorithm

    • RS512 - RSA using SHA-512 hash algorithm

  • The JWT must have a valid expiration date (exp claim). If there is no exp claim, or if it is invalid, the JWT authentication fails.

  • If any of the iat, nbf, or iss claims exists in the JWT, it must be valid, otherwise the JWT authentication fails.

Important guidelines

When configuring an application to authenticate to Conjur Cloud using a JWT, you configure a JWT Authenticator endpoint and define an app ID in Conjur Cloud for the application authenticating to Conjur Cloud. You create a 1:1 relationship between the application authenticating to Conjur Cloud and its app ID.

Review these guidelines before you set up the JWT Authenticator. For details, see Important guidelines for configuring JWT authentication.

JWT Authenticator modification implications

When you make certain modifications to a JWT Authenticator configuration, app IDs in Conjur Cloud that use the modified JWT Authenticator must be adjusted accordingly. For more information, see Modify JWT Authenticator.