> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Purview

> Connect a Microsoft Purview account to Oleria to discover its Data Map collections, data sources, and scans, its Unified Catalog governance domains, the users, groups, and non-human identities that can reach them, and Data Map audit activity.

Connect Microsoft Purview to Oleria to see who can administer and read your Purview Data Map and Unified Catalog, and how they got that access. Oleria reads one Purview account through the Microsoft Purview APIs with a Microsoft Entra service principal, and adds user and group details from Microsoft Graph. You can review collection role assignments, and remove them from Oleria.

Every principal in Purview is a Microsoft Entra user, group, service principal, or managed identity. Oleria identifies each one by its Microsoft Entra object ID, the same ID that the [Microsoft Entra ID](https://docs.oleria.com/integrations/microsoft-entra-id.md) integration uses, so a person's Purview access joins their Entra identity.

## What Oleria discovers

| Area | Detail |
| :- | :- |
| **Users** | Every Microsoft Entra user who holds Purview access: a collection role, directly, through a group, or through a Microsoft Entra directory role such as Global Administrator, a Unified Catalog role, ownership of a data product, or an Azure role on the Purview account. Guests are marked as external. Each user has their email, status, creation date, last password change, last Microsoft Entra sign-in, multi-factor authentication (MFA) status, and registered authentication methods. Holders of Collection administrator, Data Governance Administrator, Governance Domain Creator, Governance Domain Owner, and the Azure Owner and User Access Administrator roles are flagged as administrators. |
| **Non-human identities** | Service principals and managed identities that hold Purview access. When you enter the account's Azure subscription ID and assign the app the Azure Reader role on the account, the Purview account's own system-assigned and user-assigned managed identities are included. |
| **Groups** | Microsoft Entra groups that hold Purview access, with their members and nested groups. |
| **Resources and access** | The Purview account, its collections and subcollections, the data sources registered in each collection, and each data source's scans, with the scan's credential name and type, integration runtime, scan rule set, and schedule. Each collection role holder appears on the collection where the role is assigned. Optionally, the Unified Catalog's governance domains and subdomains with their role holders, the data products that Purview lets the app read with their owners, and the Azure role holders on the Purview account. |
| **Roles** | The Microsoft Entra directory roles that a Purview policy names, with their members. Purview names **Global Administrator** as a Collection administrator of the root collection when it creates an account, so your Global Administrators appear as root Collection administrators. This needs `RoleManagement.Read.Directory`. |
| **Activity** | Data Map events from the Microsoft Purview audit log, such as created, updated, and deleted assets, classifications, and glossary terms, and sensitivity label changes. |

## Prerequisites

* A Microsoft Purview account in the commercial cloud. The free version of Microsoft Purview has no Purview account, so it can't be connected.
* A **Global Administrator** or **Privileged Role Administrator**, to grant admin consent for Microsoft Graph application permissions. A Cloud Application Administrator or Application Administrator can't grant them.
* A **Collection administrator** of the account's root collection, or a domain admin, to assign the app its Data Map roles.
* The audit log turned on in your organization, for Data Map activity. Audit (Standard) is on by default for most Microsoft 365 organizations.
* Optional, for governance domains: a **Data Governance Administrator** or **Governance Domain Creator**, to assign the Governance Domain Owner role on each governance domain.
* Optional, for Azure role holders and the account's managed identities: a **User Access Administrator** or **Role Based Access Control Administrator** on the Purview account, and its Azure subscription ID.
* Optional: **Microsoft Entra ID P1 or P2**, for last sign-in and MFA status. Without it, Oleria still syncs, and those fields show as unavailable.

## Choose an authentication method

The connection form offers three methods. Pick one:

1. **Authenticate via Microsoft (OAuth)**, the default. You grant admin consent to Oleria's Microsoft app. You don't register an app or manage a credential.
2. **Client Secret Authentication**. You register your own app in Microsoft Entra ID and give Oleria a client secret.
3. **Client Certificate Authentication**. You register your own app and give Oleria a certificate and its unencrypted private key.

With OAuth, go on to [Connect Microsoft Purview to Oleria](#connect-microsoft-purview-to-oleria) first, because granting consent adds Oleria's app to your tenant if it isn't there yet. Then [assign the Purview roles](#assign-purview-roles-to-the-app). For either of the other methods, register the app first:

**1. Register an application**

Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an **Application Developer**. Go to **Entra ID** -> **App registrations** -> **New registration**. Name the app (for example, `Oleria Purview`) and select **Register**. On its **Overview** page, copy the **Application (client) ID** and **Directory (tenant) ID**.

**2. Create a credential**

> [tab] Client secret
>
> Select **Certificates & secrets** -> **Client secrets** -> **New client secret**, add a description, choose an expiration, and select **Add**. Copy the secret's **Value**. Microsoft never displays it again after you leave the page. A client secret lasts at most 24 months, so update the integration in Oleria before it expires.

> [tab] Client certificate
>
> Select **Certificates & secrets** -> **Certificates** -> **Upload certificate**, choose the public certificate (`.cer`, `.pem`, or `.crt`), and select **Add**. Combine the certificate and its unencrypted private key into one PEM file, then base64-encode the whole file. The key must be a PEM block that starts with `-----BEGIN PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----`. For example, with the certificate in `certificate.pem` and the key in `private_key.pem`:
>
> ```bash macOS or Linux theme={null}
> cat certificate.pem private_key.pem > oleria-purview.pem
> base64 < oleria-purview.pem | tr -d '\n' > oleria-purview.b64
> ```
>
> ```powershell Windows (PowerShell) theme={null}
> Get-Content certificate.pem, private_key.pem |
>     Set-Content oleria-purview.pem
> [Convert]::ToBase64String([IO.File]::ReadAllBytes("oleria-purview.pem")) |
>     Set-Content oleria-purview.b64 -NoNewline
> ```
>
> Paste the contents of `oleria-purview.b64` into Oleria's **Client Certificate** field, then delete `oleria-purview.pem` and `oleria-purview.b64`, because they hold the unencrypted private key. Update the integration in Oleria before the certificate expires.

**3. Grant Microsoft Graph permissions**

Select **API permissions** -> **Add a permission** -> **Microsoft Graph** -> **Application permissions**. Add these permissions, select **Add permissions**, then select **Grant admin consent for** your tenant:

```
User.Read.All
GroupMember.Read.All
AuditLogsQuery.Read.All
```

Optionally, also add:

* `Application.Read.All`, for service principal details.
* `AuditLog.Read.All`, for last sign-in and MFA status. It also needs Microsoft Entra ID P1 or P2.
* `Organization.Read.All`, so Oleria matches sign-ins on your verified domains.
* `Member.Read.Hidden`, for the members of groups with hidden membership.
* `RoleManagement.Read.Directory`, for the members of the Microsoft Entra roles, such as Global Administrator, that Purview makes Collection administrators.

Oleria can't connect without `User.Read.All`. Without one of the other permissions, Oleria still syncs, with less detail:

| Permission | Without it |
| :- | :- |
| `GroupMember.Read.All` | Groups appear by object ID, without their names or members, and groups that own a data product aren't linked to it. Removing a collection role from a user or a group fails when Oleria must check their group memberships. |
| `AuditLogsQuery.Read.All` | Activity syncs fail with an error that names this permission. After you grant it, Oleria reads the activity it missed, up to 180 days back. |
| `Application.Read.All` | Service principals and managed identities appear without their Microsoft Entra details, by object ID unless a group's member list or the Purview account's Azure record names them. A user or app deleted from Microsoft Entra ID that still holds a Purview role appears as an enabled non-human identity. Activity by service principals isn't linked to them. Removing a collection role fails when Oleria must check the groups of a service principal, or the groups that Oleria's app belongs to. |
| `AuditLog.Read.All` | Last sign-in isn't shown, and MFA status shows as unavailable. |
| `Organization.Read.All` | Oleria matches sign-ins on the domains of your users' sign-in names instead of your verified domains. |
| `Member.Read.Hidden` | Groups with hidden membership appear without members. |
| `RoleManagement.Read.Directory` | The Microsoft Entra roles that a Purview policy names, such as Global Administrator, don't appear, and their members don't appear with the access those roles give them. Removing a collection role doesn't check whether the principal also holds it through one of those roles. |

## Assign Purview roles to the app

Purview doesn't use Microsoft Graph permissions for its own data. The app reads Purview through roles that you assign to its service principal inside Purview. Do this for every authentication method.

With OAuth, the app is Oleria's Microsoft 365 app, the same app that the **SharePoint & OneDrive** integration without write actions, and the **Microsoft Dynamics 365**, **Microsoft Fabric**, and **Microsoft Power Platform** integrations, use with OAuth. If you've already connected one of them with OAuth, the app is already in your tenant: find it under **Entra ID** -> **Enterprise apps** -> **All applications** in the Microsoft Entra admin center, and assign the roles before you connect. Otherwise, it's added to your tenant when an administrator grants admin consent in [Connect Microsoft Purview to Oleria](#connect-microsoft-purview-to-oleria). Note the app name that Microsoft shows on the consent screen. The roles you assign belong to that app, not to this connection alone. To keep Purview access separate, use your own app registration.

**1. Assign the Data Map roles on the root collection**

Sign in to the Microsoft Purview portal as a Collection administrator of the root collection. When the account is your tenant's primary account in the new Microsoft Purview portal, its root collection is the default domain: open **Data Map**, select **Domains**, then select the default domain. Other accounts in the tenant use the classic portal: select **Data Map** -> **Collections**, then select the root collection, which has the same name as your Purview account.

Select the **Role assignments** tab. For each of these roles, select **Edit role assignments** or the person icon, search for the app, and select **OK**:

* **Collection administrator**, which Oleria needs to read collections and their role assignments.
* **Data source administrator**, which Oleria needs to read data sources and scans. Without it, the sync still reads collections and access, without data sources and scans. With your own app registration, Oleria doesn't connect until the app holds both roles.

Subcollections inherit the roles from the root collection. Collection administrator always reaches every subcollection. Data source administrator doesn't reach a subcollection that restricts inherited permissions, so assign it on that subcollection too. A direct subcollection of the default domain can't restrict what it inherits from the default domain.

**2. Optional: assign Unified Catalog roles**

Skip this step if you don't need governance domains. The Unified Catalog is available only with the tenant-level account of the new Microsoft Purview portal.

For each governance domain, go to **Unified Catalog** -> **Catalog management** -> **Governance domains** and select the domain. On the **Roles** tab, select **+** next to **Governance Domain Owner**, search for the app, select it, and select **Save**. Purview can take a few hours to let the app read the domain after you assign the role.

Governance Domain Owner lets the app read the domain and its role holders, but Purview refuses it the domain's data products. Oleria skips data products it can't read, and the sync continues.

> [!NOTE]
>
> Governance Domain Owner can delegate domain permissions and set domain-level access policies. Oleria only reads the Unified Catalog. It doesn't change it.

**3. Optional: assign the Azure Reader role**

Skip this step if you don't need the Azure role holders and managed identities of the Purview account. In the [Azure portal](https://portal.azure.com), open the Purview account. Select **Access control (IAM)** -> **Add** -> **Add role assignment**, and select the **Reader** role. On the **Members** tab, select **User, group, or service principal**, select **Select members**, choose the app, and select **Review + assign**. Reader lets the app view the account, but not change it.

To find the subscription ID, go to **Subscriptions** in the Azure portal, select the subscription that holds the Purview account, and copy the **Subscription ID** from the **Essentials** section.

## Connect Microsoft Purview to Oleria

**1. Open the integration**

Sign in to your Oleria workspace, go to **Integrations**, and find **Microsoft Purview**. Select the **+** icon (**Add Integration for Microsoft Purview**), or **Connect** in the list view.

**2. Complete the connection form**

| Field | Notes |
| :- | :- |
| Authentication Method | **Authenticate via Microsoft (OAuth)** (default), **Client Secret Authentication**, or **Client Certificate Authentication**. |
| Tenant Id | Client secret or certificate only. The **Directory (tenant) ID** of your app registration. You can't change it after you connect. |
| Client Id | Client secret or certificate only. The **Application (client) ID** of your app registration. |
| Client Secret | Client secret only. The secret value. |
| Client Certificate | Client certificate only. The base64-encoded PEM file with the certificate and its unencrypted private key. |
| Purview Account Name | Required. The account name in the account's Data Map endpoint: for `https://contoso.purview.azure.com`, enter `contoso`. It's the name of the Purview account in the Azure portal, 3 to 63 letters, digits, or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. You can't change it after you connect. |
| Azure Subscription Id (optional) | The ID of the Azure subscription that holds the Purview account, as a GUID. With it, and the Azure **Reader** role on the account, Oleria also collects the account's Azure role holders and managed identities. |
| I authorize Oleria to perform write actions in Microsoft Purview (recommended) | Selected by default. Clear it if you don't want Oleria to remove collection roles. While it's cleared, Oleria refuses remediation actions, but it can still revert earlier ones. You can change it later in the connection settings. |

**3. Authenticate**

Select **Authenticate**. With OAuth, Microsoft asks an administrator to grant consent, then returns you to Oleria. Before it saves the connection, Oleria checks that it can read users from Microsoft Graph, and role assignments and data sources from the Purview account.

With OAuth, consent adds the app to your tenant, so it can't hold a Purview role yet. When Purview answers that the app holds no role (status `403`), Oleria saves the connection so that you can assign the roles after consent. [Assign the Purview roles](#assign-purview-roles-to-the-app) next. Until the app holds Collection administrator, the sync of resources and access fails. Activity still syncs, without links to collections. If Oleria shows that Microsoft Purview refused the app instead, assign the roles and select **Authenticate** again.

## Verify the integration

Confirm that the connection appears on the **Connected** tab of the **Integrations** page with a status of **Healthy**. After the first sync, review users, non-human identities, groups, and collections in your Oleria workspace. If the first sync fails, check that the app holds Collection administrator on the root collection. If data sources or scans are missing, check that it holds Data source administrator there too. Both are in [Assign Purview roles to the app](#assign-purview-roles-to-the-app). The integration's **Capabilities and operation readiness** section lists the permissions each capability needs. It names the Data Map roles `Microsoft Purview Data Map role: Collection administrator` and `Microsoft Purview Data Map role: Data source administrator`.

## Remediation actions

Oleria offers **Revoke permission to resource instance** for collections when **I authorize Oleria to perform write actions in Microsoft Purview** is selected. It needs the Collection administrator role that the sync uses, plus the `User.Read.All` and `GroupMember.Read.All` permissions, so that Oleria can check group memberships before it removes a role. **Capabilities and operation readiness** lists all three as the action's required permissions.

| Target | What Oleria does | Revert |
| :- | :- | :- |
| Collection | Removes a user, group, or service principal from the collection role being revoked, on the collection where the role is assigned. If the principal no longer holds the role there, nothing changes. | Adds the principal back to the removed roles. If the principal has been given one of those roles on the collection in another way since, the revert fails and changes nothing. |

Oleria refuses to revoke:

* Access to the account, a data source, a scan, or a Unified Catalog item. Only collection roles can be removed.
* The app's own role on a collection.
* The last Collection administrator of a root collection. Oleria counts a Microsoft Entra directory role named there, such as Global Administrator, as another Collection administrator.
* A group that is the app's only path to Collection administrator on the collection, because Oleria couldn't revert the change.
* A role that the principal also holds on a parent collection that this collection inherits from. Remove it on the parent collection.
* A role that the principal also holds through a group. Oleria names the group, the role, and the collection. Remove the principal from the group, or remove the group's role in Purview.
* A role that the principal also holds through a Microsoft Entra directory role named on the collection or a parent collection, directly or through a role-assignable group. Remove the principal's directory role assignment in Microsoft Entra ID.

Without `RoleManagement.Read.Directory`, Oleria can't read who holds those directory roles. It removes the principal's direct role without checking them, so a principal who also holds one of those directory roles keeps the access.

> [!NOTE]
>
> Purview doesn't let you remove a Collection administrator that a collection inherits from its parent collection.

## Known limitations

* **Commercial cloud only.** Purview accounts in the US Government and China clouds can't be connected.
* **One Purview account per connection.** To connect several accounts in one tenant, add one Oleria integration per account. The Unified Catalog belongs to the whole tenant, so each of those integrations shows it.
* **Last activity is the last Microsoft Entra sign-in**, not the last use of Purview. It needs `AuditLog.Read.All` and Microsoft Entra ID P1 or P2.
* **Activity looks back up to 180 days** on the first sync. After that, Oleria reads new events with a two-hour delay. Microsoft doesn't guarantee how soon an event reaches the audit log, and an event that reaches it more than two hours late isn't collected.
* **Activity covers the whole tenant.** Data Map events from every Purview account in the tenant are collected. Only events that name one of this account's collections, data sources, or scans are linked to it.
* **Some Data Map events show Purview's own operation name.** Creating a collection, data source, or scan appears as a created object, on the collection, data source, or scan it names. Other collection, role assignment, data source, and scan events appear as custom activity, with the operation name that Purview records.
* **Data source and scan creation events name no user.** Purview records the client software that made the change, not who made it.
* **Inherited collection roles** appear once, on the collection where they're assigned, not on each subcollection.
* **Deleted principals are skipped** when the app has `Application.Read.All`. A role assignment that names a user or app that no longer exists in Microsoft Entra ID isn't shown. Without that permission, a deleted user or app that still holds a Purview role appears as an enabled non-human identity, named by its object ID.
* **The free version of Microsoft Purview can't be connected.** It has no Purview account.
* **Not synced:** Microsoft Purview portal role groups and compliance role groups and their members, Microsoft Entra roles that no Purview policy names, data loss prevention (DLP) policies, and sensitivity labels and their policies.
* **Unified Catalog roles can't be removed** from Oleria, and **disabling non-human identities** isn't offered from this integration.

## Troubleshooting

When Oleria can't connect, it shows **Error creating integration**, followed by `received invalid inputs. actual error:` and one of these messages:

| Message | Fix |
| :- | :- |
| `Microsoft Graph refused the app (status <status> <code>): grant the application permission User.Read.All with admin consent` | Add the `User.Read.All` application permission and select **Grant admin consent for** your tenant. |
| `Microsoft Purview refused the app (status <status> <code>): in the Microsoft Purview portal, assign the app's service principal the <role> role on the root collection of account "<account>"` | Assign the named role (Collection administrator or Data source administrator) to the app on the root collection, as in [Assign Purview roles to the app](#assign-purview-roles-to-the-app). Then select **Authenticate** again. |
| `the Microsoft Purview account "<account>" could not be reached at https://<account>.purview.azure.com: check the account name` | Check **Purview Account Name**. |
| `a valid Directory (tenant) ID is required` | Enter the **Directory (tenant) ID** from your app registration's **Overview** page. |

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.