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.

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

1. Define a JWT Authenticator

   Create a Conjur policy for the JWT Authenticator.

   1. Save the following policy as authn-jwt.yml:

      - !policy id: conjur/authn-jwt/<SERVICE_ID> body: - !webservice # Mandatory variable: How the JWT Authenticator gets the signing keys # Uncomment either 'jwks-uri' or 'public-keys #- !variable jwks-uri #- !variable public-keys # Optional variables # Uncomment one or all of the following optional variables # Note: If you uncomment 'identity-path' you must also uncomment 'token-app-property' # Note: If you uncomment 'public-keys' above you must also uncomment 'issuer' #- !variable ca-cert #- !variable token-app-property #- !variable identity-path #- !variable issuer #- !variable enforced-claims #- !variable mapping-claims #- !variable audience # Group of applications that can authenticate using this JWT Authenticator - !group apps - !permit role: !group apps privilege: [ read, authenticate ] resource: !webservice - !webservice status # Group of users who can check the status of the JWT Authenticator - !group operators - !permit role: !group operators privilege: [ read ] resource: !webservice status

   2. Replace <SERVICE_ID> with a name that helps identify the authenticator, for example, prod, dev, myVendor, and so on. For information about service IDs, see Authenticator service IDs.

   3. Select the policy variables:

      Use the following diagram as a guide:

      

      1. Uncomment one of provider signing key variables, depending on how the JWT Authenticator will receive the JWT signing key:

         Signing key provider	Description
         jwks-uri	The resource for a set of JSON-encoded public keys, one of which corresponds to the key used to digitally sign the JWT. The keys must be encoded as a JWK Set (RFC7517). Value: A JWKS URI, beginning with https:// JWKS URI examples: Google - https://www.googleapis.com/oauth2/v3/certs Microsoft - https://login.microsoftonline.com/common/discovery/v2.0/keys GitLab - https://gitlab.com/-/jwks If you are authenticating to an Edge, make sure that the Edge has access to the JWKS-URI. When using this option, we strongly recommend that you use TLS communication with the public-keys server provider, thereby following best security practices.
         public-keys	When Conjur is unable to reach a remote JWKS URI endpoint, you can use this variable to provide a static JWKS to the JWT Authenticator. When using this variable, it is assumed that the JWT includes an iss claim, and you must also define the issuer variable (see optional variables below). Value: type and value, where type is always set to jwks (string value), and value is set to the JWKS value defined by the JWT provider (the public key set), in the following format: {\"type\":\"jwks\", \"value\":<your public key set>} For example: {\"type\":\"jwks\", \"value\":{"keys":[{"use":"sig","kty":"RSA","kid":"D1wArl26HhE2bFf4o4lAnnr0xtxcKt2ElJgFQnRgXk","alg":"RS256","n":"9gRcfAj1FsaX_hJ4__r6dXEs9AAETFPIG4pRti87XUyx-hi6z4dWvhkxLxZ12dKVGfWUkVRbLCUTfNlT9zueMib2HZ9mnk2oXJCBUuzi6JoIm1A5JyP-q_0GR6vCNH_Z7BVFI9cQKFprku6xpYZzdJcdAibzU12RuVsE0L3LKMolDS7Nhr6wKU1m8Ka-sNkFl1qciWO4oQcv3AUnOJvzMotCOzA_5MCyS6CGqWFXJo1KvzqrnIlJoA8tfnT5vnfSJhiWC_FYoeSPCmY3VnGvFs6PTJDa3Gfvb7U1X4S5ztnI6Y_ac3GtSdmVDnQPsOkKQI8669MHq-Bd-8C6Vp6UNQ","e":"AQAB"}]} }

      2. Uncomment the optional variables by which Conjur should create a relationship with the app ID.

         These are optional yet recommended. For more information, see Configure JWT authentication.

         Click to see the variable descriptions

         Variable	Description
         ca-cert	When the JWKS provider server uses a self-signed certificate or the certificate is signed by a third-party CA, use this variable to establish a TLS connection and validate server identity. Certificates from this variable (can be one or many certificates) override default operating system CA certificate bundles when fetching the JWKS from the remote URI. Value: The X.509 public key certificate or certificate bundle. Each certificate in the bundle should be in PEM (RFC7468) format. Required: No
         token-app-property	Use token-app-property to create a 1:1 mapping between the JWT Authenticator and the authenticating application. You populate token-app-property with the name of a claim in the JWT, for example "app-id". When you define an app ID for the authenticating application, its host id must match the JWT claim's value. For example, say the JWT has the following claim: "app-id": "app530" You populate the token-app-property with app-id You define the app ID as follows: - !host app530. The JWT Authenticator uses this mapping to validate the identity of the authenticating application. You can populate this variable with one claim only. For nested claims, specify the path to the nested claim: <claim_root>/<claim_name> Claims names that contain a slash (/) or a colon (:) are not supported. Required: No, but highly recommended
         identity-path	Further to defining the token-app-property variable, you can use the identity-path variable to define the app ID's path in Conjur, thereby completing the full app ID name. The JWT Authenticator narrows validation of the authenticating application by the app ID, and in the defined identity path. identity-path has no purpose when standing alone. It should be used only if token-app-property is defined. Required: No
         issuer	JWT Authenticator validates the issuer of the JWT. The issuer variable value must be identical to the iss claim value. Required: When signing keys are static, that is, when the public-keys variable (see signing key provider variables) is defined in the policy, this variable is required When the sign keys come from the JWKS URI, this variable is optional. In this case, if you do not define this variable, the issuer is taken from the jwks-uri.
         enforced-claims	You can define a list of enforced claims in the JWT Authenticator. All Conjur app IDs that work with the JWT Authenticator endpoint must include these enforced claims in their host annotations. When this variable is defined in the JWT Authenticator, it must be populated with at least one claim. Separate multiple claims with commas: custom_claim1,custom_claim2. For nested claims, specify the path to the nested claim: <claim_root>/<claim_name>   You cannot enforce reserved claims (iss, exp, nbf, iat, aud, jti). When a claim is enforced, application identities that do not include this claim as a host annotation will no longer be able to authenticate to Conjur and must be deleted and redefined.. Required: No
         claim-aliases	Claim names in JWTs do not always represent their essence. For example ref might actually indicate a namespace ID, or a branch. You can map claim names to more user-friendly aliases in your app ID's host annotations, instead of the actual claim name. Following on from the example above, you can map ref to namespace, and then use namespace in the host annotation. So the host annotation would look as follows: authn-jwt/<service-id>/namespace: theNamespace Because of this mapping, the JWT Authenticator knows to check the JWT's ref value. When this variable is defined in the JWT Authenticator, it must be populated with at least one mapping statement, in the following format: <target-annotation-name>:<source-claim-name> For nested claims, specify the path to the nested source claim: <target-annotation-name>:<source_claim_root>/<source_claim_name> Separate multiple mapping statements with commas: <target-annotation-name_1>:<source-claim-name_1>,<target-annotation-name_2>:<source-claim-name_2>   You cannot map reserved claims to aliases (iss, exp, nbf, iat, aud, jti). Application identities (hosts) that were defined prior to mapping the claim to an alias, and whose host annotations include the mapped claim, must be redefined to use alias. Required: No
         audience	If the JWT has an audience claim (aud), you can include this variable to authenticate the aud claim. The audience variable accepts a single value and must match the aud claim value. If the aud claim contains an array, the array must include the audience variable value. Required: No

         Example policy using token-app-property

         The following policy defines a JWT Authenticator, auth-jwt/myVendor that uses the following variables:

         • token-app-property and identity-path to create a 1:1 relationship between the application and Conjur

         • enforced-claims to enforce using additional_data/group_id as one of the app ID's host annotations

         • jwks-uri for the JWKS signing keys URI

         The Authenticator Status (status) webservice defined in the policy verifies the status of the JWT Authenticator. It identifies whether or not the JWT Authenticator configuration was successful. Make sure to grant permissions to the user groups that should be able to check JWT Authenticator status by adding them to the operators group. For details on defining groups in policy, see Group.

         - !policy id: conjur/authn-jwt/myVendor body: - !webservice # Mandatory variable: How the JWT Authenticator gets the signing keys # Uncomment either 'jwks-uri' or 'public-keys - !variable jwks-uri #- !variable public-keys # Optional variables # Uncomment one or all of the following optional variables # Note: If you uncomment 'identity-path' you must also uncomment 'token-app-property' # Note: If you uncomment 'public-keys' above you must also uncomment 'issuer' #- !variable ca-cert - !variable token-app-property - !variable identity-path #- !variable issuer - !variable enforced-claims #- !variable mapping-claims #- !variable audience # Group of applications that can authenticate using this JWT Authenticator - !group apps - !permit role: !group apps privilege: [ read, authenticate ] resource: !webservice - !webservice status # Group of users who can check the status of the JWT Authenticator - !group operators - !permit role: !group operators privilege: [ read ] resource: !webservice status

   4. Load the policy into root:

      conjur policy load -f /path/to/file/authn-jwt.yml -b root

2. Populate the policy variables

   In this step, populate the variables that you defined in the JWT Authenticator policy above:

   1. Populate jwks-uri with the signing key URI, https://vendorHost.example.com/path/to/jwks:

      conjur variable set -i conjur/authn-jwt/myVendor/jwks-uri -v https://vendorHost.example.com/path/to/jwks

   2. Because we are using the app_name claim to create the 1:1 relationship, populate token-app-property as follows (you can populate this variable with one claim only):

      conjur variable set -i conjur/authn-jwt/myVendor/token-app-property -v app_name

   3. Populate identity-path with the app ID path, (without the host/ prefix):

      conjur variable set -i conjur/authn-jwt/myVendor/identity-path -v jwt-apps

   4. Populate enforced-claims with the additional_data/group_id:

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

3. Define an app ID (host)

   In this step, you define an identity in Conjur for your applications. This app ID is represented as a host in Conjur.

   Save the following policy as authn-jwt-hosts.yml:

   - !policy id: <policy-id> body: - !group - &hosts - !host id: <host-id> annotations: authn-jwt/<SERVICE_ID>/<claim>: <claim value> #authn-jwt/<SERVICE_ID>/<claim>: <claim value> - !grant role: !group members: *hosts - !grant role: !group conjur/authn-jwt/<SERVICE_ID>/apps member: !group <policy-id>

   • If you defined the token-app-property in the JWT Authenticator configuration, use the best practices when defining the host.

   • Define at least one annotation.

     The more annotations you define, the tighter the application security. You can define any string-type claim from the JWT as an annotation, for example, workspace and additional_data/group_id. Note that the additional_data/group_id annotation is mandatory because additional_data/group_id is an enforced claim in the JWT Authenticator policy.

     Nested claims are supported. Arrays are currently not supported.

   - !policy id: jwt-apps body: - !group - &hosts - !host id: myapp annotations: authn-jwt/myVendor/workspace: 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

   Load the policy into any policy level, for example, to load into root:

   conjur policy load -f /path/to/file/authn-jwt-hosts.yml -b root

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.

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:

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.

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