JWT authentication is a generic, secure way for applications running on various platforms to authenticate to Conjur 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 as application identities, or app IDs. For JWT authentication, the Conjur app ID can be established with varying granularity, allowing for a collection of resources to be identified to Conjur 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 and GitLab.
How it works
An application requests an identity token from a JWT provider.
The JWT provider sends a JWT back to the application.
The application sends an authentication request to Conjur using the JWT Authenticator REST API.
Conjur fetches a public key from the JWT provider and saves it for later use.
Conjur attempts to authenticate and authorize the request. If successful, Conjur sends a short-lived access token back to the application.
The application can use the Conjur token to retrieve secrets stored in Conjur.
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
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 (
expclaim). If there is no
expclaim, or if it is invalid, the JWT authentication fails.
If any of the
issclaims exists in the JWT, it must be valid, otherwise the JWT authentication fails.
When configuring an application to authenticate to Conjur using a JWT, you configure a JWT Authenticator endpoint and define an app ID in Conjur for the application authenticating to Conjur. You create a 1:1 relationship between the application authenticating to Conjur and its app ID.
Review these guidelines before you set up the JWT Authenticator. For details, see Important guidelines for configuring JWT authentication.
When you make certain modifications to a JWT Authenticator endpoint, app IDs in Conjur that use the modified endpoint must be adjusted accordingly. For more information, see Modify JWT Authenticator.