Collibra REST API authentication with JSON Web Token

In this tutorial you check the prerequisites for JSON Web Token (JWT) authentication with Collibra Data Intelligence Platform, obtain the access token and test the authentication.

Almost all of the Collibra API calls require authentication.

How JWT authentication works

You can use JSON Web Token (JWT) authentication for your applications that interact with the Collibra REST API.

  • JWT authentication components
  • JWT authentication sequence
  • Read customer JWK Set sequence

A diagram depicting Collibra JWT authentication components

A diagram depicting Collibra JWT authentication sequence

A diagram depicting how Collibra reads a customer JWK Set

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.

Prerequisites

  • You have an Identity Provider (IdP) that supports issuing JWT tokens.
  • You have configured the JWT section of the Collibra Console service configuration.
  • You have created a Collibra user for the client application with the user name provided by the IdP.

    You can usually find the user name in the sub subject field.

Obtain the token

Your application must provide the authentication token as a Bearer token in the HTTP Authorization header. Use the OAuth 2.0 client credentials flow to request a token.

Test the JWT configuration

Make any API call to Collibra to test the correct JWT authentication setup, for example GET https://<your_collibra_url>/rest/2.0/communities.

Postman example

  1. Go to the Authorization tab.
  2. From the Type drop-down menu, select Bearer Token.
  3. Fill in the Token field.

curl example

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

Response codes

Code Meaning
204 The request has been authorized.
401 The request has not been authorized. See payload for details.

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.

Diagnose rejected JWT tokens

To diagnose configuration issues, inspect each of the three JWT sections separated by a period (.):

Token Description 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQs
  • The first section is a base-64 encoded JSON header.
  • The second section is base-64 encoded JSON payload.
  • The third section is a digital signature of the header and payload that proves the authenticity of the token.

An example of why a token may be rejected is if the iss issuer and aud audience fields from the token payload do not match the Collibra configuration.

Additional resources