mintlify__docs/dashboard/sso.mdx

---
title: "Single sign-on (SSO)"
description: "Set up single sign-on with SAML or OIDC identity providers like Okta, Azure AD, and Google Workspace for secure team authentication."
keywords: ["SSO", "SAML authentication", "Okta integration", "Microsoft Entra", "identity provider", "JIT", "provisioning", "OIDC"]
---

<Info>
  SSO is available on [Enterprise plans](https://mintlify.com/pricing?ref=sso).
</Info>

Enterprise admins can configure SAML SSO for Okta or Microsoft Entra directly from the Mintlify dashboard. For other providers like Google Workspace or Okta OIDC, [contact us](mailto:support@mintlify.com) to set up SSO.

## Configure SSO

### Okta

<Steps>
  <Step title="Configure Okta SSO in your Mintlify dashboard">
    1. In your Mintlify dashboard, navigate to the [Single Sign-On](https://dashboard.mintlify.com/settings/organization/sso) page.
    2. Click **Configure**.
    3. Select **Okta SAML**.
    4. Copy the **Single sign on URL** and **Audience URI**.
  </Step>
  <Step title="Create a SAML app in Okta">
    1. In Okta, under **Applications**, create a new app integration using SAML 2.0.
    2. Enter the following from Mintlify:
        * **Single sign on URL**: the URL you copied from your Mintlify dashboard
        * **Audience URI**: the URI you copied from your Mintlify dashboard
        * **Name ID Format**: `EmailAddress`

    4. Add these attribute statements:

        | Name | Name format | Value |
        | ---- | ----------- | ----- |
        | `firstName` | Basic | `user.firstName` |
        | `lastName` | Basic | `user.lastName` |
  </Step>
  <Step title="Copy the Okta metadata URL">
    In Okta, go to the **Sign On** tab of your application and copy the metadata URL.
  </Step>
  <Step title="Save in Mintlify">
    Back in the Mintlify dashboard, paste the metadata URL and click **Save changes**.
  </Step>
</Steps>

### Microsoft Entra

<Steps>
  <Step title="Configure Microsoft Entra SSO in your Mintlify dashboard">
    1. In your Mintlify dashboard, navigate to the [Single Sign-On](https://dashboard.mintlify.com/settings/organization/sso) page.
    2. Click **Configure**.
    3. Select **Microsoft Entra ID SAML**.
    4. Copy the **Single sign on URL** and **Audience URI**.
  </Step>
  <Step title="Create an enterprise application in Microsoft Entra">
    1. In Microsoft Entra, navigate to **Enterprise applications**.
    2. Click **New application**.
    3. Click **Create your own application**.
    4. Select "Integrate any other application you don't find in the gallery (Non-gallery)."
  </Step>
  <Step title="Configure SAML in Microsoft Entra">
    1. In Microsoft Entra, navigate to **Single Sign-On**.
    2. Click **SAML**.
    3. Under **Basic SAML Configuration**, enter the following:
        * **Identifier (Entity ID)**: the Audience URI from Mintlify
        * **Reply URL (Assertion Consumer Service URL)**: the Single sign on URL from Mintlify

    Leave the other values blank and click **Save**.
  </Step>
  <Step title="Configure Attributes & Claims in Microsoft Entra">
    1. In Microsoft Entra, navigate to **Attributes & Claims**.
    2. Select **Unique User Identifier (Name ID)** under "Required Claim."
    3. Change the Source attribute to `user.primaryauthoritativeemail`.
    4. Under **Additional claims**, create the following:
        | Name | Value |
        | ---- | ----- |
        | `firstName` | `user.givenname` |
        | `lastName` | `user.surname` |
  </Step>
  <Step title="Copy the Microsoft Entra metadata URL">
    Under **SAML Certificates**, copy the **App Federation Metadata URL**.
  </Step>
  <Step title="Save in Mintlify">
    Back in the Mintlify dashboard, paste the metadata URL and click **Save changes**.
  </Step>
  <Step title="Assign users">
    In Microsoft Entra, navigate to **Users and groups**. Assign the users who should have access to your Mintlify dashboard.
  </Step>
</Steps>

## JIT provisioning

When you enable JIT (just-in-time) provisioning, users who sign in through your identity provider are automatically added to your Mintlify organization.

<Note>
  JIT provisioning only works for IdP-initiated login. Users must sign in from your identity provider (Okta dashboard or Microsoft Entra portal) rather than starting from the Mintlify login page.
</Note>

To enable JIT provisioning, you must have SSO enabled. Navigate to the [Single Sign-On](https://dashboard.mintlify.com/settings/organization/sso) page in your dashboard, set up SSO, and then enable JIT provisioning.

## Map RBAC roles with SAML groups

Assign [roles](/dashboard/roles) to users based on their identity provider group membership. When a user signs in through SSO, Mintlify reads the `groups` attribute from the SAML assertion and maps those groups to dashboard roles.

### Configure group attribute statements

Add a `groups` attribute statement to your SAML identity provider configuration. The attribute must use the `unspecified` name format.

The resulting SAML assertion should include an `AttributeStatement`.

```xml Example SAML assertion
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Attribute Name="groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              xsi:type="xs:string">Everyone</saml2:AttributeValue>
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              xsi:type="xs:string">Engineering</saml2:AttributeValue>
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              xsi:type="xs:string">Admins</saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>
```

**Key requirements:**
- The attribute name must be `groups` (case-sensitive)
- The name format must be `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`
- Each group the user belongs to should be a separate `AttributeValue` element

<Tabs>
  <Tab title="Okta">
    In your Okta SAML app configuration, add a group attribute statement:

    | Name | Name format | Filter | Value |
    | ---- | ----------- | ------ | ----- |
    | `groups` | Unspecified | Matches regex | `.*` |

    Adjust the filter to match the specific groups you want to send to Mintlify.
  </Tab>
  <Tab title="Microsoft Entra">
    In your Microsoft Entra enterprise application:

    1. Navigate to **Single Sign-On** > **Attributes & Claims**.
    2. Click **Add a group claim**.
    3. Select which groups to include (all groups or specific ones).
    4. Under **Advanced options**, check **Customize the name of the group claim** and set the name to `groups`.
  </Tab>
</Tabs>

Once configured, Mintlify maps the group names from the SAML assertion to roles in your organization. To set up or modify group-to-role mappings, reach out to your Mintlify account representative.

## Change or remove SSO provider

1. Navigate to the [Single Sign-On](https://dashboard.mintlify.com/settings/organization/sso) page in your dashboard.
2. Click **Configure**.
3. Select your preferred SSO provider or no SSO.

If you remove SSO, users must authenticate with a password, magic link, or Google OAuth instead.

## Other providers

For providers other than Microsoft Entra or Okta SAML, [contact us](mailto:support@mintlify.com) to configure SSO.

### Google Workspace with SAML

<Steps>
  <Step title="Create an application">
    1. In Google Workspace, navigate to **Web and mobile apps**.
    2. Click **Add custom SAML app** in the **Add app** dropdown.
    <Frame>
      ![Screenshot of the Google Workspace SAML application creation page with the "Add custom SAML app" menu item highlighted](/images/gsuite-add-custom-saml-app.png)
    </Frame>
  </Step>
  <Step title="Send us your IdP information">
    Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team.
    <Frame>
      ![Screenshot of the Google Workspace SAML application page with the SSO URL, Entity ID, and x509 certificate highlighted. The specific values for each of these are blurred out.](/images/gsuite-saml-metadata.png)
    </Frame>
  </Step>
  <Step title="Configure integration">
    On the Service provider details page, enter the following:

    * ACS URL (provided by Mintlify)
    * Entity ID (provided by Mintlify)
    * Name ID format: `EMAIL`
    * Name ID: `Basic Information > Primary email`

    <Frame>
      ![Screenshot of the Service provider details page with the ACS URL and Entity ID input fields highlighted.](/images/gsuite-sp-details.png)
    </Frame>

    On the next page, enter the following attribute statements:

    | Google Directory Attribute | App Attribute |
    | -------------------------- | ------------- |
    | `First name` | `firstName` |
    | `Last name` | `lastName` |

    Once this step is complete and users are assigned to the application, let our team know and we'll enable SSO for your account.
  </Step>
</Steps>

### Okta (OIDC)

<Steps>
  <Step title="Create an application">
    In Okta, under **Applications**, create a new app integration using OIDC. Choose the **Web Application** application type.
  </Step>
  <Step title="Configure integration">
    Select the authorization code grant type and enter the Redirect URI provided by Mintlify.
  </Step>
  <Step title="Send us your IdP information">
    Navigate to the **General** tab and locate the client ID and client secret. Securely provide these to us along with your Okta instance URL (for example, `<your-tenant-name>.okta.com`). You can send these via a service like 1Password or SendSafely.
  </Step>
</Steps>