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 Single Sign-On 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 Single Sign-On 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 Single Sign-On page in your dashboard, set up SSO, and then enable JIT provisioning.

Require SSO

Enterprise admins can require organization members to sign in through their identity provider, blocking other authentication methods like password, magic link, and Google OAuth. Use this to ensure that every dashboard sign-in flows through your IdP so that account lifecycle, MFA, and access policies are enforced centrally.

Enable SSO enforcement

Before you can require SSO, you must have an active SSO connection with a default connection configured. Attempting to enforce SSO without a configured connection returns an error to prevent locking your organization out.

1. Set up SSO

   Configure a SAML connection following the steps in Configure SSO and confirm the connection shows as Active on the Single Sign-On page.

2. Toggle Require SSO

   On the same page, turn on Require SSO. Once enabled, password, magic link, and Google OAuth sign-ins are disabled for your organization. Members who try to sign in with another method are redirected to your IdP.

Choose allowed authentication methods

If you want to allow a combination of methods instead of SSO-only, you can choose which methods are permitted for your organization from the SSO settings. The available options are:

• SSO through your configured identity provider
• Password
• Magic link sent to the member’s email
• Google OAuth

Saving an empty list resets your organization to allow all methods. Saving a list that contains only SSO requires an active default SSO connection, the same as toggling Require SSO on.

Switching organizations as a non-SSO user

If a member belongs to multiple organizations and is signed in with a non-SSO method (for example, password or Google), switching into an organization that requires SSO triggers an SSO step-up. The dashboard sends the member to your IdP to complete authentication before the org switch finishes. Existing sessions in other organizations are not affected.

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 Single Sign-On 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 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.