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

# Set up single sign-on with SAML or OIDC

> Connect Okta, Microsoft Entra ID, or another SAML 2.0 or OIDC identity provider so employees sign in to OpenWhispr with their company account.

Single sign-on lets employees sign in to OpenWhispr with their company identity provider instead of a password. Once your domain is verified, anyone with an email at that domain is sent to your identity provider when they sign in, and you can require it.

## How it works

Two systems take part in every sign-in:

* **Your identity provider (IdP)**, such as Okta, holds your company accounts. It checks the password and any multi-factor step.
* **OpenWhispr is the service provider (SP)**: the app people sign in to. It never sees the password. It trusts your IdP's signed answer about who the person is.

```mermaid theme={null}
sequenceDiagram
  participant E as Employee
  participant App as OpenWhispr app
  participant OW as OpenWhispr sign-in
  participant IdP as Your IdP (Okta)
  E->>App: Sign in with SSO, enter work email
  App->>OW: Opens the browser
  OW->>IdP: Domain is verified, send them to Okta
  IdP->>E: Company login (and MFA, if you use it)
  IdP->>OW: Signed confirmation of who they are
  OW->>App: Back in the app, signed in
```

Setup is the one-time work of introducing the two. You give your IdP OpenWhispr's addresses, you give OpenWhispr your IdP's details, and you prove you own your email domain.

## Before you start

You need:

* an active OpenWhispr Enterprise workspace with owner or admin access. Enterprise is set up with our team: you create an OpenWhispr account and a workspace in the desktop app, and we activate it as Enterprise
* a company email domain, such as `acme.com`. Personal email domains like Gmail or Outlook are refused
* administrator access to your identity provider
* access to your domain's DNS, to add one TXT record

SSO setup lives in the OpenWhispr admin portal at [admin.openwhispr.com](https://admin.openwhispr.com) under **Security > Single sign-on**.

## Values to give your identity provider

Every URL below includes your **Provider ID**, so choose it first. Use lowercase letters, numbers, `-`, and `_`, for example `acme-okta`. When you enter a Provider ID in **Add provider**, the admin portal shows these URLs filled in. Copy them from there; the patterns here are for reference.

| Setting in your identity provider | Value |
| - | - |
| SAML Single sign-on URL / ACS URL | `https://auth.openwhispr.com/api/auth/sso/saml2/sp/acs/{providerId}` |
| SAML Audience URI / SP Entity ID | `https://auth.openwhispr.com/api/auth/sso/saml2/sp/metadata?providerId={providerId}` |
| OIDC Sign-in redirect URI | `https://auth.openwhispr.com/api/auth/sso/callback/{providerId}` |
| Initiate login URI / app-tile launch URL | `https://auth.openwhispr.com/api/desktop-signin/sso?providerId={providerId}` |

Once the provider is saved, the SP Entity ID URL also serves OpenWhispr's SAML service-provider metadata, which some identity providers, such as Microsoft Entra ID, can import.

## Connect your identity provider

**1. Start adding the provider**

In the admin portal, open **Security > Single sign-on** and select **Add provider**. Choose **SAML** or **OIDC**, then enter:

* **Provider ID**, for example `acme-okta`
* **Email domain**, for example `acme.com`

The dialog now shows the URLs for this Provider ID. Keep them at hand for the next step.

**2. Create the app in your identity provider**

> [tab] Okta (SAML)
>
> In the Okta Admin Console, create a new app integration and choose **SAML 2.0**. On the SAML settings page:
>
> | Okta setting | Value |
> | - | - |
> | Single sign-on URL | The SAML ACS URL |
> | Audience URI (SP Entity ID) | The SAML SP Entity ID URL |
> | Name ID format | **EmailAddress** |
> | Application username | **Email** |
>
> Leave Okta's signature settings at their defaults (Response and Assertion signed).
>
> Attribute statements are optional. OpenWhispr reads `email`, `givenName`, and `surname`, or `displayName` for the full name. Without an `email` attribute, the Name ID is used as the email.
>
> So employees can start from their Okta dashboard, set **Login initiated by** to **Either Okta or App**. See [Sign in from an app tile](#sign-in-from-an-app-tile).
>
> Assign the people or groups who should use OpenWhispr. Then open the app's **Sign On** tab and view the SAML setup instructions. You need three values from there:
>
> * **Identity Provider Issuer**, which looks like `http://www.okta.com/exk…`
> * **Identity Provider Single Sign-On URL**
> * **X.509 Certificate**

> [tab] Okta (OIDC)
>
> In the Okta Admin Console, create a new app integration and choose **OIDC - OpenID Connect** with the application type **Web Application**.
>
> | Okta setting | Value |
> | - | - |
> | Grant type | **Authorization Code** |
> | Sign-in redirect URIs | The OIDC Sign-in redirect URI |
>
> OpenWhispr requests the scopes `openid`, `email`, and `profile`.
>
> So employees can start from their Okta dashboard, set **Login initiated by** to **Either Okta or App**, choose **Redirect to app to initiate login (OIDC Compliant)**, and set **Initiate login URI** to the app-tile launch URL. See [Sign in from an app tile](#sign-in-from-an-app-tile).
>
> Assign the people or groups who should use OpenWhispr. You need three values:
>
> * **Issuer URL**: your Okta domain, for example `https://acme.okta.com`
> * **Client ID**
> * **Client secret**

> [tab] Microsoft Entra ID (SAML)
>
> In the Microsoft Entra admin center, open **Enterprise applications**, select **New application**, then **Create your own application**. Open its **Single sign-on** page and choose **SAML**.
>
> Under **Basic SAML Configuration**:
>
> | Entra setting | Value |
> | - | - |
> | Identifier (Entity ID) | The SAML SP Entity ID URL |
> | Reply URL (Assertion Consumer Service URL) | The SAML ACS URL |
> | Sign on URL | Leave empty |
>
> Enter the Identifier and Reply URL manually for this initial setup. The SP Entity ID URL returns `404` until you save the provider in the next step. After saving, you can download OpenWhispr's metadata from that URL and import it with **Upload metadata file**.
>
> OpenWhispr reads only an attribute named exactly `email`, and otherwise uses the Name ID as the email. Entra's default claims don't match: they use URI names such as `…/claims/emailaddress`, and the default Name ID is `user.userprincipalname`, which isn't always the email. Under **Attributes & Claims**, do one of these:
>
> * Edit **Unique User Identifier (Name ID)** to use the source attribute `user.mail` with the **Email address** format.
> * Add a claim named `email` with the source attribute `user.mail`.
>
> Assign the people or groups who should use OpenWhispr. You need three values from the **Single sign-on** page:
>
> * **Microsoft Entra Identifier**, the IdP issuer
> * **Login URL**, the sign-in URL
> * **Certificate (Base64)**, downloaded from **SAML Certificates**

**3. Finish adding the provider**

Back in the admin portal dialog, enter the values from your identity provider.

| Protocol | Field | Where it comes from |
| - | - | - |
| SAML | IdP issuer | Okta's **Identity Provider Issuer**, or Entra's **Microsoft Entra Identifier** |
| SAML | Sign-in URL | Okta's **Identity Provider Single Sign-On URL**, or Entra's **Login URL** |
| SAML | Signing certificate | The X.509 certificate, pasted in full |
| OIDC | Issuer URL | Your identity provider's issuer, for example `https://acme.okta.com` |
| OIDC | Client ID | The app's client ID |
| OIDC | Client secret | The app's client secret |

Save the provider.

**4. Verify your domain**

On the new provider, select **Get DNS record**. Add the TXT record it shows to your domain's DNS. Its name has the form `_better-auth-token-{providerId}.{domain}`, for example `_better-auth-token-acme-okta.acme.com`. Then select **Verify domain**.

Until the domain is verified, nobody from that domain is sent through SSO. DNS changes can take a while to appear, so try again later if verification fails right away.

**5. Test with a pilot employee**

Have an assigned employee open the OpenWhispr desktop app, select **Sign in with SSO**, and enter their work email. They finish sign-in in the browser and return to the app.

**6. Require SSO and connect directory sync (optional)**

Once sign-in works, you can turn on **Require SSO** under **Security > Single sign-on**. It blocks password and social sign-in for the verified domain. The workspace owner is exempt, so a misconfigured identity provider can always be undone.

To create and remove workspace members from your directory, set up [SCIM provisioning](https://docs.openwhispr.com/help/it/scim-provisioning.md). If you plan to use it, read its rollout order before you enable **Require SSO**.

## How people sign in

* **Employees** open the OpenWhispr desktop app, select **Sign in with SSO**, and enter their work email.
* **Admins** sign in to the admin portal at [admin.openwhispr.com/sign-in](https://admin.openwhispr.com/sign-in) with **Continue with SSO**.

## Who joins your workspace

The first time someone signs in through SSO, OpenWhispr adds them to your workspace as a member, and they take a [seat](https://docs.openwhispr.com/help/account/seats.md). You don't invite them first.

So your identity provider decides who gets OpenWhispr. Only people assigned to the OpenWhispr app in your IdP can finish signing in. For a pilot, assign just the pilot group, then assign more people when you're ready to roll out.

If you use [SCIM provisioning](https://docs.openwhispr.com/help/it/scim-provisioning.md), your directory decides instead: people are added when your IdP sends them over, and removed when it deactivates them.

## Sign in from an app tile

With the Okta settings above, an employee can click the OpenWhispr tile on their Okta dashboard. The tile starts a normal sign-in and opens the OpenWhispr desktop app, so the app must be installed on that computer.

> [!NOTE]
>
> Signing in from an app tile requires the latest OpenWhispr service update. If a tile click doesn't open the app, employees can sign in from the desktop app as described above.

## Troubleshooting

| Symptom | What to check |
| - | - |
| Employees aren't sent to SSO | The domain is verified under **Security > Single sign-on**. Until it is, nobody from that domain is routed through SSO |
| SSO isn't offered for one person | Their email domain matches the provider's **Email domain** exactly |
| The app asks the person to switch account | They're signed in to your identity provider as someone else in the browser. Have them switch to their own account and try again |
| SAML sign-in fails after a certificate change | The signing certificate was rotated in your identity provider. Follow [Rotate a SAML signing certificate](#rotate-a-saml-signing-certificate) to replace the provider's certificate |

### Rotate a SAML signing certificate

The admin portal cannot edit an existing provider. To use a new signing certificate, remove the provider, add it again, and re-verify the domain:

1. If [directory sync](https://docs.openwhispr.com/help/it/scim-provisioning.md) uses this provider, pause sync and move its connection to another verified provider first. Pausing alone does not allow removal.
2. If this is the last verified provider, turn off **Require SSO** before removing it.
3. Under **Security > Single sign-on**, remove the provider, then add it again with the same Provider ID and the new signing certificate.
4. Select **Get DNS record**, update the TXT record with the new value, and select **Verify domain**.
5. Test sign-in with a pilot employee before restoring **Require SSO** or moving directory sync back and resuming it.

## Related

* [SCIM provisioning](https://docs.openwhispr.com/help/it/scim-provisioning.md)
* [Managed Amazon Bedrock and Azure OpenAI](https://docs.openwhispr.com/help/it/managed-enterprise-ai.md)
* [Network allowlist](https://docs.openwhispr.com/help/it/network-allowlist.md)
* [Answering a security review](https://docs.openwhispr.com/help/privacy/for-your-it-team.md)


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