A use-case: Conjur-GitLab Integration with JWT Authentication

This topic demonstrates how to integrate GitLab with Conjur, using JWT authentication in Conjur.

 

For more information about this authentication, see JWT Authenticator.

Assumptions

For this use case scenario:

  • We'll use Conjur CLI v7.0.1 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.

Step 1: Plan the configuration

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, conjur/authn-jwt/gitlab/apps.

To learn more, see Best practices for JWT authentication configuration

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 project_id, project_path, and ref claims for the annotations.

Step 2: Configure the authentication

Now let's configure the JWT authentication in Conjur.

  1. 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

    • the token-app-property,identity-path, and issuer variables 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 token-app-property and identity path variables

    • We uncomment the jwks-uri variable

     
    - !policy
        id: conjur/authn-jwt/gitlab
        body:
        - !webservice
      
        #Optional: Uncomment any or all of the following variables:
        #'token-app-property'/'identity-path'/'issuer'
        #'identity-path' is always used together with 'token-app-property',
        #but 'token-app-property' can be used without 'identity-path'
     
        - !variable
            id: token-app-property
      
        - !variable
            id: identity-path
     
        - !variable
            id: issuer
     
        #Mandatory: The JWT provider URI: You must provide (uncomment) either
        #'provider-uri' OR 'jwks-uri'
     
        #- !variable
        #    id: provider-uri
      
        - !variable
            id: jwks-uri
      
        #Group of hosts 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
  2. Next, let's populate the variables in Conjur with information related to the JWT using the Conjur CLI.

    1. We populate the token-app-property variable with the namespace_path claim, as discussed in Plan the configuration above.

       
      conjur variable set -i conjur/authn-jwt/gitlab/token-app-property -v namespace_path
    2. We populate the identity-path variable with the application path (without the host/ prefix):

       
      conjur variable set -i conjur/authn-jwt/gitlab/identity-path -v conjur/authn-jwt/gitlab/apps
    3. We populate the issuer variable with the GitLab URL:

       
      conjur variable set -i conjur/authn-jwt/gitlab/issuer -v gitlab.com
    4. Lastly, we populate the identity-path variable with the application path:

       
      conjur variable set -i conjur/authn-jwt/gitlab/jwks-uri -v https://gitlab.com/-/jwks/
  3. Now let's create an application identity in Conjur.

    We name the application identity for the value of the token-app-property (the namespace_path claim) that we configured in the JWT Authenticator. So we will call the application identity namespace1.

    We also add the annotation that we discussed earlier (see Plan the configuration).

    The following application identity represents entities in namespace 1 that authenticate to Conjur if their GitLab token matches the project_id, ref, and project_path claims 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 /conjur/authn-jwt/gitlab/apps
      member: !group gitlab-apps

Step 3: Allowlist the JWT Authenticator in Conjur.

Lastly, we need to allowlist our JWT Authenticator, authn-jwt/gitlab, on all of our Followers.

To do this, in the Conjur configuration file (conjur.yml), let's add the JWT Authenticator under authenticator::

 
authenticators: 
  - authn-jwt/gitlab

and apply the changes:

 
$ evoke configuration apply

Send an authentication request

Using the JWT Authenticator REST API:

 
POST https://<Conjur-server-hostname>/authn-jwt/<service-id>/<account>/[<host-id>]/authenticate

the authentication request will look like this:

 
curl -k --request POST 'https://follower1.example.com/authn-jwt/gitlab/myorg/namespace1/authenticate' --header 'Content-Type: application/x-www-form-urlencoded' --header "Accept-Encoding: base64" --data-urlencode 'jwt=eyJ0e......jjjkl'