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

# Okta: end-to-end SSO and SCIM setup

> Connect Okta to Oleria for single sign-on and user provisioning, covering both the Main Workspace and the Governance App.

This page walks through connecting Okta to Oleria from a blank slate: creating the Okta app, 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 Okta connection.

<Note>
  This page is about signing in to Oleria and provisioning Oleria accounts from Okta. It is not the same as the [Okta integration](/integrations/okta) under **Integrations**, which connects Okta as a data source so Oleria can analyze your Okta tenant's identities and access. That integration does not 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 Okta to one, the other, or both - they don't have to match. For example, it's common to enable SSO and SCIM for the Governance App (so every employee can be provisioned as a reviewer automatically) while managing the smaller set of Main Workspace administrators by hand.

### 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                   | Okta redirects the user's browser to Oleria with a signed SAML assertion at sign-in time | Okta'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 Okta     |
| 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 + SCIM (recommended)          | Okta SAML + SCIM           | Okta SAML + SCIM                                        | Full end-to-end: Okta group membership determines who has an Oleria account and what role they hold, and the same Okta credentials sign them in, including automatic deactivation when someone is unassigned. This is what the rest of this page sets up.                                                                            |
| SSO only                          | Okta SAML                  | Okta SAML                                               | Small, stable user list you're comfortable adding by hand in [Manage Users](/administration/manage-users), but want Okta credentials for sign-in. Apply to either tab independently, or both.                                                                                                                                        |
| SCIM only                         | Okta SCIM                  | Okta SCIM                                               | Users should come from Okta automatically, but you're not ready to move sign-in off social login yet. Apply to either tab independently, or both.                                                                                                                                                                                    |
| SSO + automatic user provisioning | N/A - Governance App only  | Okta SAML + Oleria's automatic user provisioning toggle | Lighter-weight than SCIM - no provisioning connector to build in Okta, accounts just appear the first time someone signs in - but there's no automatic deprovisioning, and it's gated only by email domain, not Okta group/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 | Okta 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                                                                                                                     |

This page sets up the recommended SSO + SCIM flow, one tab at a time. If you only need one tab, skip the [other tab's section](#set-up-the-other-tab). 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).

## Prerequisites

* Administrator access to your Oleria workspace and Okta admin access with permission to create app integrations.
* Decide which application(s) - **Main Workspace**, **Governance App**, or both - you're connecting Okta 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 Okta groups should map to. See [How Oleria maps roles and groups](/administration/scim-user-provisioning#how-oleria-maps-roles-and-groups).

## 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 application you're connecting first, and click **Add IdP** in the **SAML IdP** card.
  </Step>

  <Step title="Create the Okta app">
    In the Okta Admin Console, go to **Applications → Applications → Create App Integration**, select **SAML 2.0**, and name it something that identifies which Oleria tab it's for (for example `Oleria - Main Workspace` or `Oleria - Governance App`) - this matters once you've done this twice for both tabs.
  </Step>

  <Step title="Copy Oleria's SP details into Okta">
    On Oleria's **Oleria details** step, copy the **Entity ID** and **ACS URL**. On Okta's **Configure SAML** step, enter them as the **Audience URI (SP Entity ID)** and **Single sign-on URL**. Copy or download the **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">
    Still on **Configure SAML**, set **Name ID format** to **Persistent** and **Application username** to **Email** - Oleria's service provider requires a persistent NameID policy and rejects sign-in otherwise.
  </Step>

  <Step title="Add the required attribute statements">
    <Note>
      This step is on a **different page** than the previous one for most Okta orgs today. On Okta Identity Engine (OIE) orgs - the default for new orgs - Attribute Statements aren't part of the **Configure SAML** page at all; add them afterward on the app's **Sign On** tab, under **Attribute Statements**. Only on legacy Okta Classic Engine orgs do they appear further down the same **Configure SAML** page.
    </Note>

    Add an attribute statement **Name** `email`, **Name format** `Unspecified`, **Value** `user.profile.email`, and a second **Name** `name`, **Name format** `Unspecified`, **Value** `user.profile.firstName + " " + user.profile.lastName`.

    See [Connect a SAML identity provider](/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 app to the users or groups who should be able to sign in to Oleria, then on the **Sign On** tab copy the **Identity Provider 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 applications, no spaces, and not `google`, `microsoft`, or `cognito` - you can't change it later), paste the Okta 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 Okta">
    Skip this step if you left **Sign requests** off. Otherwise, go back to the Okta app's **General** tab, open **SAML Settings → Edit**, and click **Show Advanced Settings**. Upload Oleria's **Request signing certificate** (downloaded in **pem** format earlier in this Part) next to **Signature Certificate**, then set **Signed Requests** to **Validate SAML requests with signature certificates**.
  </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 **pem** format. In Okta, in that same **Show Advanced Settings** view, set **Assertion Encryption** to **Encrypted** and upload the certificate next to **Encryption 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

You can add SCIM provisioning to the same Okta app you just created for SSO - Okta supports provisioning on custom SAML apps once you turn it on.

<Steps>
  <Step title="Enable provisioning on the Okta app">
    Open the same Okta app from Part 1. On the **General** tab, click **Edit** next to **App Settings**, check **Enable SCIM provisioning**, and click **Save**. A new **Provisioning** tab appears on the app.
  </Step>

  <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="Configure the API integration">
    On the Okta app's **Provisioning** tab, select **Integration**, click **Edit**. Enter Oleria's **SCIM Base URL** as the **SCIM connector base URL**, for unique identifier enter **userName**, and check **Push New Users**, **Push Profile Updates**, and **Push Groups**.
    Set **Authentication Mode** to **OAuth 2**, under **OAuth 2** set **Grant Type** to **Client Credentials**, and enter Oleria's **OAuth Token URL** as the access token endpoint along with the **Client ID** and **Client Secret** you copied.

    <Note>
      Oleria's SCIM API only issues short-lived tokens through this client credentials exchange - it does not accept a single, static, long-lived bearer token. Use **OAuth 2 / Client Credentials** here, not the **HTTP Header** (bearer token) authentication mode. Okta mints and automatically refreshes its own token from the Client ID and Client Secret, so there's nothing to manually re-enter later. See [Authenticate to the SCIM API](/administration/scim-user-provisioning#authenticate-to-the-scim-api) for how this same OAuth 2.0 Client Credentials flow works if you're ever calling the API directly instead of through Okta.
    </Note>
  </Step>

  <Step title="Turn on the provisioning actions you need">
    Under **Provisioning → To App**, click **Edit** and enable **Create Users**, **Update User Attributes**, and **Deactivate Users**.
  </Step>

  <Step title="Main Workspace only: push groups from Okta">
    <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)).

      **Governance App:** there is no group-to-role mapping to configure - every provisioned user is assigned the single `reviewer` role automatically. You only need users pushed, not groups.
    </Note>

    In Okta, go to the app's **Push Groups** tab and push each Okta group whose members should get Oleria access. Okta then creates the matching group in Oleria automatically via SCIM, with membership synced, but without a role set. Okta's Push Groups doesn't support mapping a role or any other custom attribute onto the group it creates, so 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="Assign and provision">
    Assign the users or groups who should get Oleria accounts to the app (**Main Workspace**: via the groups you just pushed; **Governance App**: directly, or via any group). Okta provisions matching users into Oleria within its usual sync interval.
  </Step>

  <Step title="Verify">
    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). Deactivate or unassign a test user in Okta and confirm they lose access in Oleria.
  </Step>
</Steps>

<Note>
  **Alternative for the Governance App:** if you don't need directory-driven deprovisioning and don't want to build the Okta 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

Okta has no restriction on reusing the same **Audience URI (SP Entity ID)** or SCIM base URL pattern across multiple apps, so connecting the second tab is simply repeating [Part 1](#part-1-set-up-sso) and [Part 2](#part-2-set-up-scim) with a second, separately-named Okta app pointed at the other tab's Oleria details and SCIM credentials. You do not need to reuse or share anything between the two Okta apps.

## 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)
* 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).