Collibra JSON Web Token authentication guide

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

Almost all of the Collibra API calls require authentication.

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

How JWT authentication works

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.

curl -H 'Authorization: Bearer <your_token>' ...

Benefits of using JWT token authentication include:

• Keeping the authentication details at 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 Platform 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	Create a client credential account with a secret in your IdP. Determine the JSON Web Key Set (JWKS) endpoint URL for your IdP. Register the JWKS endpoint with Collibra. Create a user in Collibra for your client application account. Provide a meaningful first and last name to identify that this is a service account.
When your application starts	Authenticate your client application with your IdP. Save the returned access token for use in REST API calls.
When your application calls the Collibra REST APIs	Include the JWT token in the authorization HTTP header as a bearer token. 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. 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.
   

   Setting	Description
   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 Save all.
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 an 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. Common causes are: Bad signature. Wrong audience. Wrong issuer. Wrong media type. 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

• Read the JSON Web Token authentication section of the Collibra Installation and Configuration Guide.
• Read the Collibra REST API authentication with JSON Web Token tutorial.
• Consult the REST API documentation provided with your version of Collibra Data Intelligence Platform at https://<your_collibra_url>/docs/index.html.
• Read the Collibra Administration Guide API documentation.
• Learn about basic authentication: Collibra REST API authentication.