Collibra REST API authentication with JSON Web Token

In this tutorial you check the prerequisites for JSON Web Token (JWT) authentication with Collibra 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

A diagram depicting Collibra JWT authentication components

JWT authentication sequence

Read customer JWK Set sequence

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

• Read the JSON Web Token authentication section of the Collibra Installation and Configuration Guide.

• Read the Collibra JSON Web Token authentication guide.

• Consult the REST API documentation provided with your version of Collibra Platform at https://<your_collibra_url>/docs/index.html.

• Read the Collibra API documentation.

• Learn about basic authentication: Collibra REST API authentication.