Use-case example: Using JWT Authentication to integrate Conjur and GitLab
This topic demonstrates how to integrate GitLab with Conjur using JWT authentication in Conjur.
For more information about this authentication, see JWT Authentication.
For this use case scenario:
We'll use Conjur CLI v7.1.0 to load policy and to populate variables.
We'll use the following GitLab token:
Configure the authentication
In this section we plan and configure the JWT authentication.
Before we begin, we need to decide which claim or claims in the GitLab token to use to create a 1:1 relationship between the applications and Conjur.
Let's say we want all entities in the
namespace1 namespace path in GitLab to be able to authenticate to Conjur. We will use the
namespace_path claim to create this 1:1 relationship when we define the JWT Authenticator. For added security, we will also add the full path of the application identity (
host) in Conjur,
To learn more, see Configure JWT authentication
In addition, we have to define at least one annotation when we define the application identity. The more annotations we use, the more we narrow down the entities that can authenticate using this JWT Authenticator.
We can use any string-type claim from the token as an annotation. This claim must not contain spaces or special characters that are not allowed by Conjur. Let's use the
ref claims for the annotations.
You can define the JWT Authenticator to enforce selected claims, making respective host annotations mandatory for passing authentication.
Moreover, when you define the JWT Authenticator, you can map vague claim names to more user-friendly aliases. In the JWT above,
For more information about enforcing claims and mapping claim names to more user-friendly aliases, see Configure JWT authentication.
Step 2: Configure the authentication
Now let's configure the JWT authentication in Conjur.
We start by configuring a JWT Authenticator. We create a policy where we configure:
the JSON Web Key Set (JWKS) URI (jwks-uri) provided by GitLab
issuervariables for creating a 1:1 relationship between the application and Conjur
To do this, let's copy the template policy and adjust it to our needs:
We name the JWT Authenticator
authn-jwt/gitlab. This helps us identify this as a JWT Authenticator for GitLab entities.
We uncomment the
We uncomment the
- !policy id: conjur/authn-jwt/gitlab body: - !webservice #Mandatory variable: The JWT provider URI #Uncomment either 'provider-uri' OR 'jwks-uri' #- !variable # id: provider-uri - !variable id: jwks-uri #Optional variables #Uncomment one or all of the following optional variables. #Note: If you uncomment 'token-app-property' you must also uncomment 'identity-path', #and vice versa; - !variable id: token-app-property - !variable id: identity-path - !variable id: issuer #- !variable # id: enforced-claims #- !variable # id: claim-aliases #- !variable # id: audience #Group of applications that can authenticate using this JWT Authenticator - !group apps - !permit role: !group apps privilege: [ read, authenticate ] resource: !webservice - !webservice id: status #Group of users who can check the status of the JWT Authenticator - !group id: operators - !permit role: !group operators privilege: [ read ] resource: !webservice status
Next, let's populate the variables in Conjur with information related to the JWT using the Conjur CLI.
We populate the
jwks-urivariable with the JWT provider URL:
conjur variable set -i conjur/authn-jwt/gitlab/jwks-uri -v https://gitlab.com/-/jwks/
We populate the
token-app-propertyvariable with the
namespace_pathclaim, as discussed in Plan the configuration above.
conjur variable set -i conjur/authn-jwt/gitlab/token-app-property -v namespace_path
We populate the
identity-pathvariable with the application path (without the
conjur variable set -i conjur/authn-jwt/gitlab/identity-path -v gitlab-apps
Lastly, we populate the
issuervariable with the GitLab URL:
conjur variable set -i conjur/authn-jwt/gitlab/issuer -v gitlab.com
Now let's create an application identity in Conjur.
We name the application identity for the value of the
namespace_pathclaim) that we configured in the JWT Authenticator. So we will call the application identity
We also add the annotation that we discussed earlier (see Plan the configuration).
The following application identity represents entities in
namespace 1that authenticate to Conjur if their GitLab token matches the
project_pathclaims defined in the annotations:
- !policy id: gitlab-apps body: - !group - &hosts - !host id: namespace1 annotations: authn-jwt/gitlab/project_id: 26768846 authn-jwt/gitlab/ref: master authn-jwt/gitlab/project_path: namespace1/jwt-example - !grant role: !group members: *hosts - !grant role: !group authn-jwt/gitlab/apps member: !group gitlab-apps
Step 3: Allowlist the JWT Authenticator in Conjur.
Lastly, we need to allowlist our JWT Authenticator,
To do this, in the Conjur configuration file (
conjur.yml), let's add the JWT Authenticator under
and apply the changes:
Send an authentication request
Using the JWT Authenticator REST API:
the authentication request will look like this: