Azure authorization for SCIM

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.

Obtain the client secret

1. Sign in to your Azure portal.
2. Search for and select Azure Active Directory.
3. In the Manage section of the Directory page, select App registrations → New registration.
4. On the Register an application page, enter the required information:
   • Name: The name of your application.
   • Supported account types: Select Accounts in this organizational directory only (Single tenant).
5. Click Register.
6. In the Manage section of your application page, select Certificates & secrets → Client secrets.
7. Click New client secret.
8. In the Add a client secret dialog box, enter the required information:
   • Description: The description of your client secret.
   • Expires: Select an expiry period.
9. Click Add.

   Your new secret is generated and added to the Client secrets list.

10. Copy the Value of your secret for future use.

Obtain the client and tenant IDs

1. Sign in to your Azure portal.
2. Search for and select Azure Active Directory.
3. In the Manage section of the Directory page, select App registrations → your application.
4. In the Overview section, copy the Application (client) ID and Directory (tenant) ID values for future use.

Obtain the jwks_uri parameter

1. Request a verbose output from https://login.microsoftonline.com/<tenant_id>/.well-known/openid-configuration.
2. From the JSON response, copy the jwks_uri value for future use.

Obtain the typ, iss, sub, and aud parameters

1. Send a POST request to the https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token endpoint using your tenant ID, client ID, and client secret:
   • For Windows, Postman, and Powershell:

     curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
       https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token \
       -d 'client_id=<client_id>' \
       -d 'grant_type=client_credentials' \
       -d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default' \
       -d 'client_secret=<client_secret>'

   • For Linux and Mac

     curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
       https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token \
       -d 'client_id=<client_id>' \
       -d 'grant_type=client_credentials' \
       -d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \
       -d 'client_secret=<client_secret>'

2. From the response, copy the access token.
3. Decode the JWT with an application such as JWT.io.
4. Copy the typ, iss, sub, and aud parameters for future use.

Register the JWKS endpoint with Collibra

Follow the instructions to Register the JWKS endpoint with Collibra and use the following values:

Collibra Console field	Value
JSON Web Key Set URL	The jwks_uri from the verbose output.
JWT Token Types	The typ parameter from the decoded JWT.
JWT Issuer	The iss parameter from the decoded JWT.
JWT Audience	The aud parameter from the decoded JWT.

Create a user in Collibra

Follow the instructions to Create a user in Collibra for your client application account:

User details	Value
Username	The sub parameter from the decoded JWT.
User groups	Assign the user to a group that has elevated permissions such as Sysadmin or one that has similar permissions.

Create a SCIM application

Create a new SCIM application and authorize it:

1. Sign in to your Azure portal.
2. Search for and select Azure Active Directory.
3. In the Manage section of the Directory page, select Enterprise applications → New registration.
4. Click the Create your own application button and provide the application name in the input field, then click the Create button.
5. On the Browse Azure AD Gallery page, click Create your own application and enter the required information:
   • What's the name of your app?: The name of your application.
   • What are you looking to do with your application?: Select Integrate any other application you don't find in the gallery (Non-gallery).
6. Click Create.

Your newly created application appears in the list of Enterprise applications.

Authorize your SCIM application

1. From the list of applications, select your new application → Provisioning.
2. On the Provisioning page, in the Manage provisioning section, select Update credentials.
3. On the Provisioning details page, enter the require information:
   • Provisioning mode: Automatic
   • Admin credentials:
     • Tenant URL: The endpoint of the CollibraSCIM API, for example https://<your_collibra_url>/rest/scim/v2.
     • Secret Token: Your JSON Web Token.
4. Click Test Connection.

   If your credentials are successfully verified, Azure displays a confirmation message.

5. Click Save to complete the process.

Start and stop a provisioning job

Azure access tokens are valid only for one hour and cannot be refreshed due to the Azure AD limitations on token refresh. The workaround to achieve users and groups provisioning and deprovisioning is to start and stop the provisioning job based on your need:

1. Generate a new client secret.
2. In the Manage section of the Directory page, select Enterprise applications → your application → Provisioning.
3. On the Provisioning page, in the Manage provisioning section, select Update credentials.
4. Click Test Connection.

   If your credentials are successfully verified, Azure displays a confirmation message.

5. Click Save to complete the process.
6. Return to the Provisioning page and click Start provisioning to perform the initial synchronization of Collibra users.

   Wait for the process to complete and validate the results in Collibra.

7. Click Stop provisioning.
8. Generate a new client secret and update the credentials.
9. Start the provisioning again when you need to perform another synchronization of users and groups.

Register an application

To access Collibra public APIs without requiring individual user credentials you must first register your application in Collibra and obtain a client ID and client secret that are required to request an access token. You can register new applications in Settings → OAuth Applications → Manage OAuth:

1. Click Register New Application

   The Register New Application dialog box appears.

   

2. Enter the required information:

   Field	Description
   Application Type	Integration: For applications that are developed by you to access and interact with the Collibra public APIs, facilitating integration with our product suite. Platform: For applications that are used to facilitate communication between different components of the Collibra platform, ensuring seamless data exchange and interaction across our product suite.
   Application Name	The name of you application, used to identify it in the list of registered applications.
   Integration Type	This option is only available if you select Platform as the Application Type. Select Data Quality Integration to register a Data Quality & Observability Classic instance.

3. Click Register.

   The Registration Confirmation dialog box appears.

   

4. Copy and safely store the Client ID and Client Secret.

   This is the only time you are able to see the client secret.

Create a SCIM application

Create a new SCIM application and authorize it:

1. Sign in to your Azure portal.
2. Search for and select Azure Active Directory.
3. In the Manage section of the Directory page, select Enterprise applications → New registration.
4. Click the Create your own application button and provide the application name in the input field, then click the Create button.
5. On the Browse Azure AD Gallery page, click Create your own application and enter the required information:
   • What's the name of your app?: The name of your application.
   • What are you looking to do with your application?: Select Integrate any other application you don't find in the gallery (Non-gallery).
6. Click Create.

Your newly created application appears in the list of Enterprise applications.

Authorize your SCIM application

1. From the list of applications, select your new application → Provisioning.
2. On the Provisioning page, in the Manage provisioning section, select Update credentials.
3. On the Provisioning details page, enter the require information:
   • Provisioning mode: Automatic
   • Admin credentials:
     • Authentication Method: Select OAuth2 Client Credentials Grant.
     • Tenant URL: The endpoint of the CollibraSCIM API, including the Azure AD optimization flag, for example https://<your_collibra_url>/rest/scim/v2?aadOptscim062020.
     • Token Endpoint: The token endpoint of the Collibra OAuth 2.0 Authorization API: https://<your_collibra_url>/rest/oauth/v2/token.
     • Client Identifier: The URL encoded value of the Client ID of your registered application in Collibra, for example urn%3Asys%3Aenv%3A4a1261cc-5bc0-44c0-9b85-fc4942ae7c58%3Ai%3Aq2724e.
     • Client Secret: The secret that provided by Collibra during the application registration process.
4. Click Test Connection.

   If your credentials are successfully verified, Azure displays a confirmation message.

5. Click Save to complete the process.