> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SSO configuration
> Let workspace users sign in with your identity provider using SAML single sign-on or social login, and provision governance reviewers automatically.
Choose how your workspace users sign in. Enabling single sign-on (SSO) delegates authentication to a trusted identity provider (IdP), removing the need for separate Oleria passwords and giving your team a consistent login experience.
From **Settings → SSO Configuration**, you can connect one or more SAML identity providers and enable Microsoft social sign-in. Google social sign-in is available by default. For the governance app, you can provision reviewers automatically the first time they sign in.
Only Administrators can change SSO settings.
## Main workspace and governance app
The **SSO Configuration** page has two tabs, each configuring sign-in for a different part of Oleria independently:
* **Main Workspace** - how everyone with a workspace role signs in to your Oleria workspace.
* **Governance App** - how reviewers sign in to the governance app to complete [access reviews](/governance/access-review), request and approve access requests, and review workflows.
Each tab has its own list of SAML identity providers and its own social sign-in settings, so you can connect different providers to each. Automatic user provisioning is available on the **Governance App** tab only.
Both tabs show the same **Oleria details** (Entity ID, ACS URL, and Single logout URL) while you add an identity provider, because they share a single service provider. This is expected - copy the same details into whichever identity provider you connect to either tab.
## SAML certificates
Connecting a SAML identity provider can involve up to three certificates. Each has a different owner and purpose, and only two of them ever need to be downloaded from Oleria and uploaded to your identity provider:
| Certificate | Provided by | Uploaded to | What it's for |
| :---------------------------------- | :--------------------- | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Request signing certificate** | Oleria | Your identity provider | Lets your identity provider verify that sign-in requests came from Oleria unmodified. Shown on the **Oleria details** step the same certificate for every identity provider on that tab. |
| **Response signing certificate** | Your identity provider | Oleria | Lets Oleria verify that SAML responses came from your identity provider unmodified. You never download or upload this one separately - it's already included in your identity provider's **Metadata** (URL or XML) that you paste into Oleria when adding the provider. |
| **Response encryption certificate** | Oleria | Your identity provider | Lets your identity provider encrypt the contents of its SAML responses so they can't be read in transit. Generated specifically for each identity provider, and not available until after you save it - see the **Encrypt SAML responses** step below. |
See [Set up common identity providers](#set-up-common-identity-providers) below for exactly where each identity provider expects the request signing and response encryption certificates.
## Connect a SAML identity provider
Adding a SAML identity provider is a two-step exchange: you copy Oleria's service provider details into your identity provider first, then tell Oleria how to reach that identity provider. This order matters: most identity providers only generate the SAML metadata Oleria needs once you finish creating the SAML app on their side, so Oleria gives you its own details first rather than asking for metadata it knows you can't have yet.
Always start sign-in from Oleria's own sign-in page: [https://www.oleria.com/sign-in](https://www.oleria.com/sign-in)
Launching from the identity provider's side fails with a generic error from Oleria's SAML service provider, even when the identity provider is configured correctly.
Go to **Settings → SSO Configuration** and select the **Main Workspace** or **Governance App** tab, depending on who should sign in through this provider.
In the **SAML IdP** card, click **Add IdP**.
On the **Oleria details** step, copy the **Entity ID**, **ACS URL**, and **Single logout URL** into your identity provider's SAML application configuration. These values identify Oleria as the service provider and tell your IdP where to send responses. Copy or download the **Request signing certificate** shown on this step too - if you enable **Sign requests** on the next step, your identity provider must have this certificate uploaded so it can verify the signed requests Oleria sends it, or sign-in through that provider will fail. See [Set up common identity providers](#set-up-common-identity-providers) below for where to upload it for your provider.
Complete the **SAML IdP details** step:
* **Name** - a label for the provider. Use 3-32 characters. The name must be unique across your entire workspace, including both tabs, cannot contain spaces, and cannot be `google`, `microsoft`, or `cognito`. **You cannot change the name after you create the provider.**
* **Sign requests** - select to sign the SAML authentication requests Oleria sends to your identity provider. Your identity provider must have the **Request signing certificate** from the previous step uploaded before you enable this, or it will reject Oleria's requests.
* **Encrypt SAML responses** - select if your identity provider requires Oleria to encrypt SAML responses. using a certificate Oleria generates specifically for this identity provider (separate from the request signing certificate, and not available until after you save the provider). If enabled, the certificate will be provided **after** the new identity provider config is saved. This is optional - SAML sign-in already runs over HTTPS - so only turn it on if your organization's security policy or your identity provider requires it. Not every identity provider supports response encryption; see [Set up common identity providers](#set-up-common-identity-providers) below for which ones do.
* **Metadata** - provide your IdP's SAML metadata in exactly one of two ways: enter a metadata **URL** (must start with `https://`), or paste the metadata **XML document's contents**. Provide one or the other, not both. Your identity provider generates this metadata once you finish creating the SAML app there with the Oleria details from the previous step.
Click **Add identity provider**. Users can now sign in through this provider.
If you selected **Encrypt SAML responses**, you will see a prompt to download its **Response encryption certificate** - this certificate is generated specifically for this provider. Upload it to your identity provider and configure it to encrypt SAML responses; see [Set up common identity providers](#set-up-common-identity-providers) below for more detailed steps.
Sign out of Oleria, select the provider on the sign-in page, and confirm you land back in Oleria.
## Set up common identity providers
Each identity provider has its own steps for creating a SAML app and generating metadata. Use these quick references alongside [Connect a SAML identity provider](#connect-a-saml-identity-provider) above - create the SAML app with your provider first, then come back here to finish adding it to Oleria.
* In the Okta Admin Console, go to **Applications** -> **Applications** -> **Create App Integration**, then select **SAML 2.0**.
* On the **Configure SAML** step, enter Oleria's **ACS URL** as the **Single sign-on URL** and Oleria's **Entity ID** as the **Audience URI (SP Entity ID)**.
* Set **Name ID format** to **Persistent**. Oleria's service provider requests a persistent NameID policy, and Okta rejects sign-in with a 400 error (`NameIDPolicy ... is not the configured Name ID Format ...`) if this doesn't match.
* Set **Application username** to **Email**. This is what determines the actual value Okta sends as the NameID - it must be the user's email address regardless of the **Name ID format** label above.
* Add an **Attribute Statement** with **Name** `email`, **Name format** `Unspecified`, and **Value** `user.profile.email`. Oleria requires this attribute to identify the signed-in user; without it, sign-in is denied even if the NameID itself contains the email.
* Add a second **Attribute Statement** with **Name** `name`, **Name format** `Unspecified`, and **Value** `user.profile.firstName + " " + user.profile.lastName`. Without it, sign-in succeeds but Oleria rejects the resulting session for missing the user's full name. Use `user.profile.$property` (not the bare `user.$property` form) - that's the syntax Okta's SAML attribute statements require for referencing profile properties. Avoid `user.profile.displayName` here: Okta only auto-derives it from first/last name until an admin ever explicitly edits it for a user, after which it becomes a static value that no longer tracks name changes and can't be reset back - Okta's own documentation recommends the explicit concatenation instead.
* On Okta Identity Engine (OIE) orgs, Attribute Statements aren't part of the app creation wizard - configure both attributes above afterward on the app's **Sign On** tab, under **Attributes Statements** (Okta's federated/custom claims), using the same `user.profile.$property` expressions.
* Assign the app to the users or groups who should sign in through Oleria.
* On the **Sign On** tab, copy the **Identity Provider metadata** URL into Oleria's **Metadata URL** field.
* If you selected **Sign requests** in Oleria, go back to the app's **General** tab, open **SAML Settings** -> **Edit**, and click **Show Advanced Settings**. Download Oleria's **Request signing certificate** in **pem** format and upload it next to **Signature Certificate**, then set **Signed Requests** to **Validate SAML requests with signature certificates**.
* If you selected **Encrypt SAML responses** in Oleria, in that same **Show Advanced Settings** view set **Assertion Encryption** to **Encrypted** and upload the **Response encryption certificate**, downloaded in **pem** format, next to **Encryption Certificate**.
See Okta's [Create SAML app integrations](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm) guide for full details.
* In the Microsoft Entra admin center, go to **Entra ID** -> **Enterprise applications** -> **New application** -> **Create your own application**, then select **Non-gallery application**.
* Open the app, select **Single sign-on** -> **SAML** -> **Basic SAML Configuration**, and enter Oleria's **Entity ID** as the **Identifier** and Oleria's **ACS URL** as the **Reply URL**. Click **Save** then close the **Basic SAML Configuration** panel.
* In the **Attributes & Claims** section, edit the **Unique User Identifier (Name ID)** claim and set its **Name identifier format** to **Persistent**. Oleria's service provider requests a persistent NameID policy, and sign-in fails if this doesn't match. Set the **Source attribute** to `user.objectid` (or another stable, opaque identifier) rather than email - Microsoft recommends this because a persistent NameID is meant to stay fixed even if a user's email address later changes, and Oleria gets the email separately from the claim below. Click **Save**.
* In that same **Attributes & Claims** section, **Add a new claim** with **Name** `email` and **Source attribute** `user.mail`, and another with **Name** `name` and **Source attribute** `user.displayname`. Leave **Namespace** blank on both - Oleria requires these two exact, short (non-URI) claim names to identify the signed-in user, and Entra's claim editor accepts a literal string in **Name** even though its default claims use long URIs. Close the **Attributes & Claims** panel after saving both new claims.
* In the **SAML Certificates** section, copy the **App Federation Metadata Url** into Oleria's **Metadata URL** field.
* If you selected **Sign requests** in Oleria, in that same **SAML Certificates** section click **Edit** across from **Verification certificates**, check **Require verification certificates** and upload Oleria's **Request signing certificate**, downloaded in **cer** format.
* If you selected **Encrypt SAML responses** in Oleria, 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** and upload the **Response encryption certificate**, downloaded in **cer** format, then activate it from the **...** menu next to the imported certificate.
See Microsoft's [Enable SAML single sign-on for an enterprise application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) and [Customize claims issued in the SAML token](https://learn.microsoft.com/en-us/entra/identity-platform/saml-claims-customization) guides for full details.
* In the Google Admin console, go to **Apps** -> **Web and mobile apps** -> **Add app** -> **Add custom SAML app**, and name the app.
* On the **Service provider details** page, enter Oleria's **ACS URL** and Oleria's **Entity ID**, and set **Name ID format** to **Persistent** (Google defaults this page's example to **Email**, so check it explicitly) - Oleria's service provider requests a persistent NameID policy, and sign-in fails if this doesn't match. Leave **Name ID** as **Basic Information > Primary email**.
* On the **Attribute mapping** step, map Google directory field **Basic Information > Primary email** to app attribute `email`. Oleria requires this attribute to identify the signed-in user.
* Google Workspace's attribute mapping only supports direct field-to-field mapping, with no way to combine fields - it exposes **First name** and **Last name** as separate directory fields but no combined full name field, so a single `name` attribute (as Oleria requires, and as Okta/Entra/OneLogin/Ping can all provide) currently can't be populated through Google Workspace's SAML app mapping UI. [Contact us](#contact-us) if this is blocking your setup.
* Turn the app **ON** for the organizational units or groups that should sign in through Oleria.
* Google Workspace doesn't expose a metadata URL, so download the **IdP metadata** file from the **Google Identity Provider details** page and paste its contents into Oleria's metadata XML field instead.
* Google Workspace doesn't support verifying signed SAML requests from a service provider, so leave **Sign requests** off in Oleria when connecting a Google Workspace identity provider.
* Google Workspace doesn't support encrypting SAML responses either, so leave **Encrypt SAML responses** off in Oleria when connecting a Google Workspace identity provider.
See Google's [Set up your own custom SAML app](https://support.google.com/a/answer/6087519) guide for full details.
* In the OneLogin admin portal, go to **Applications** -> **Add App**, search for **SAML Custom Connector (Advanced)**, and save it with a display name.
* On the **Configuration** tab, enter Oleria's **ACS URL** as the **ACS (Consumer) URL** and Oleria's **Entity ID** as the **Audience**.
* On that same **Configuration** tab, set **SAML NameID Format** to **Persistent** and **NameID value** to **Email**. Oleria's service provider requests a persistent NameID policy, and sign-in fails if this doesn't match; the NameID value must be the user's email address.
* On the **Parameters** tab, add a parameter with **Field name** `email`, **Value** set to **Email**, and check **Include in SAML assertion**. Add a second parameter with **Field name** `name`, **Value** set to **Macro** using `{firstname} {lastname}` (OneLogin has no built-in full name field), and check **Include in SAML assertion**. Oleria requires both exact attribute names to identify the signed-in user.
* On the **Users** tab, assign the app to the people or roles who should sign in through Oleria.
* On the **SSO** tab, copy the **Issuer URL** into Oleria's **Metadata URL** field.
* OneLogin's SAML Custom Connector (Advanced) doesn't support verifying signed SAML requests from a service provider, so leave **Sign requests** off in Oleria when connecting a OneLogin identity provider.
* If you selected **Encrypt SAML responses** in Oleria, check **Encrypt assertion** on the **Configuration** tab and save, then reopen the **Configuration** tab, scroll to **SAML Encryption Public Key**, and paste in the full contents of the **Response encryption certificate**, downloaded in **pem** format, then save again.
See OneLogin's [SAML Custom Connector (Advanced)](https://support.onelogin.com/kb/4266907/saml-custom-connector-advanced) guide for full details.
* In the PingOne admin console, go to **Applications** -> **Applications**, add an application, and select **SAML Application**.
* On the connection configuration screen, enter Oleria's **ACS URL** as the **ACS URLs** value and Oleria's **Entity ID** as the **Entity ID**.
* On the **Attribute Mapping** tab, click **Advanced** on the `SAML_SUBJECT` row, set **Name ID Format to send to SP** to `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`, and set **IDP Attribute Name or Literal Value** to the directory's email attribute. Oleria's service provider requests a persistent NameID policy, and sign-in fails if this doesn't match; the NameID value must be the user's email address.
* On that same **Attribute Mapping** tab, add an outgoing attribute named `email` (NameFormat `urn:oasis:names:tc:SAML:2.0:attrname-format:basic`) mapped to **Email Address**, and a second named `name` combining **Given Name** and **Family Name** via advanced mapping. Oleria requires both exact attribute names to identify the signed-in user. Advanced attribute mapping requires an external directory (LDAP/AD) - it isn't available if this application uses PingOne's own built-in Directory.
* Enable the application and assign it to the users or groups who should sign in through Oleria.
* Copy the **IdP Metadata URL** from the application's configuration and paste it into Oleria's **Metadata URL** field.
* If you selected **Sign requests** in Oleria, on the application's **Configuration** tab upload the **Request signing certificate**, downloaded in **crt** format, as the **Verification Certificate**, then enable **Enforce Signed AuthnRequest**.
* If you selected **Encrypt SAML responses** in Oleria, on that same **Configuration** tab enable **Encrypt Assertion**, upload the **Response encryption certificate**, downloaded in **crt** format, and choose **AES-256** as the encryption algorithm.
See Ping Identity's [Configuring a SAML application](https://docs.pingidentity.com/solution-guides/workforce_use_cases/htg_config_saml_app.html) and [Creating advanced attribute mappings](https://docs.pingidentity.com/pingoneforenterprise/pingone_for_enterprise/p14e_creating_advaced_attribute_mappings.html) guides for full details.
## Edit or remove an identity provider
In the identity providers list, use the actions next to a provider:
* **Edit** (pencil) - update the provider's settings. Every field except **Name** can be changed.
* **Remove** (trash) - delete the provider. Removal takes effect immediately. Users can no longer sign in through it, so make sure another sign-in method is available first.
## Troubleshoot identity provider errors
If adding or editing a SAML identity provider fails, Oleria shows the specific reason as part of the error. Look for one of these messages:
| Message | What to do |
| :------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |
| An identity provider with this name already exists. | Choose a different name. Names must be unique across both the **Main Workspace** and **Governance App** tabs. |
| The identity provider name is invalid. | Use 3-32 characters, no spaces, and avoid the reserved names `google`, `microsoft`, and `cognito`. |
| Identity provider not found. It may have already been removed. | Refresh the identity providers list. Another administrator likely removed this provider already; add it again if you still need it. |
| A metadata URL or metadata XML document is required. | Enter your identity provider's metadata as a URL or paste the XML document's contents. |
| Provide either a metadata URL or a metadata XML document, not both. | Clear one of the two metadata fields, then save again. |
| The SAML metadata URL is invalid or unreachable. | Confirm the URL is correct, starts with `https://`, and is reachable from the internet. |
| The SAML metadata XML is invalid. | Confirm you copied the complete metadata XML document's contents from your identity provider, with nothing missing or altered. |
Any other failure shows a generic error message. [Contact us](#contact-us) if it doesn't clear up after you retry.
## Troubleshoot sign-in failures
The errors above cover *adding or editing* an identity provider. Once a provider is saved, common SAML sign-in failures can be caused by certificate mismatch between Oleria and your identity provider:
| Symptom | Likely cause | What to do |
| :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sign-in through this provider fails right after you enable **Sign requests** | Your identity provider hasn't been configured with Oleria's **Request signing certificate** yet, so it rejects the signed request | Upload the certificate to your identity provider as described in [Set up common identity providers](#set-up-common-identity-providers), then try again |
| Sign-in through this provider fails right after you enable **Encrypt SAML responses** | Your identity provider isn't encrypting its responses with Oleria's **Response encryption certificate** yet | Download the certificate from the identity provider's details, upload it to your identity provider, and confirm encryption is turned on there before relying on this provider |
| Sign-in that used to work suddenly stops working, with no changes on the Oleria side | Your identity provider's own certificate - embedded in the metadata you gave Oleria - has expired or been rotated | Get fresh metadata (URL or XML) from your identity provider and update it on the [Edit](#edit-or-remove-an-identity-provider) screen for this provider |
Your identity provider's own admin console or sign-in logs usually show the specific SAML error (for example, an invalid signature or a decryption failure) in more detail than Oleria can. Check there first if a specific provider stops working.
## Enable Microsoft social sign-in
You can let users sign in with a Microsoft account instead of, or in addition to, a SAML provider.
Go to **Settings → SSO Configuration** and select the **Main Workspace** or **Governance App** tab.
Select **Enable Microsoft account**.
Save the settings. Microsoft is now available on the sign-in page.
## Automatically provision reviewers
On the **Governance App** tab, automatic user provisioning creates an Oleria account for people the first time they sign in through a SAML provider or a social connection. You do not have to add each reviewer by hand. Automatically provisioned users are added as [reviewers](/governance/scim-reviewer-provisioning).
Automatic user provisioning is available for the governance app only. It is not available on the **Main Workspace** tab.
You control who can be provisioned with two lists:
* **Allowed domains** - up to 10 email domains (for example, `acme.com`). A domain must match exactly; `acme.com` does not include subdomains such as `eu.acme.com`. Only people whose email domain is on this list can be provisioned.
* **Blocked emails** - up to 50 individual email addresses (for example, `name@acme.com`). People on this list are never provisioned, even if their domain is allowed.
Go to **Settings → SSO Configuration** and select the **Governance App** tab.
Select **Enable automatic user provisioning**.
Under **Allowed domains**, add the email domains that should be provisioned automatically. Optionally, add addresses to **Blocked emails** to exclude specific people.
Click **Save preferences**. The new settings apply to the next sign-in. They do not change accounts that already exist.
You must add at least one allowed domain before you can save with automatic user provisioning enabled. Saving with the toggle on and no allowed domains fails.
When automatic user provisioning is off, someone who signs in through SSO but does not already have an Oleria account is denied access. Either select **Enable automatic user provisioning** or add the person in [Manage Users](/administration/manage-users) first.
## Contact us
For questions, contact us at [support@oleria.com](mailto:support@oleria.com).