> ## 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 Entra ID: end-to-end SSO and SCIM setup

> Connect Microsoft Entra ID to Oleria for single sign-on and SCIM provisioning, covering both the Main Workspace and the Governance App, and Entra's one-Entity-ID-per-app rule.

This page walks through connecting Microsoft Entra ID to Oleria from a blank slate: creating the enterprise application, wiring up single sign-on (SSO), and turning on directory provisioning (SCIM), for whichever combination of Main Workspace and Governance App you need. It draws on [SSO configuration](/administration/sso-configuration), [SCIM user provisioning](/administration/scim-user-provisioning), and [Governance App SCIM provisioning](/administration/scim-governance-provisioning) - see those pages for the full request/response reference and troubleshooting detail; this page focuses on getting from zero to a working Entra connection, and on one Entra-specific wrinkle that may trip one up when they try to connect both tabs.

<Note>
  This page is about signing in to Oleria and provisioning Oleria accounts from Entra ID. It is not the same as the [Microsoft Entra ID integration](/integrations/microsoft-entra-id) under **Integrations**, which connects Entra as a read-only data source so Oleria can analyze *your Entra tenant's* identities and access - that integration doesn't affect who can sign in to Oleria or how.
</Note>

## Overview

### Main Workspace vs. Governance App

Oleria has two independent surfaces, each with its own sign-in and provisioning configuration:

* **Main Workspace** - where administrators, operators, and analysts run Oleria itself: posture, access graph, workflows, and settings.
* **Governance App** - a separate portal where reviewers and approvers complete [access reviews](/governance/access-review), act on access requests, and work governance queues. Governance app users are a distinct population from workspace users, typically much larger (anyone in the org who might approve or review something), and usually don't need any other access to Oleria.

Each surface has its own tab in **Settings → SSO Configuration** and its own tab in **Settings → SCIM Configuration**, with separate identity provider lists, separate SCIM credentials, and separate SCIM base URLs. You can connect Entra to either, or both. Critically for Entra specifically: **both tabs share the same Oleria service provider** - the same **Entity ID** and the same **ACS URL** - see [Entra's one-app-per-Entity-ID rule](#entras-one-app-per-entity-id-rule) below before you create a second Entra app for the second tab.

### SSO vs. SCIM vs. automatic user provisioning

Oleria has three related but independent mechanisms. SSO only authenticates; SCIM and automatic user provisioning both create Oleria accounts without an administrator adding them by hand, which makes them easy to mix up, but they work very differently:

|                             | SSO                                                                                       | SCIM                                                                                           | Automatic user provisioning                                                                        |
| :-------------------------- | :---------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| Solves                      | Authentication - how a user proves who they are when signing in                           | Provisioning - how an Oleria account gets created, updated, and removed                        | An Oleria setting that creates an account the moment someone signs in and doesn't already have one |
| Direction                   | Entra redirects the user's browser to Oleria with a signed SAML assertion at sign-in time | Entra's provisioning engine calls Oleria's SCIM API directly, independent of anyone signing in | Triggered as a side effect of a successful SAML or social sign-in; nothing is pushed from Entra    |
| Configured where            | **Settings → SSO Configuration**, either tab                                              | **Settings → SCIM Configuration**, either tab                                                  | **Settings → SSO Configuration**, **Governance App** tab only                                      |
| Can deactivate/remove users | No                                                                                        | Yes                                                                                            | No - it only ever creates accounts                                                                 |
| Without it                  | Users sign in with a social login or in rare cases a local account                        | An administrator adds, updates, and removes users by hand                                      | Only administrators, or SCIM, create accounts                                                      |

See [Automatically provision reviewers](/administration/sso-configuration#automatically-provision-reviewers) for the full detail on that setting - [Part 2](#part-2-set-up-scim) of this page is about SCIM, not automatic user provisioning.

### Possible provisioning flows

Because these mechanisms are independent, and each applies per tab, several combinations are all valid. Pick the one that matches what you're trying to achieve before you start:

| Flow                              | Main Workspace             | Governance App                                           | When to use it                                                                                                                                                                                                                                                                                                                                                                                                     |
| :-------------------------------- | :------------------------- | :------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SSO only                          | Entra SAML                 | Entra SAML                                               | Small, stable user list you're comfortable adding by hand in [Manage Users](/administration/manage-users), but want Entra credentials for sign-in. Apply to either tab independently, or both (one shared Entra app either way - see [below](#entras-one-app-per-entity-id-rule)).                                                                                                                                 |
| SCIM only                         | Entra SCIM                 | Entra SCIM                                               | Users should come from Entra automatically, but you're not ready to move sign-in off social login yet. Apply to either tab independently, or both.                                                                                                                                                                                                                                                                 |
| SSO + SCIM (recommended)          | Entra SAML + SCIM          | Entra SAML + SCIM                                        | Full end-to-end: Entra group membership determines who has an Oleria account and what role they hold, and the same Entra credentials sign them in, including automatic deactivation when someone is unassigned. This is what the rest of this page sets up. On both tabs at once, this needs one shared SSO app plus a separate provisioning-only app per tab - see [Set up the other tab](#set-up-the-other-tab). |
| SSO + automatic user provisioning | N/A - Governance App only  | Entra SAML + Oleria's automatic user provisioning toggle | Lighter-weight than SCIM - no provisioning connector to build in Entra, accounts just appear the first time someone signs in - but there's no automatic deprovisioning, and it's gated only by email domain, not Entra app assignment. Good for "let anyone at the company become a reviewer" without building a directory sync.                                                                                   |
| Split by surface                  | Manual, or a different IdP | Entra SAML + SCIM                                        | Common when only the Governance App needs to reach a broad, automatically-provisioned population (for example, every employee as a potential reviewer), while a small workspace admin team is managed separately. Also sidesteps the Entity ID rule entirely, since only one Oleria tab uses Entra.                                                                                                                |

This page sets up the recommended SSO + SCIM flow. If you only need SSO or only SCIM, skip the part you don't need - each part is independent. If you'd rather use automatic user provisioning instead of SCIM for the Governance App, see the [note at the end of Part 2](#part-2-set-up-scim). If you need **both** Oleria tabs connected to Entra, read the next section before creating a second enterprise application.

### Entra's one-app-per-Entity-ID rule

Microsoft Entra requires every SAML relying party - every enterprise application configured for SAML SSO - to have a unique Entity ID (Identifier) within the tenant:

> "There cannot be two applications in a single Microsoft Entra tenant with the same entity identifier." - [Microsoft Learn](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso-rpsts)

Entra enforces this because it uses the Entity ID to work out which application should receive a given SAML response; without a unique identifier per app, it can't disambiguate. This is sometimes described as one Entity ID per "relying party trust" (RPT) - that's not a separate object you configure, it's just what Entra calls an application once it's set up for SAML SSO. Every enterprise app with SAML SSO configured is a relying party trust; there's no way to do SAML SSO without one, and no way around the uniqueness rule by avoiding the term.

This collides with Oleria's design: as the [SSO configuration](/administration/sso-configuration#main-workspace-and-governance-app) page notes, the **Main Workspace** and **Governance App** tabs show the *same* Entity ID and ACS URL, because they share one Oleria service provider. If you create two separate Entra enterprise apps - one per Oleria tab - both need Oleria's Entity ID, and Entra will reject the second one with an error like "please enter an identifier which is unique within your organization."

**The fix:** use a single Entra enterprise application for both tabs, rather than creating two. Complete [Part 1](#part-1-set-up-sso) once to create that one app, then when you reach the **Governance App** tab in Oleria, add its identity provider using the *same* Entra app's federation metadata URL instead of creating a second app. One Entra app, one Entity ID, satisfies Entra's rule, and both Oleria tabs get a working IdP.

<Note>
  A single shared Entra app means the same set of assigned Entra users/groups can sign in through either tab - Entra assignment doesn't distinguish which Oleria tab a sign-in is destined for, since that's determined by which button the user selects on Oleria's own sign-in page. If you need a genuinely different population gated at the identity provider for each tab, don't reuse one Entra app; instead, connect Entra to only one tab and use a different IdP, or manual provisioning, for the other.
</Note>

## Prerequisites

* Administrator access to your Oleria workspace, and Global Administrator (or equivalent) access in Entra to create and configure enterprise applications.
* Decide which tab(s) - **Main Workspace**, **Governance App**, or both - you're connecting Entra to, and whether you want SSO, SCIM, or both for each. See [Possible provisioning flows](#possible-provisioning-flows) above.
* For SCIM into the **Main Workspace** tab: know which Oleria roles (`admin`, `operator`, `analyst`, `governance-operator`, `identity-lifecycle-operator`) your Entra groups should map to. See [How Oleria maps roles and groups](/administration/scim-user-provisioning#how-oleria-maps-roles-and-groups).
* For SCIM: a Microsoft Entra ID P1 or P2 license, required for automatic provisioning (and for token encryption, if you use it).

## Part 1: Set up SSO

<Steps>
  <Step title="Open Oleria's SSO configuration page">
    In Oleria, go to **Settings → SSO Configuration**, select the **Main Workspace** or **Governance App** tab depending on which one you're connecting first, and click **Add IdP** in the **SAML IdP** card.
  </Step>

  <Step title="Create the Entra enterprise application">
    In the Microsoft Entra admin center, go to **Entra ID → Enterprise applications → New application → Create your own application**, select **Non-gallery application**, and name it something that identifies it as the Oleria connection (for example `Oleria`) - if you plan to [share this one app across both tabs](#entras-one-app-per-entity-id-rule), avoid naming it after just one tab.
  </Step>

  <Step title="Copy Oleria's SP details into Entra">
    On Oleria's **Oleria details** step, copy the **Entity ID** and **ACS URL**. In the Entra app, select **Single sign-on → SAML → Basic SAML Configuration**, and enter them as the **Identifier** and **Reply URL**. Click **Save** and close the panel. Also copy or download Oleria's **Request signing certificate** shown on Oleria's **Oleria details** step - you'll need it later in this Part if you turn on **Sign requests**.
  </Step>

  <Step title="Configure the NameID and required claims">
    In **Attributes & Claims**:

    * Edit the **Unique User Identifier (Name ID)** claim, set **Name identifier format** to **Persistent**, and set the **Source attribute** to `user.objectid` (or another stable, opaque identifier) - Oleria's service provider requires a persistent NameID policy and rejects sign-in otherwise.
    * Add a new claim named `email` with source attribute `user.mail`, and another named `name` with source attribute `user.displayname`. Leave **Namespace** blank on both - Oleria requires these two exact, short claim names.

    See [Enter the SAML IdP details](/administration/sso-configuration#connect-a-saml-identity-provider) for why each of these is required.
  </Step>

  <Step title="Assign users and grab the metadata">
    Assign the users or groups who should be able to sign in through Oleria to the app, then in **SAML Certificates**, copy the **App Federation Metadata Url**.
  </Step>

  <Step title="Enter the SAML IdP details in Oleria">
    Back in Oleria, complete the **SAML IdP details** step: give the provider a **Name** (3-32 characters, unique across both tabs, no spaces, and not `google`, `microsoft`, or `cognito` - you can't change it later), paste the Entra metadata URL into **Metadata**, and decide whether to turn on **Sign requests** and/or **Encrypt SAML responses**. Click **Add identity provider**.
  </Step>

  <Step title="If you turned on Sign requests: upload the request signing certificate to Entra">
    Skip this step if you left **Sign requests** off. Otherwise, in the Entra app's **SAML Certificates** section, click **Edit** across from **Verification certificates**, check **Require verification certificates**, and upload Oleria's **Request signing certificate**, downloaded in **cer** format earlier in this Part.
  </Step>

  <Step title="If you turned on Encrypt SAML responses: download and upload the response encryption certificate">
    Skip this step if you left **Encrypt SAML responses** off. Otherwise, back in Oleria you'll see a prompt to download the **Response encryption certificate** generated specifically for this provider - download it in **cer** format. In Entra, open the app's **Token encryption** page (a separate page from **SAML Certificates** - requires a Microsoft Entra ID P1 or P2 license), select **Import Certificate**, upload the certificate, then activate it from the **...** menu next to the imported certificate.
  </Step>

  <Step title="Confirm sign-in works">
    Sign out of Oleria, go to [https://www.oleria.com/sign-in](https://www.oleria.com/sign-in), select the new provider, and confirm you land back in Oleria signed in.
  </Step>
</Steps>

## Part 2: Set up SCIM

<Steps>
  <Step title="Get Oleria's SCIM credentials">
    In Oleria, go to **Settings → SCIM Configuration** and select the same tab you used in Part 1 (**Main Workspace** or **Governance App**). Copy the **SCIM Base URL**, **Client ID**, **Client Secret**, and **OAuth Token URL**.
  </Step>

  <Step title="Mint a bearer token">
    Follow [Authenticate to the SCIM API](/administration/scim-user-provisioning#authenticate-to-the-scim-api) to exchange the Client ID and Client Secret for a bearer token. Entra's provisioning integration needs a single token pasted into its configuration, not a client ID/secret pair it refreshes itself, so use whichever token lifetime your organization is comfortable re-entering on expiry.
  </Step>

  <Step title="Open the Provisioning tab">
    On the same Entra enterprise application from Part 1 (or, if you're only setting up SCIM without SSO, a new **Non-gallery application**), select **Provisioning** and set **Provisioning Mode** to **Automatic**.
  </Step>

  <Step title="Enter the SCIM connection details">
    Under **Admin Credentials**, enter Oleria's **SCIM Base URL** as the **Tenant URL** and the bearer token from step 2 as the **Secret Token**. Click **Test Connection** to confirm Entra can reach Oleria, then **Save**.
  </Step>

  <Step title="Review the attribute mappings">
    Entra proposes default attribute mappings for **Provision Microsoft Entra ID Users**. Confirm `userPrincipalName` (or another attribute holding the user's email) maps to `userName`, and that a display name maps through to `name.formatted` - adjust if your tenant's defaults don't line up with the [Users](/administration/scim-user-provisioning#users) attribute table.

    <Note>
      **Main Workspace only:** Oleria grants roles through group membership, not directly on the user (see [How Oleria maps roles and groups](/administration/scim-user-provisioning#how-oleria-maps-roles-and-groups)). Leave **Provision Microsoft Entra ID Groups** enabled so group membership syncs along with users.

      **Governance App:** there is no group-to-role mapping to configure - every provisioned user is assigned the single `reviewer` role automatically. You can turn group provisioning off and provision users only.
    </Note>
  </Step>

  <Step title="Main Workspace only: sync groups from Entra">
    Under **Provisioning → Mappings → Scope**, assign each Entra security group whose members should get Oleria access to the app. You don't need to create anything in Oleria first, or call the SCIM API yourself - Entra creates the matching group in Oleria automatically via SCIM, with membership synced, but without a role set. A newly-created group falls back to Oleria's read-only `analyst` role until you assign it a different one in the next step.
  </Step>

  <Step title="Main Workspace only: assign each group a role in Oleria">
    In Oleria, under **Settings** open **Manage Users**, select the **Groups** tab, and for each group you push, select it, click **Change role**, choose the role it should map to, and click **Save**. Every current and future member of the group inherits that role. See [Assign a role to a group](/administration/manage-users#assign-a-role-to-a-group) for the full walkthrough.
  </Step>

  <Step title="Scope and start provisioning">
    Under **Users and groups**, assign the users or groups that should get Oleria accounts. On the **Provisioning** tab, set **Scope** to **Sync only assigned users and groups** (recommended over syncing the whole directory), then click **Start provisioning**.
  </Step>

  <Step title="Verify">
    Watch the **Provisioning** tab's sync status - the first cycle can take anywhere from about 20 minutes to a few hours. In Oleria, confirm the new users appear (**Main Workspace**: in [Manage Users](/administration/manage-users) with the expected role; **Governance App**: in the governance reviewer list). Unassign a test user in Entra and confirm they lose access in Oleria on the next cycle.
  </Step>
</Steps>

<Note>
  **Alternative for the Governance App:** if you don't need directory-driven deprovisioning and don't want to build the Entra provisioning connector above, you can skip this Part entirely and use Oleria's built-in automatic user provisioning instead - it only requires SSO (Part 1) to already be working. Follow [Automatically provision reviewers](/administration/sso-configuration#automatically-provision-reviewers) to enable it and set allowed email domains. Remember this is not SCIM: it only creates accounts on sign-in and never deactivates them, so it's not a substitute for SCIM if you need automatic offboarding.
</Note>

## Set up the other tab

If you need both tabs connected to Entra, don't repeat Part 1 with a new enterprise application - see [Entra's one-app-per-Entity-ID rule](#entras-one-app-per-entity-id-rule) above. Instead:

* **SSO:** in Oleria, go to the other tab's **SSO Configuration** and add an identity provider using the *same* Entra app's **App Federation Metadata Url** from Part 1.
* **SCIM:** Entra allows only one provisioning job per enterprise application, so you can't add a second **Provisioning** configuration to the same app you used for SSO. Create a second **Non-gallery application** instead, used for provisioning only - leave its **Single sign-on** section unconfigured entirely. Entra's Entity ID uniqueness rule only applies to apps with SAML SSO configured, so a provisioning-only app with no SAML section touched never collides with it. Point this second app's **Provisioning** tab at the other tab's SCIM Base URL and bearer token, following [Part 2](#part-2-set-up-scim) again on the new app.

## Troubleshooting

* Adding or editing the identity provider in Oleria: [Troubleshoot identity provider errors](/administration/sso-configuration#troubleshoot-identity-provider-errors)
* Sign-in failures after the provider is saved: [Troubleshoot sign-in failures](/administration/sso-configuration#troubleshoot-sign-in-failures)
* "Please enter an identifier which is unique within your organization" when creating a second Entra app: see [Entra's one-app-per-Entity-ID rule](#entras-one-app-per-entity-id-rule) - use one shared app instead of two.
* SCIM request/response errors: the [SCIM user provisioning](/administration/scim-user-provisioning) and [Governance App SCIM provisioning](/administration/scim-governance-provisioning) reference pages cover the request and response shape for every endpoint.

## Contact us

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