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
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
- Go to the Authorization tab.
- From the Type drop-down menu, select Bearer Token.
- 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:
|
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 |
|
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 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.