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.

SSO is available on Enterprise plans.

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 to set up SSO.

Configure SSO

Okta

1. Configure Okta SSO in your Mintlify dashboard

   1. In your Mintlify dashboard, navigate to the Identity & access 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:

      Name	Name format	Value
      firstName	Basic	user.firstName
      lastName	Basic	user.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

1. Configure Microsoft Entra SSO in your Mintlify dashboard

   1. In your Mintlify dashboard, navigate to the Identity & access 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:

      Name	Value
      firstName	user.givenname
      lastName	user.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

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

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.

To enable JIT provisioning, you must have SSO enabled. Navigate to the Identity & access page in your dashboard, set up SSO, and then enable JIT provisioning.

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. Automatic routing works whether or not you require SSO, as long as your organization has an active SSO connection.

You can add up to five verified domains per organization.

1. Navigate to the Identity & access page in your dashboard.
2. On the SSO tab, in the Verified domains section, 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

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

1. Navigate to the Identity & access 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) and from the Mintlify login page using an email on a verified domain (SP-initiated). Both flows should redirect through your identity provider and land you in the dashboard.
3. On the SSO tab, in the Sign-in policy section, toggle Require SSO on.

You can only require SSO after configuring an SSO connection. Requiring SSO does not check whether members can still sign in, so add break-glass access for at least one admin before turning it on.

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

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 or a misconfiguration locks members out.

1. Navigate to the Identity & access page in your dashboard.
2. On the SSO tab, in the Break-glass access section, 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.

Add break-glass access for admin accounts that are not tied to your primary identity provider, store the credentials in a secure password manager, and review the list whenever team membership changes.

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

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

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.

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.

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 Identity & access 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 to configure SSO.

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 us your IdP information

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

Okta (OIDC)

1. Create an application

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

2. Configure integration

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

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