Skip to main content
Mintlify

Search documentation

Type to search this documentation.

On this pageOverview

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.

Enterprise admins can configure Security Assertion Markup Language (SAML) SSO for Okta or Microsoft Entra directly from the Mintlify dashboard. To set up SSO for other providers, such as Google Workspace or Okta OpenID Connect (OIDC), contact us.

Configure SSO

Section titled “Configure SSO”

Okta

Section titled “Okta”

  1. Configure Okta SSO in your Mintlify dashboard

    1. In your Mintlify dashboard, navigate to the Security page.
    2. Click Configure.
    3. Select Okta SAML.
    4. Copy the Single sign on URL and Audience URI.

  2. 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:
      NameName formatValue
      firstNameBasicuser.firstName
      lastNameBasicuser.lastName

  3. Copy the Okta metadata URL

    In Okta, go to the Sign On tab of your application and copy the metadata URL.

  4. Save in Mintlify

    Back in the Mintlify dashboard, paste the metadata URL and click Save changes.

Microsoft Entra

Section titled “Microsoft Entra”

  1. Configure Microsoft Entra SSO in your Mintlify dashboard

    1. In your Mintlify dashboard, navigate to the Security page.
    2. Click Configure.
    3. Select Microsoft Entra ID SAML.
    4. Copy the Single sign on URL and Audience URI.

  2. 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)."

  3. 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.

  4. 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:
      NameValue
      firstNameuser.givenname
      lastNameuser.surname

  5. Copy the Microsoft Entra metadata URL

    Under SAML Certificates, copy the App Federation Metadata URL.

  6. Save in Mintlify

    Back in the Mintlify dashboard, paste the metadata URL and click Save changes.

  7. Assign users

    In Microsoft Entra, navigate to Users and groups. Assign the users who should have access to your Mintlify dashboard.

JIT provisioning

Section titled “JIT provisioning”

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

To enable JIT provisioning, you must have SSO enabled. In your dashboard, navigate to the Security page. Set up SSO, then enable JIT provisioning.

Verified domains

Section titled “Verified domains”

Verify ownership of your email domains so Mintlify can scope SSO and member provisioning to people with matching email addresses. When someone signs in with an email address on a verified domain, Mintlify automatically routes them to your identity provider. This automatic routing works whether or not you require SSO, as long as your organization has an active SSO connection.

You can add up to 25 verified domains per organization.

The Verified domains section appears only after your SSO connection is active. Configure SSO before adding domains.

  1. Navigate to the Security page in your dashboard.
  2. In the SSO section, under Verified domains, enter the domain (for example, example.com) and click Add.
  3. Mintlify generates a verification token. In your DNS provider, create a TXT record with the name _mintlify-verification.example.com and the token as the value. Some DNS providers append the domain automatically. If yours does, enter just _mintlify-verification as the record name.
  4. Return to the dashboard and click Verify. The status changes from Pending to Verified once the record propagates.

To remove a domain, click the delete button beside it.

Require SSO

Section titled “Require SSO”

To require everyone in your organization to sign in through your identity provider, turn on Require SSO. When Require SSO is on, Mintlify rejects password, magic link, and Google OAuth sign-ins.

  1. Navigate to the Security page in your dashboard.
  2. Confirm that SSO works end-to-end. In a private browser window, sign in to your Mintlify dashboard from your identity provider's app catalog (IdP-initiated). Then sign in from the Mintlify login page using an email on a verified domain (service provider (SP)-initiated). Both flows should redirect through your identity provider and land you in the dashboard.
  3. In the SSO section, turn on Require SSO.

To stop requiring SSO, toggle the setting off. Other sign-in methods become available again immediately.

Break-glass access

Section titled “Break-glass access”

Designate members who can bypass SSO and sign in with a password or magic link. Use break-glass access to recover access if your identity provider has an outage. It also helps if a misconfiguration locks members out.

  1. Navigate to the Security page in your dashboard.
  2. In the SSO section, under Break-glass emails, enter the email address of a member who should retain non-SSO access and click Add.

Each break-glass email must belong to an existing member of your organization. Break-glass access only takes effect while Require SSO is on.

Map RBAC roles with SAML groups

Section titled “Map RBAC roles with SAML groups”

Assign 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. It maps those groups to dashboard roles.

Configure group attribute statements

Section titled “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.

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

In your Okta SAML app configuration, add a group attribute statement:

NameName formatFilterValue
groupsUnspecifiedMatches regex.*

Adjust the filter to match the specific groups you want to send to Mintlify.

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.

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, contact your Mintlify account representative.

Change or remove SSO provider

Section titled “Change or remove SSO provider”
  1. Navigate to the Security 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

Section titled “Other providers”

For providers other than Microsoft Entra or Okta SAML, contact us to configure SSO.

Google Workspace with SAML

Section titled “Google Workspace with SAML”

  1. Create an application

    1. In Google Workspace, navigate to Web and mobile apps.
    2. Click Add custom SAML app in the Add app dropdown.

  2. Send your IdP information to Mintlify

    Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team.

  3. 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

    On the next page, enter the following attribute statements:

    Google Directory AttributeApp Attribute
    First namefirstName
    Last namelastName

    After you complete this step and assign users to the application, tell the Mintlify team. The Mintlify team then enables SSO for your account.

Okta (OIDC)

Section titled “Okta (OIDC)”

  1. Create an application

    In Okta, under Applications, create a new app integration using OIDC. Select the Web Application type.

  2. Configure integration

    Select the authorization code grant type and enter the Redirect URI provided by Mintlify.

  3. Send your IdP information to Mintlify

    Navigate to the General tab and locate the client ID and client secret. Securely send these to the Mintlify team along with your Okta instance URL (for example, <your-tenant-name>.okta.com). You can send these details via a service like 1Password or SendSafely.

Section titled “Related topics”
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu