OAuth setup with Entra ID

This page is relevant for Hackolade Studio client connection to a Collibra instance using an identified user. It does not apply to a server or CLI instance of Hackolade Studio establishing a machine-to-machine connection to Collibra using a service account.

1. Register an Application in Microsoft Entra ID

1. Go to Azure Portal > Microsoft Entra ID > App registrations
2. Click New registration
   1. Configure:
   2. Name (example): Collibra Integration
3. Supported account types: usually Single tenant
4. After creation:
   1. Save Application (client) ID
   2. Save Directory (tenant) ID

More detailed instructions in the official Microsoft documentation

2. Configure API Permissions of the Application

1. Go to API Permissions in the left panel
2. Add:
   1. User.Read (required)
   2. openid profile offline_access (optional)

1. Click Grant admin consent

3. Retrieve OpenID Configuration from the Overview of the Application

Copy the Entra well-known endpoint:

https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

Or:

Go to Overview > Endpoints
Copy and open the link from the OpenID Connect metadata document

From this JSON, extract:

• jwks_uri → used in Collibra
• issuer → used in Collibra

4. Map Values to Collibra Configuration

1. Open Collibra console: https://console-{company-domain}.collibra.com\ 2. Select your environment -> Data Governance Center > Configuration > Security configuration > JWT

Next properties should be mapped:

5. How Collibra matches the token to a user

When you connect from Hackolade Studio, Microsoft Entra ID issues an access token for your user, and Hackolade Studio sends this token to Collibra. Collibra reads one value from the token and looks for a Collibra user with exactly this username. If no user matches, Collibra refuses the connection, even when all other JWT properties are correct.

An access token contains several fields, called claims. Each claim has a name and a value. For example, the decoded token of John Doe contains these claims, among others (Microsoft lists all of them in its access token claims reference, if you want to know what each claim contains):

sub: "AAAAAAAAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ"
preferred_username: "john.doe@yourcompany.com"
aud: "..."
iss: "..."

In the JWT Principal ID Claim Name property, you set which claim Collibra reads. The default value is sub, as described in the Collibra JWT authentication guide. Entra ID fills sub with an identifier generated for your application. The default value works only if your Collibra usernames contain exactly this identifier.

In this example, the Collibra username of John Doe is his sign-in name, john.doe@yourcompany.com. This value is in the preferred_username claim, not in sub. With sub, no user matches. With preferred_username, Collibra finds the user:

To check which claim to use for your organization:

1. Retrieve an access token for a test user and decode it, as described for the JWT Audience above.
2. In Collibra, open this user and note the username.
3. In the decoded token, find the claim whose value is exactly this username, and enter the name of this claim in JWT Principal ID Claim Name. If this claim is sub, keep the default value.

If no claim of the token contains the Collibra username, add the missing claim in Entra ID as an optional claim (App registrations > your application > Token configuration), or align the Collibra usernames with a claim that the token already contains.