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

# Single sign-on (SSO)

> Set up single sign-on with SAML or OIDC identity providers like Okta, Azure AD, and Google Workspace for secure team authentication.

<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`

    3. 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 theme={null}
<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>
      <img src="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gsuite-add-custom-saml-app.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=2c06c394d98ccd65df92aefceaeb75bd" alt="Screenshot of the Google Workspace SAML application creation page with the &#x22;Add custom SAML app&#x22; menu item highlighted" width="3804" height="1860" data-path="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>
      <img src="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gsuite-saml-metadata.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=e9e47998599205dc051e9402cba63756" alt="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." width="3800" height="1850" data-path="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>
      <img src="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gsuite-sp-details.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=a410a25f000fe2bc4d735a6ebe7754da" alt="Screenshot of the Service provider details page with the ACS URL and Entity ID input fields highlighted." width="3788" height="1864" data-path="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>


## Related topics

- [Accordions](/docs/components/accordions.md)
- [skill.md](/docs/ai/skillmd.md)
- [Branching and publishing](/docs/editor/branching-and-publishing.md)