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

# Rights-Protected Documents

> Let the crawler index documents protected by Microsoft Purview sensitivity labels (Azure Rights Management): choose a mode, configure it, verify it

A document protected by a **Microsoft Purview** sensitivity label that applies encryption (Azure Rights Management) reaches the crawler encrypted. The `prismeai-crawler` service can decrypt it **in memory** before parsing, so its text is indexed like any other document's. The stored file is never modified: downloaded again, it is still protected.

This feature is in **beta**, and **off by default**. Until it is configured, protected documents are refused with `MipNotConfigured` instead of being indexed as unreadable content.

**Requirements:**

* Platform, crawler and search engine **v27.10.0** or later, with the `prismeai-core` and `prismeai-apps` charts of the same release. Application mode alone works from v27.9.1.
* The Microsoft commercial cloud. The US Government (GCC High) and China (21Vianet) clouds are not supported.

## Choose a mode

`MIP_MODE` sets who asks Microsoft for each document's key. It has no default, and the crawler never falls back from one mode to the other.

| | `delegated` | `application` |
| - | - | - |
| Rights used to obtain the key | The owner of the SharePoint connection the document comes from | An Entra application holding `Content.SuperUser` |
| What can be decrypted | Only the documents that person may open | Any protected document of the tenant |
| Documents covered | Documents synchronized by the SharePoint connector | Every document the crawler parses: connector documents, uploaded files, files found by a website crawl |
| Microsoft permission | `user_impersonation` on Azure Rights Management, delegated, on the SharePoint connector's app | `Content.SuperUser` on Azure Rights Management, application, with admin consent |
| Secret held by the crawler | None | A client secret |
| Pods that reach Microsoft | Platform runtime | Crawler |
| Name in the Rights Management usage log | The connection owner | The application |

Choose `delegated` unless you must index protected files that do not come from the SharePoint connector (uploads, other connectors, websites): it needs no tenant-wide permission.

## Delegated mode

**1. Give the crawler its platform identity**

The crawler authenticates to the platform with a Kubernetes service account token. With the Helm charts, keep `global.platformServiceAccount.enabled: true` (the default) in both `prismeai-core` and `prismeai-apps`, and set `global.apiUrl` and `global.internalApiUrl` in the `prismeai-apps` values. Without the charts, see `PLATFORM_SERVICE_ACCOUNTS` in [Environment variables](https://docs.prisme.ai/self-hosting/kubernetes/environment-variables.md) and the `PLATFORM_TOKEN_*` variables [below](#crawler-settings).

**2. Allow Rights Management on the SharePoint connector**

The SharePoint connections of your knowledge bases must sign in per user (OAuth), usually with the connector's central client, see [SharePoint](https://docs.prisme.ai/apps-store/marketplace/connectors/sharepoint.md). On the app registration they use, in Microsoft Entra, add **API permissions > Add a permission > Azure Rights Management Services > Delegated permissions > `user_impersonation`**. Grant admin consent if your tenant does not let users consent.

Then, in the connector's configuration app, add `https://aadrm.com/user_impersonation` to the **Scopes** of the central client (maintainer view), and to those of any workspace that uses its own Entra client or sets its own **Scopes**. **Scopes** replaces the default list, so also list the scopes the connector uses: read-write by default for the central client, read-only for a workspace's own client (see [SharePoint](https://docs.prisme.ai/apps-store/marketplace/connectors/sharepoint.md)). Refresh tokens must stay enabled. For example, with the read-only scopes:

```text theme={null}
offline_access https://graph.microsoft.com/Sites.Read.All https://graph.microsoft.com/Files.Read.All https://graph.microsoft.com/User.Read https://aadrm.com/user_impersonation
```

Each owner of an existing connection reconnects once. Until then, their protected documents are refused with `MipOwnerNotConnected`.

**3. Open the egress from the runtime**

Allow the platform runtime pods to reach `login.microsoftonline.com` and `api.aadrm.com` on port 443. See [Network](#network).

**4. Configure the crawler**

Set `MIP_MODE=delegated`, `MIP_TENANT_ID`, `MIP_RMS_SERVICE_ID` and `MIP_ALLOWED_LABELS` on `prismeai-crawler`, then restart it. See [Crawler settings](#crawler-settings).

## Application mode

> [!WARNING]
>
> `Content.SuperUser` lets its holder obtain the key of **any** protected document in your tenant, whatever rights the document grants. Microsoft then logs the application, not a person. Grant it to an application registration created for this purpose only, with no other permission. The label allowlist is what bounds it: anyone who can upload a file into a knowledge base can have it decrypted, even a file they may not open.

**1. Register an application**

In Microsoft Entra, **App registrations > New registration**: single tenant, no redirect URI. Note its **Application (client) ID**, and create a client secret under **Certificates & secrets**.

**2. Grant Content.SuperUser**

**API permissions > Add a permission > Azure Rights Management Services > Application permissions > `Content.SuperUser`**, then **Grant admin consent**. The tenant's super-user feature (`Enable-AipServiceSuperUserFeature`) is not needed.

**3. Open the egress from the crawler**

Allow the crawler pods to reach `login.microsoftonline.com` and `api.aadrm.com` on port 443. See [Network](#network).

**4. Configure the crawler**

Set `MIP_MODE=application`, `MIP_TENANT_ID`, `MIP_CLIENT_ID`, `MIP_CLIENT_SECRET`, `MIP_RMS_SERVICE_ID` and `MIP_ALLOWED_LABELS` on `prismeai-crawler`, then restart it. See [Crawler settings](#crawler-settings).

## Crawler settings

Every `MIP_*` setting the mode needs is required. If one is missing, nothing is decrypted, and the startup log names what is missing.

| Variable | Mode | Description | Default |
| - | - | - | - |
| `MIP_MODE` | Both | `delegated` or `application` | |
| `MIP_TENANT_ID` | Both | Directory (tenant) ID of the Entra tenant your documents belong to | |
| `MIP_RMS_SERVICE_ID` | Both | Your tenant's `RightsManagementServiceId`, **not** the tenant ID. A document whose licence names another one is refused without contacting Microsoft | |
| `MIP_ALLOWED_LABELS` | Both | Comma-separated label GUIDs that may be decrypted, see [Which labels are decrypted](#which-labels-are-decrypted). Unset, nothing is decrypted | |
| `MIP_CLIENT_ID` | `application` | Application (client) ID of the registration holding `Content.SuperUser` | |
| `MIP_CLIENT_SECRET` | `application` | Its client secret. Provide it from a Kubernetes Secret | |
| `MIP_OWNER_NOT_CONNECTED_RETENTION_DAYS` | `delegated` | Days a document stays indexed while its connection owner is signed out. `0` removes it at the first refusal | `30` |
| `PLATFORM_TOKEN_FILE` | `delegated` | The crawler's service account token. Set by the `prismeai-apps` chart | `/var/run/secrets/prisme.ai/token` |
| `PLATFORM_TOKEN_ORIGINS` | `delegated` | Comma-separated platform API origins (`scheme://host[:port]`) the token may be sent to. Set by the `prismeai-apps` chart from `global.apiUrl` and `global.internalApiUrl` | |

With Helm, in the `prismeai-apps` values:

```yaml theme={null}
prismeai-crawler:
  env:
    - name: MIP_MODE
      value: delegated
    - name: MIP_TENANT_ID
      value: <tenant-id>
    - name: MIP_RMS_SERVICE_ID
      value: <rights-management-service-id>
    - name: MIP_ALLOWED_LABELS
      value: <label-guid>,<label-guid>
  # Application mode only: MIP_CLIENT_ID in env, MIP_CLIENT_SECRET from a Secret
  # envFrom:
  #   - secretRef:
  #       name: crawler-mip
```

One crawler deployment decrypts the documents of **one** Microsoft tenant.

### Find the identifiers

* **`RightsManagementServiceId`**, from a Windows machine, with an administrator of the rights management service:

  ```powershell theme={null}
  Install-Module -Name AIPService
  Connect-AipService
  Get-AipServiceConfiguration | Select-Object RightsManagementServiceId
  ```

* **Label GUIDs**: in the Microsoft Purview portal, **Information protection > Sensitivity labels**, or with Security & Compliance PowerShell (`Connect-IPPSSession`, then `Get-Label | Format-Table DisplayName, Guid`). Braces and letter case do not matter.

## Which labels are decrypted

* **`MIP_ALLOWED_LABELS` is the ceiling of the deployment.** A label outside it is never decrypted. Add `sharepoint-library` to also decrypt files that a SharePoint library with IRM protected without a label. Protection applied by a person without a label is never decrypted.
* **Knowledge bases can narrow it.** The platform, each organization and each knowledge base can set [decryptable labels](https://docs.prisme.ai/products/ai-knowledge/knowledge-bases.md#decryptable-labels). In delegated mode, a label must be allowed both there and in `MIP_ALLOWED_LABELS`; with no list set at any level, `MIP_ALLOWED_LABELS` alone applies. In application mode the lists do not stop decryption: a document whose label they exclude is indexed but not returned by search.

> [!WARNING]
>
> An indexed document no longer carries its own rights: anyone who can read the knowledge base can read what was decrypted into it. Allow only labels whose protection already lets **every reader of the knowledge bases** this crawler feeds read the document, such as a label for all employees. The same holds for `sharepoint-library`, whose audience is the library's readers.

## Network

| Host (port 443) | Reached by, `delegated` | Reached by, `application` |
| - | - | - |
| `login.microsoftonline.com` | Platform runtime pods | Crawler pods |
| `api.aadrm.com` | Platform runtime pods | Crawler pods |

A TLS-inspecting proxy on these paths breaks decryption: exempt both hosts, or trust its CA with `global.extraCABundle` in the chart of the pods that reach Microsoft (`prismeai-core` in delegated mode, `prismeai-apps` in application mode), see [Trusting an extra CA bundle](https://docs.prisme.ai/self-hosting/kubernetes/configuration.md#trusting-an-extra-ca-bundle). See also [Network Policies](https://docs.prisme.ai/self-hosting/kubernetes/network-policies.md).

## Verify

After a restart, the crawler logs exactly one of these lines:

| Log message | Meaning |
| - | - |
| `Protected-document decryption enabled` | Configured. The `mode` field gives the mode, `allowed_labels` the number of labels allowed |
| `Protected-document decryption disabled (not configured)` | Nothing is set: the default |
| `Protected-document decryption disabled: incomplete configuration` | The `missing` field names the missing settings |
| `Protected-document decryption disabled: unknown MIP_MODE` | `MIP_MODE` is neither `delegated` nor `application` |
| `Protected-document decryption disabled: MIP_MODE not set` | Some settings are set, but not `MIP_MODE` |

In application mode, it then checks its access to Microsoft, without requesting any key: `Azure RMS credentials accepted` or `… could not be verified at boot` (wrong tenant, client ID or secret, or no egress to `login.microsoftonline.com`), and `Rights-management endpoint reachable` or `… unreachable` (egress or TLS inspection; this check does not use `HTTPS_PROXY`, so behind a proxy it can warn while decryption works). Admin consent is only checked by the first document: without it, documents are refused with `MipAccessDenied`.

In delegated mode, check `Platform token origins`, which lists the platform origins the crawler sends its token to. A warning ending with `platform calls go unauthenticated` means the platform will refuse them: no origin listed, or no token mounted.

Then index a protected document whose label is allowed: it becomes searchable, and the key request appears in your Rights Management usage log (`Get-AipServiceUserLog`) from the next day (UTC).

## Troubleshooting

A refused document shows its code in its error, in the knowledge base's document list. Once the cause is fixed, reindex the document, or click **Retry failed documents** on its connection.

| Code | Cause and action |
| - | - |
| `MipNotConfigured` | Decryption is off or incomplete. Check the [startup log](#verify) |
| `MipLabelNotAllowed` | The label is outside `MIP_ALLOWED_LABELS` or the knowledge base's decryptable labels, or the document is protected without a label. Allow the label if it belongs in the knowledge base |
| `MipAccessDenied` | Microsoft refused the key. Application mode: check the admin consent of `Content.SuperUser`. Delegated mode: the connection owner may not open this document |
| `MipExtractionDenied` | The label lets the reader view but not extract the content. Only a change of the label's rights in Purview allows indexing it |
| `MipForeignTenant` | The document was protected by another organization. Expected: it cannot be decrypted. If your own documents get it, check `MIP_RMS_SERVICE_ID` and `MIP_TENANT_ID` |
| `MipOwnerNotConnected` | Delegated: the connection owner's sign-in no longer works, or lacks the Rights Management consent. The owner reconnects the SharePoint connection |
| `MipNoDelegate` | Delegated: no connection owner can be asked: a file uploaded by hand (expected in this mode), a connector other than SharePoint, or an owner who lost access to the knowledge base |
| `MipCrawlerNotAuthenticated` | Delegated: the platform refused the crawler's token. Check `global.platformServiceAccount` in both charts and `global.apiUrl` in `prismeai-apps`. If you renamed the releases or the crawler's ServiceAccount, set `global.platformServiceAccount.accounts.crawler.subject` in `prismeai-core`; if the crawler runs in another cluster, `global.platformServiceAccount.issuer` |
| `MipEngineWithoutRelay` | Delegated: the knowledge base's search engine does not know the platform's relay yet. The platform sets it when it is upgraded, if the search engine already runs v27.9.1 or later; otherwise contact support |
| `MipRelayRequestRejected` | Delegated: the platform rejected the request. Check that the crawler and the platform run the same release; an isolated occurrence clears at the next synchronization |
| `MipServiceUnavailable` | Microsoft or the platform did not answer or, in application mode, the client ID or secret is wrong. Retried automatically; if it persists, check the [startup log](#verify) and the [network](#network). In delegated mode, also check the `error` events of the Storage workspace |
| `MipPasswordProtected` | The file is encrypted with a password, which no service can decrypt |
| `MipPdfNotSupported`, `MipUnsupportedContainer` | The file uses a protection format the crawler does not decrypt |

Changing `MIP_MODE` does not re-check documents already indexed at once: reindex them to apply the new mode now.

## Operating requirements and limits

* **Temporary files hold decrypted content.** Some conversions write into `TMP_MEDIA_FOLDER` (default `/tmp/prismeai-crawler/`). Put it on a tmpfs or an encrypted volume, and keep it out of backups.
* **Images of a protected document are not indexed**, only its text.
* **Not decrypted:** Double Key Encryption, password-protected files, and PDFs in the older SharePoint IRM format.

## Related

> [card] [Crawler & SearchEngine](https://docs.prisme.ai/self-hosting/entreprise/crawler-searchengine.md)
>
> Deploying and configuring the crawler

> [card] [Decryptable labels](https://docs.prisme.ai/products/ai-knowledge/knowledge-bases.md#decryptable-labels)
>
> Narrowing the labels per platform, organization and knowledge base


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