JSON Web Token authentication guide

This tutorial is a complete guide to REST API authentication using a JSON Web Token.

Note   Almost all of the Collibra API calls require authentication.

Tip   To learn about basic authentication, see Collibra REST API authentication.

You can use JSON Web Token (JWT) authentication for your applications that interact with the Collibra REST API. During this process, your application requests an access token from your Identity Provider (IdP). The IdP acts as the authentication server and returns a signed JWT access token. When your application makes API calls to Collibra, it provides the JWT access token as a Bearer token in the HTTP Authorization header.

Benefits of using JWT token authentication include:

  • Keeping the authentication details with the IdP and separate from Collibra.
  • Simplifying your security management.
  • Limiting the time a token is valid for.

Collibra minimum versions

JWT authentication is available starting with the following versions:

  • Collibra Data Intelligence Cloud 2020.11.
  • Collibra Data Governance Center 5.7.7-1.

Set up and use JWT

The following table summarizes acquiring and using JWT in Collibra REST API requests.

Process

Steps

Initial setup
  1. Create a client credential account with a secret in your IdP.
  2. Determine the JSON Web Key Set (JWKS) endpoint URL for your IdP.
  3. Register the JWKS endpoint with Collibra.
  4. Create a user in Collibra for your client application account.

    Tip   Provide a meaningful first and last name to identify that this is a service account.

When your application starts
  1. Authenticate your client application with your IdP.
  2. Save the returned access token for use in REST API calls.
When your application calls the Collibra REST APIs
  1. Include the JWT token in the authorization HTTP header as a bearer token.
  2. If the API call responds with unauthorized, the access token or JWKS credentials may have expired. Re-authenticate and retry the request.

JWT dependencies on your Identity Provider

The following details must be provided by your IdP in the JWT token for Collibra to accept the token.

Section

Field

Description

Header alg

The encryption algorithm.

Collibra supports all standard encryption algorithms.

kid

The JWKS identifier of the public key used to sign the JWT token.

An identity provider may have multiple public key certificates, for example multiple valid keys may exist while a key rotation is in progress.

typ

Optional field that defines the JWT type.

Tip   Use the MIME type format, for example application/jwt or application/secevent+jwt with the application/ prefix removed, for example jwt or secevent+jwt.

Payload iss

The issuer of the token.

This field is used to check the token comes from the expected IdP.

exp The token expiry time.
iat The time the token was issued.
sub The subject or the principal ID.
Signature  

The digital signature of the header and payload.

The signature verifies the message did not change along the way. In the case of tokens signed with a private key, the signature also verifies the authenticity of the JWT sender.

Configure JWT settings

To enable or change the JSON Web Token configuration:

  1. Open Collibra Console.

    Collibra Console opens with the Infrastructure page.

  2. In the tab pane, expand an environment to show its services.
  3. In the tab pane, click the Data Governance Center service of that environment.
  4. Click Configuration.
  5. Click Edit configuration.
  6. In the JWT section, make the necessary changes.
    SettingDescription
    JSON Web Key Set URL

    The URL to retrieve public key information needed to verify the authenticity of JSON Web Tokens (JWTs), issued by an authorization server.

    This setting is required to enable JWT authentication.

    JWT Token Types

    A case-insensitive comma-separated list of accepted JWT media types coming in the typ header parameter.

    Leave blank if the authorization server does not provide a media type parameter.

    The default values is at+jwt,jwt.

    JWT Algorithms

    A comma-separated list of accepted JWT algorithms coming in the alg header parameter. See https://tools.ietf.org/html/rfc7518#section-3.1 for details.

    Leave blank to accept all digital signature algorithms.

    JWT Issuer

    The accepted issuer coming in the iss JWT claim.

    Leave blank if the authorization server does not provide an issuer claim.

    JWT Audience

    A comma-separated list of accepted audience values for the aud claim.

    The value for this field is a configuration setting in your authorization server, which identifies your Collibra environment as the intended recipient of the JWT.

    Leave blank if the authorization server does not provide an audience claim.

    JWT Principal ID Claim Name.

    The name of the JWT claim containing the principal’s identity. See https://tools.ietf.org/html/rfc7519#section-4.1.2 for details.

    Defaults to the standard subject claim, sub.

    Change this setting only if your authorization server has other means of identifying the principal, for example, a client_id claim.

    This setting is required if JWT authentication is enabled.

    JWT Maximum Clock Skew

    The maximum acceptable difference in seconds between the clocks of the machines running the authorization server and Collibra.

    Differences smaller than the given amount are ignored when performing time comparisons for token validation.

    The default value is 60 seconds if left blank.

  7. Click the green Save all button.
  8. Restart the environment to apply your changes. See Stop an environment and Start an environment.

JWT troubleshooting

The following table contains JWT authentication error codes that may appear in the body of the 401 Unauthorized HTTP response. You can use the error codes to determine the appropriate course of action for your application.

Error code Description Possible action

malformedToken

The JWT token is incorrectly encoded or has incorrect syntax

Check your IdP configuration to make sure it is returning a token in JWT format.

expiredToken

The JWT token has expired

In your application, request a new token from the IdP and retry.

invalidToken

The JWT token is invalid (for example bad signature, wrong audience, wrong issuer, wrong media type, or disallowed signing algorithm)

Check your IdP and Collibra JWT configuration to make sure the settings are consistent.

unableToProcessToken

The JWT token could not be processed

Check your IdP and Collibra JWT configuration and if the problem persists contact Collibra Support.

Additional resources