> For the complete documentation index, see [llms.txt](https://docs.dispel.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dispel.com/secure-and-govern/identity-providers.md).
# Identity Providers (SSO)
Let your users sign in to Dispel with your existing identity provider. Connect Microsoft Entra ID, Okta, or PingIdentity over OAuth (OIDC) or SAML for single sign-on.
## Overview
Connecting an identity provider (IdP) lets your users sign in to Dispel with the same enterprise credentials they already use everywhere else — single sign-on (SSO). Instead of managing a separate Dispel password, your IdP handles authentication and tells Dispel who the user is.
Dispel supports four identity providers. Active Directory connects over LDAP(S); Microsoft Entra ID, Okta, and Ping Identity each connect over either OAuth (OIDC) or SAML:
* [**Active Directory**](/secure-and-govern/identity-providers/active-directory.md) — Microsoft's on-premises directory service.
* [**Microsoft Entra ID**](/secure-and-govern/identity-providers/microsoft-entra-id.md) — Microsoft's cloud identity platform (formerly Azure AD).
* [**Okta**](/secure-and-govern/identity-providers/okta.md) — Okta's enterprise identity platform.
* [**PingIdentity**](/secure-and-govern/identity-providers/ping-identity.md) — Ping's federated identity platform.
{% hint style="info" %}
**Where to find it.** Sign in as an organization administrator and open **Settings → Integrations** (or the dedicated **Settings → Authentication** page). The providers appear in the **Identity & Authentication (IdP / SSO)** section. Click **Connect** on a provider to begin.
{% endhint %}
{% hint style="warning" %}
**One identity provider per organization.** An organization can have a single active IdP at a time, using a single protocol. To switch providers — or switch an existing provider between OAuth and SAML — you must disconnect the current one first.
{% endhint %}
## Choosing a protocol
The protocol you'll use is determined by the provider you're connecting:
* Active Directory connects over LDAP(S) only.
* Microsoft Entra ID, Okta, and Ping Identity each support both OAuth (OIDC) and SAML. When you configure one of these, you'll be able to select between these two protocols. Only one can be active per provider at a time.
For those three cloud providers, choose between OIDC and SAML based on how your IdP application is set up:
| Protocol | What it is | Choose it when |
| ---------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **OAuth** (OIDC) | An open standard for access delegation, commonly used for token-based authentication. | Your IdP app is set up as an OIDC / OAuth application. |
| **SAML** | An XML-based framework for exchanging authentication and authorization data between parties. | Your IdP app is set up as a SAML application, or your organization standardizes on SAML. |
> Active Directory uses LDAP(S) — a protocol for querying and authenticating against a directory server, secured with TLS. Because AD supports only LDAP(S), there's no protocol selection step for it.
## What you provide, and what Dispel provides
Setting up SSO is a two-way exchange. You give Dispel details about your IdP, and — for SAML — you paste Dispel's service-provider details back into your IdP.
#### OAuth (OIDC)
You enter the following in Dispel:
| Field | What to enter |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Client URL** | The URL where OAuth tokens are sent — found in your IdP settings. |
| **Client ID** | Your IdP's unique identifier (often a URL or URN), from your IdP settings. |
| **Client Secret** | The client secret issued by your IdP. |
| **Organization Identifier** | A unique identifier *you* choose. Your users type this on the Dispel sign-in screen. Letters, numbers, dashes, and underscores only. |
On the IdP side, register Dispel as an application and set its **redirect URI** to your Dispel address followed by `/oauth/login-callback` (for example, `https://app.dispel.com/oauth/login-callback`). If you're unsure of the exact address for your environment, confirm it with your Dispel representative.
#### SAML
Dispel shows two read-only values at the top of the SAML form — paste these into your IdP's SAML application:
| Dispel provides | Paste into your IdP as |
| ----------------------------------- | --------------------------------------------- |
| **Service Provider (SP) Entity ID** | The SP entity ID / audience. |
| **Assertion Consumer Service URL** | The ACS URL / reply URL / single sign-on URL. |
Use the **Copy ID** and **Copy URL** buttons next to each. Then enter the following in Dispel:
| Field | What to enter |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **SSO URL** | The URL where the SAML assertion is sent — found in your IdP settings. |
| **Identity Provider Entity ID** | Your IdP's unique identifier (often a URL or URN). |
| **Base64 Signing Certificate** | The certificate your IdP uses to sign SAML assertions. Paste it, or use **Upload Certificate** (max 1 MB). |
| **Organization Identifier** | A unique identifier *you* choose. Your users type this on the Dispel sign-in screen. |
#### LDAP(S)
Unlike the SSO flows, LDAP isn't a redirect-based handshake — Dispel connects directly to your directory and authenticates users against it. There's nothing to paste back into another system; all configuration lives in Dispel. The values below come from your Active Directory administrator.
You enter the following in Dispel:
| Field | What to enter |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sign-in identifier** | A unique identifier *you* choose. Your users type this on the Dispel sign-in screen. |
| **Active Directory domain** | Your AD DNS domain — e.g. `corp.example.com`. |
| **Domain controllers** | The hostname(s) of the domain controller(s) Dispel connects to over LDAPS (port 636) — e.g. `dc01.corp.example.com`. |
| **Certificate trust + CA certificate** | How Dispel validates the TLS connection, and (recommended) the CA certificate that issued your domain controllers' certificates. From your PKI or AD admin; PEM, CRT, or CER. |
| **Bind DN or UPN** | The read-only service account Dispel authenticates as — e.g. `svc-dispel@corp.example.com`. |
| **Bind password** | The service account's password. |
| **User search base** | The directory location (OU) to search for users — e.g. `OU=Users,DC=corp,DC=example,DC=com`. |
| **Group search base** | The directory location (OU) to search for groups. |
| **Login attribute** | The attribute users enter as their username — commonly `sAMAccountName`. |
## Setting up a provider
The exact IdP-side steps differ by provider — see each provider's page for specifics. The overall flow is the same:
1. Go to **Settings → Integrations** and click **Connect** on the provider's card.
2. **Select Authentication Protocol** — OAuth or SAML.
3. *(SAML only)* Copy Dispel's **SP Entity ID** and **ACS URL** into your IdP's SAML app.
4. Fill in the connection fields with the values from your IdP, and choose an **Organization Identifier**.
5. Click **Save settings**.
6. *(SAML only)* Click **Test connection**. Dispel redirects you to your IdP to sign in, then shows the user attributes it received (email, first name, last name). If the test fails, check that the details match your IdP's SAML app and that the test user exists in your IdP and is invited to this organization.
> Connecting Active Directory? AD uses LDAP(S) and follows a different flow — Dispel connects directly to your directory rather than redirecting through an SSO handshake, and there's no protocol to choose. See the [Active Directory setup guide](/secure-and-govern/identity-providers/active-directory.md) for the full walk-through.
{% hint style="info" %}
**Secrets are masked.** After you save, secret fields (client secret, certificate) are masked. When editing later, leave a masked field unchanged to keep the stored value.
{% endhint %}
## How users sign in
Once SSO is configured, users sign in with your IdP instead of a Dispel password:
1. On the Dispel sign-in screen, the user enters your **Organization Identifier**.
2. Dispel redirects them to your IdP to authenticate.
3. On success, they're returned to Dispel and signed in.
Dispel reads the user's **email**, **first name**, and **last name** from the IdP response.
{% hint style="info" %}
**Users must be invited first.** SSO authenticates a user, but it doesn't grant access on its own. A user must already be invited to your organization in Dispel before they can sign in via SSO. See [Invite a User to Dispel](/manage-users-and-access/users/invite-a-user.md).
{% endhint %}
## Group mapping
You can automatically place SSO users into Dispel groups based on the groups or claims your IdP sends. Group membership is re-evaluated on every sign-in, so access stays in step with your IdP. See [OIDC Group Mapping](/integrate-and-administer/integrations/oidc-group-mapping.md).
## SSO and multi-factor authentication
When SSO is in use, your IdP is responsible for authentication — including any MFA you enforce there. As a result, Dispel's email one-time codes are not applied to users who sign in via SSO. Keep this in mind when designing MFA requirements in the [Policy Builder](/secure-and-govern/policy-builder.md).
## Switching or disconnecting a provider
To change providers, or to switch a provider between OAuth and SAML, **Disconnect** the current integration first, then connect the new one.
{% hint style="warning" %}
**Disconnecting forces a password reset.** Removing an SSO integration means affected users can no longer sign in through the IdP — they'll need to reset their Dispel passwords to sign in again, and you'll need to re-enter all fields to reconnect.
{% endhint %}
## Frequently asked questions
Can I use more than one identity provider at once?
No. An organization has a single active IdP at a time. If you're already connected to one provider, the others are unavailable until you disconnect — you'll see a note that you're currently connected to another provider and must disconnect it first.
Can I use both OAuth and SAML for the same provider?
No. Only one authentication protocol is supported per identity provider at a time. To switch protocols, disconnect and reconnect with the other one.
What is the Organization Identifier?
It's a short, unique label you choose (letters, numbers, dashes, and underscores). Your users enter it on the Dispel sign-in screen so Dispel knows which IdP to send them to.
Does a user automatically get an account on first SSO sign-in?
Only if they've already been invited to your organization. SSO proves who a user is, but they must have an invitation in Dispel to gain access.
Who can configure SSO?
An organization administrator. Configuring or disconnecting an identity provider requires organization-edit permission.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.dispel.com/secure-and-govern/identity-providers.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.