mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
54f9721835
* docs: apply brand tone and writing style fixes * Apply suggestion from @ethanpalm * Apply suggestion from @ethanpalm * Apply suggestion from @ethanpalm --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
258 lines
13 KiB
Plaintext
258 lines
13 KiB
Plaintext
---
|
|
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 [Identity & access](https://app.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 [Identity & access](https://app.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 [Identity & access](https://app.mintlify.com/settings/organization/sso) 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](https://app.mintlify.com/settings/organization/sso) 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 <Icon icon="trash" /> 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](https://app.mintlify.com/settings/organization/sso) 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](https://app.mintlify.com/login) 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.
|
|
|
|
<Warning>
|
|
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.
|
|
</Warning>
|
|
|
|
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](https://app.mintlify.com/settings/organization/sso) 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.
|
|
|
|
<Tip>
|
|
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.
|
|
</Tip>
|
|
|
|
## 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 [Identity & access](https://app.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>
|
|
|
|
</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>
|
|
|
|
</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>
|
|
|
|
</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. Select the **Web 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>
|