Configure JWT authentication

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

 

You must have Conjur admin permissions to perform this task.

Before you begin

  • This section assumes your application uses a JWT for authentication, and that the JWT is signed. For details, see JSON Web Token (JWT).

  • Make sure the time on the Conjur machine and the JWT provider time are synced. You can use the secured NTP service to synchronize the times.

  • Important! Make sure you fully understand the Important guidelines for configuring JWT authentication.

    There are many ways to define the JWT authentication. The example JWT authentication configured is just one configuration example.

  • The example in this sections use the following information:

    • Authentication is based on the token-app-property variable.

    • App ID path: host/jwt-apps

    • JWT Provider: https://vendorHost.example.com

    • Example JWT:

       
      {
        "ver": "2.0",
        "iss": "https://login.example.com",
        "sub": "AAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
        "aud": ["service1","service2","conjur"],
        "exp": 1537361411,
        "iat": 1537274711,
        "nbf": 1537274711,
        "workspace": "production_emp",
        ​"app_name": "myapp",
        "app_id": "app530",
        "additional_data": {   
            "group_name": "mygroup",
            "group_id": "group21",
            "team_name": "myteam",
            "team_id": "team76",
        },
        "client_id": "s6BhgRkqt3",
        "state": "af0ifjslrkj"
        "oid": "00000000-0000-0000-66f3-3332eca7ea91",
        "tid": "9122040d-6c67-4c5b-b112-36a304b66dad",
        "nonce": "123456",
        "aio": "Df2UXL1ix!lv8q5!eGbIDaky5mnOreY"
      }
  • Decide which claims in the JWT you want to use to set up the JWT authentication.

    Based on the example JWT above, let's use the workspace, app_name, and additional_data/group_id claims to define the authentication:

     
    {
      "ver": "2.0",
      "iss": "https://login.example.com",
      "sub": "AAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
      "aud": ["service1","service2","conjur"],
      "exp": 1537361411,
      "iat": 1537274711,
      "nbf": 1537274711,
      "workspace": "production_emp",
      ​"app_name": "myapp",
      "app_id": "app530",
      "additional_data": {   
          "group_name": "mygroup",
          "group_id": "group21",
          "team_name": "myteam",
          "team_id": "team76",
      },
      "client_id": "s6BhgRkqt3",
      "state": "af0ifjslrkj"
      "oid": "00000000-0000-0000-66f3-3332eca7ea91",
      "tid": "9122040d-6c67-4c5b-b112-36a304b66dad",
      "nonce": "123456",
      "aio": "Df2UXL1ix!lv8q5!eGbIDaky5mnOreY"
    }
  • If Conjur is unable to reach your remote JWKS URI endpoint, you need to provide the static JWKS value defined by the JWT provider (the public key set) to the JWT Authenticator. Make sure that you have access to this public key set when configuring the JWT Authenticator.

Configure the JWT authentication

This section describes how to set up a JWT Authenticator in Conjur so that your application can use a JWT to authenticate to Conjur.

Step 1: Configure JWT authentication

Step 2: Check the authenticator status

Check that the JWT Authenticator is configured correctly. For details, see Authenticator Status Webservice.

Step 3: Allowlist the JWT Authenticator

In this step, you add the JWT Authenticator to the list of allowed authenticators in Conjur.

You need to enable the authenticator on every Follower you want to authenticate to. For details, see Configure authenticators.

Send a JWT authentication request

Use the following URI to send a JWT authentication request to Conjur:

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

For example, using the following details:

Parameter

Example

Conjur-server-hostname

myorg.example.com

service-id

myVendor

account

cucumber

host-id

Following the example JWT authentication we configured above, which uses the token-app-property to create a 1:1 relationship between the JWT Authenticator and app ID (host), we do not include the host-id in the request.

the resulting request looks as follows:

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

For more details about sending authentication requests, see the Authenticate using JWT Authenticator REST API.

Modify JWT Authenticator

When you make certain modifications to a JWT Authenticator configuration, app IDs in Conjur that use the modified JWT Authenticator must be adjusted accordingly. This section describes these JWT Authenticator modifications and the required app ID policy adjustments.

 

App owners must be notified of these modifications so that they can adjust their app IDs accordingly. App IDs that are not adjusted will not be able to authenticate to Conjur due to mismatched configurations.

Claim alias mapping

If you modify the claim-aliases variable definition in the JWT Authenticator, application identities that include this claim mapping in their annotations must be modified accordingly.

Take, for example, the JWT Authenticator defined above in Configure JWT authentication.

Say you add the claim-aliases variable to the JWT Authenticator policy, and populate it as follows:

 
conjur variable set -i conjur/authn-jwt/myVendor/claim-aliases -v environment: workspace

In the myapp app ID (see Define an app ID (host)), the authn-jwt/myVendor/workspace: production_emp annotation must be adjusted accordingly to authn-jwt/myVendor/environment: production_emp:

 
- !policy
  id: jwt-apps
  body:
    - !group

    - &hosts
        - !host
            id: myapp
            annotations:
                authn-jwt/myVendor/environment: production_emp
                authn-jwt/myVendor/additional_data/group_id: group21

    - !grant 
        role: !group
        members: *hosts

- !grant
    role: !group conjur/authn-jwt/myVendor/apps
    member: !group jwt-apps

Enforced claims

If you add or modify the enforced-claims variable definition in the JWT Authenticator, application identities that do not include this enforced claim in its annotations must be modified to include it.

Take, for example, the JWT Authenticator defined above in Configure JWT authentication.

Say you want to enforce the team_id claim in the JWT Authenticator policy. Modify (repopulate) the enforced-claims variable as follows:

 
conjur variable set -i conjur/authn-jwt/myVendor/enforced-claims -v additional_data/group_id, team_id

The app ID (see Define an app ID (host)) must now include annotations for both the additional_data/group_id and team_id claims:

 
- !policy
  id: jwt-apps
  body:
    - !group

    - &hosts
        - !host
            id: myapp
            annotations:
                authn-jwt/myVendor/environment: production_emp
                authn-jwt/myVendor/additional_data/group_id: group21
                authn-jwt/myVendor/team_id: team76

    - !grant
        role: !group
        members: *hosts

- !grant
    role: !group conjur/authn-jwt/myVendor/apps
    member: !group jwt-apps

Troubleshooting