> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/api/guides/the-system-for-cross-domain-identity-management/microsoft-entra-id-authorization-for-scim.md).

# Microsoft Entra ID authorization for SCIM

Collibra supports only basic, bearer token authentication with JWT, and OAuth.

{% tabs %}
{% tab title="JWT authentication" %}
The following table summarizes acquiring and using JWT in Collibra REST API requests.

| Process                                            | Steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Initial setup                                      | <ol><li>Create a client credential account with a secret in your IdP.</li><li>Determine the JSON Web Key Set (JWKS) endpoint URL for your IdP.</li><li><a href="https://productresources.collibra.com/docs/collibra/latest/Default.htm#cshid=DOC0773">Register the JWKS endpoint</a> with Collibra.</li><li><p><a href="https://productresources.collibra.com/docs/collibra/latest/Default.htm#cshid=DOC0655">Create a user</a> in Collibra for your client application account.</p><div data-gb-custom-block data-tag="hint" data-style="success" class="hint hint-success"><p>Provide a meaningful first and last name to identify that this is a service account.</p></div></li></ol> |
| When your application starts                       | <ol><li>Authenticate your client application with your IdP.</li><li>Save the returned access token for use in REST API calls.</li></ol>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| When your application calls the Collibra REST APIs | <ol><li>Include the JWT token in the authorization HTTP header as a bearer token.</li><li>If the API call responds with <strong>unauthorized</strong>, the access token or JWKS credentials may have expired. Re-authenticate and retry the request.</li></ol>                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Obtain the client secret

{% stepper %}
{% step %}
Sign in to your Microsoft Entra admin center.
{% endstep %}

{% step %}
Select **Entra ID** → **App registrations** → **New registration**.
{% endstep %}

{% step %}
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)**.
  {% endstep %}

{% step %}
Click **Register**.
{% endstep %}

{% step %}
In the **Manage** section of your application page, select **Certificates & secrets** → **Client secrets**.
{% endstep %}

{% step %}
Click **New client secret**.
{% endstep %}

{% step %}
In the **Add a client secret** dialog box, enter the required information:

* **Description**: The description of your client secret.
* **Expires**: Select an expiry period.
  {% endstep %}

{% step %}
Click **Add**.\ <i class="fa-chevrons-right">:chevrons-right:</i> Your new secret is generated and added to the **Client secrets** list.
{% endstep %}

{% step %}
Copy the **Value** of your secret for future use.
{% endstep %}
{% endstepper %}

## Obtain the client and tenant IDs

{% stepper %}
{% step %}
Sign in to your Microsoft Entra admin center.
{% endstep %}

{% step %}
Select **Entra ID** → **App registrations** → your application.
{% endstep %}

{% step %}
In the **Overview** section, copy the **Application (client) ID** and **Directory (tenant) ID** values for future use.
{% endstep %}
{% endstepper %}

## 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

{% stepper %}
{% step %}
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:

{% tabs %}
{% tab title="Windows, Postman, Powershell" %}

```bash
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>'
```

{% endtab %}

{% tab title="Linux, Mac" %}

```bash
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>'
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
From the response, copy the access token.
{% endstep %}

{% step %}
Decode the JWT with an application such as [JWT.io](https://jwt.io).
{% endstep %}

{% step %}
Copy the **typ**, **iss**, **sub**, and **aud** parameters for future use.
{% endstep %}
{% endstepper %}

## Register the JWKS endpoint with Collibra

Follow the instructions to [Register the JWKS endpoint](https://productresources.collibra.com/docs/collibra/latest/Default.htm#cshid=DOC0773) 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 without the trailing tenant ID. |
| JWT Audience           | The **aud** parameter from the decoded JWT.                                |

## Create a user in Collibra

Follow the instructions to [Create a user](https://productresources.collibra.com/docs/collibra/latest/Default.htm#cshid=DOC0655) 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:

{% stepper %}
{% step %}
Sign in to your Microsoft Entra admin center.
{% endstep %}

{% step %}
Select **Entra ID** → **Enterprise applications**.
{% endstep %}

{% step %}
Select **New application** → **Create your own application**.
{% endstep %}

{% step %}
In the **Create your own application** dialog box, 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)**.
  {% endstep %}

{% step %}
Click **Create**.
{% endstep %}
{% endstepper %}

<i class="fa-chevrons-right">:chevrons-right:</i> Your newly created application appears in the list of **Enterprise applications**.

{% hint style="info" %}
Collibra supports v1.0 Microsoft identity platform access tokens.
{% endhint %}

### Authorize your SCIM application

{% stepper %}
{% step %}
From the list of applications, select your new application → **Provisioning**.
{% endstep %}

{% step %}
Select **New configuration**.
{% endstep %}

{% step %}
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.
    {% endstep %}

{% step %}
Click **Test Connection**.\ <i class="fa-chevrons-right">:chevrons-right:</i> If your credentials are successfully verified, Microsoft Entra ID displays a confirmation message.
{% endstep %}

{% step %}
Click **Save** to complete the process.
{% endstep %}
{% endstepper %}

## Start and stop a provisioning job

Microsoft Entra access tokens are valid only for one hour and cannot be refreshed due to the Entra ID 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:

{% stepper %}
{% step %}
[Generate a new client secret](#secret).
{% endstep %}

{% step %}
Select **Entra ID** → **Enterprise applications** → your application → **Provisioning**.
{% endstep %}

{% step %}
On the **Provisioning** page, in the **Manage provisioning** section, select **Update credentials**.
{% endstep %}

{% step %}
Enter the new token.
{% endstep %}

{% step %}
Click **Test Connection**.\ <i class="fa-chevrons-right">:chevrons-right:</i> If your credentials are successfully verified, Microsoft Entra ID displays a confirmation message.
{% endstep %}

{% step %}
Click **Save** to complete the process.
{% endstep %}

{% step %}
Return to the **Provisioning** page and click **Start provisioning** to perform the initial synchronization of Collibra users.

{% hint style="success" %}
Wait for the process to complete and validate the results in Collibra.
{% endhint %}
{% endstep %}

{% step %}
Click **Stop provisioning**.
{% endstep %}

{% step %}
Generate a new client secret and update the credentials.
{% endstep %}

{% step %}
Start the provisioning again when you need to perform another synchronization of users and groups.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="OAuth authentication" %}

## 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 <img src="/files/4TrHCnXp2WcnOdFcaeqL" alt="Cogwheel icon" data-size="line"> **Settings** → **OAuth Applications** → **Manage OAuth**:

{% stepper %}
{% step %}
Click **Register New Application**\ <i class="fa-chevrons-right">:chevrons-right:</i> The **Register New Application** dialog box appears.

<img src="/files/jPSeCq06QmQuonuGPrtu" alt="" width="25%">
{% endstep %}

{% step %}
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. |
| Application Name | The name of you application, used to identify it in the list of registered applications.                                                                       |
| {% endstep %}    |                                                                                                                                                                |

{% step %}
Click **Register**.\ <i class="fa-chevrons-right">:chevrons-right:</i> The **Registration Confirmation** dialog box appears.

<img src="/files/INBDsnG9wzx91AvYF8mn" alt="" width="25%">
{% endstep %}

{% step %}
Copy and safely store the **Client ID** and **Client Secret**.

{% hint style="warning" %}
This is the only time you are able to see the client secret.
{% endhint %}
{% endstep %}
{% endstepper %}

## Create a SCIM application

Create a new SCIM application and authorize it:

{% stepper %}
{% step %}
Sign in to your Microsoft Entra admin center.
{% endstep %}

{% step %}
Select **Entra ID** → **Enterprise applications**.
{% endstep %}

{% step %}
Select **New application** → **Create your own application**.
{% endstep %}

{% step %}
In the **Create your own application** dialog box, 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)**.
  {% endstep %}

{% step %}
Click **Create**.
{% endstep %}
{% endstepper %}

<i class="fa-chevrons-right">:chevrons-right:</i> Your newly created application appears in the list of **Enterprise applications**.

### Authorize your SCIM application

{% stepper %}
{% step %}
From the list of applications, select your new application → **Provisioning**.
{% endstep %}

{% step %}
Select **New configuration**.
{% endstep %}

{% step %}
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 Entra ID 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.
    {% endstep %}

{% step %}
Click **Test Connection**.\ <i class="fa-chevrons-right">:chevrons-right:</i> If your credentials are successfully verified, Microsoft Entra ID displays a confirmation message.
{% endstep %}

{% step %}
Click **Save** to complete the process.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## Map SCIM app attributes

{% stepper %}
{% step %}
Sign in to your Microsoft Entra admin center.
{% endstep %}

{% step %}
Search for and select **Entra ID** → **Enterprise applications** → your application → **Provisioning**.
{% endstep %}

{% step %}
Select **Mappings** → **Provision API:Users**.
{% endstep %}

{% step %}
On the **Attribute Mapping** page, edit or add your desired mappings.

{% hint style="info" %}
Collibra supports a limited number of SCIM attributes.
{% endhint %}

* User attribute mapping

  | Microsoft Entra ID Attribute                             | API Attribute                                                           |
  | -------------------------------------------------------- | ----------------------------------------------------------------------- |
  | `userPrincipalName`                                      | `userName`                                                              |
  | `Switch([IsSoftDeleted],,"False" "True","True","False")` | `active`                                                                |
  | `Coalesce([mail], [userPrincipalName])`                  | `emails[type eq "work"].value`                                          |
  | `givenName`                                              | `name.givenName`                                                        |
  | `surname`                                                | `name.familyName`                                                       |
  | `jobTitle`                                               | `title`                                                                 |
  | `department`                                             | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department` |
  | `streetAddress`                                          | `addresses[type eq "work"].streetAddress`                               |
  | `city`                                                   | `addresses[type eq "work"].locality`                                    |
  | `state`                                                  | `addresses[type eq "work"].region`                                      |
  | `postalCode`                                             | `addresses[type eq "work"].postalCode`                                  |
  | `country`                                                | `addresses[type eq "work"].country`                                     |
  | `telephoneNumber`                                        | `phoneNumbers[type eq "work"].value`                                    |
  | `mobile`                                                 | `phoneNumbers[type eq "mobile"].value`                                  |
  | `facsimileTelephoneNumber`                               | `phoneNumbers[type eq "fax"].value`                                     |
  | `otherMails`                                             | `emails[type eq "other"].value`                                         |
  | `preferredLanguage`                                      | `locale`                                                                |
  | `employeeId`                                             | `externalId`                                                            |

{% hint style="info" %}
Collibra users have a single email address and an additional list of email addresses. In contrast, SCIM uses a list of email addresses. If the SCIM list contains only one email address or one of the email addresses is marked as primary, that email address becomes the Collibra user email address. If the SCIM list contains multiple email addresses and none is marked as primary, the operation returns an error.
{% endhint %}

* Group attribute mapping

  | Microsoft Entra ID Attribute | API Attribute |
  | ---------------------------- | ------------- |
  | `displayName`                | `displayName` |
  | `members`                    | `members`     |

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>You cannot assign roles to users via SCIM. However, you can manage groups and group membership in your IdP and disable the <strong>Groups DGC managed</strong> Console configuration option. Following the initial provisioning, your IdP groups are available in Collibra and you can start assigning roles to them.</p></div>

{% endstep %}

{% step %}
Click **Save** to complete the process.
{% endstep %}
{% endstepper %}

## Additional resources

* [Azure developer portal](https://portal.azure.com/#home)
* [Develop and plan provisioning for a SCIM endpoint in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups)
* [How Application Provisioning works in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/how-provisioning-works)
* [Customize user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes)
* [Known issues for provisioning in Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/known-issues)
* [Known issues and resolutions with SCIM 2.0 protocol compliance of the Microsoft Entra user provisioning service](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/application-provisioning-config-problem-scim-compatibility)
* [Collibra JSON Web Token authentication guide](https://developer.collibra.com/tutorials/rest-api-json-web-token/)
* [Collibra REST API authentication with JSON Web Token](https://developer.collibra.com/tutorials/rest-api-authentication-jwt/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.collibra.com/api/guides/the-system-for-cross-domain-identity-management/microsoft-entra-id-authorization-for-scim.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.