单点登录（SSO）

SSO 适用于 Enterprise 方案。

Enterprise 管理员可以直接在 Mintlify dashboard 中为 Okta 或 Microsoft Entra 配置 SAML SSO。对于 Google Workspace 或 Okta OIDC 等其他提供商，请联系我们以设置 SSO。

配置 SSO

Okta

在 Mintlify dashboard 中配置 Okta SSO

在 Mintlify dashboard 中，前往 Identity & access 页面。
点击 Configure。
选择 Okta SAML。
复制 Single sign on URL 和 Audience URI。

在 Okta 中创建 SAML 应用

在 Okta 的 Applications 中，使用 SAML 2.0 创建一个新的应用集成。
输入来自 Mintlify 的以下信息：
- Single sign on URL：你从 Mintlify dashboard 复制的 URL
- Audience URI：你从 Mintlify dashboard 复制的 URI
- Name ID Format：EmailAddress
添加以下属性声明：
Name Name format Value
firstName Basic user.firstName
lastName Basic user.lastName

Name	Name format	Value
`firstName`	Basic	`user.firstName`
`lastName`	Basic	`user.lastName`

复制 Okta metadata URL

在 Okta 中，进入应用的 Sign On 标签页，复制 metadata URL。

在 Mintlify 中保存

回到 Mintlify dashboard，粘贴 metadata URL，然后点击 Save changes。

Microsoft Entra

在 Mintlify dashboard 中配置 Microsoft Entra SSO

在 Mintlify dashboard 中，前往 Identity & access 页面。
点击 Configure。
选择 Microsoft Entra ID SAML。
复制 Single sign on URL 和 Audience URI。

在 Microsoft Entra 中创建企业应用

在 Microsoft Entra 中，前往 Enterprise applications。
点击 New application。
点击 Create your own application。
选择 “Integrate any other application you don’t find in the gallery (Non-gallery)”。

在 Microsoft Entra 中配置 SAML

在 Microsoft Entra 中，前往 Single Sign-On。
点击 SAML。
在 Basic SAML Configuration 下，输入以下内容：
- Identifier (Entity ID)：来自 Mintlify 的 Audience URI
- Reply URL (Assertion Consumer Service URL)：来自 Mintlify 的 Single sign on URL

将其他值留空，然后点击 Save。

在 Microsoft Entra 中配置 Attributes & Claims

在 Microsoft Entra 中，前往 Attributes & Claims。
在 “Required Claim” 下选择 Unique User Identifier (Name ID)。
将 Source 属性更改为 user.primaryauthoritativeemail。
在 Additional claims 下，创建以下内容：
Name Value
firstName user.givenname
lastName user.surname

Name	Value
`firstName`	`user.givenname`
`lastName`	`user.surname`

复制 Microsoft Entra metadata URL

在 SAML Certificates 下，复制 App Federation Metadata URL。

在 Mintlify 中保存

回到 Mintlify dashboard，粘贴 metadata URL，然后点击 Save changes。

分配用户

在 Microsoft Entra 中，前往 Users and groups，为需要访问 Mintlify dashboard 的用户进行分配。

JIT（即时）配置

启用 JIT（即时）配置后，通过身份提供商登录的用户会被自动添加到你的 Mintlify 组织中。

JIT 配置仅适用于由 IdP 发起的登录。用户必须从身份提供商（Okta dashboard 或 Microsoft Entra 门户）发起登录，而不能从 Mintlify 登录页面开始。

要启用 JIT 配置，你必须先启用 SSO。前往 dashboard 中的 Identity & access 页面，完成 SSO 设置，然后启用 JIT 配置。

已验证域名

验证你对邮箱域名的所有权，让 Mintlify 可以将 SSO 和成员配置范围限定为拥有匹配邮箱地址的人员。当有人使用已验证域名下的邮箱地址登录时，Mintlify 会自动将其路由到你的身份提供商。只要你的组织有一个可用的 SSO 连接，无论是否要求 SSO，自动路由都会生效。每个组织最多可添加 5 个已验证域名。

前往 dashboard 中的 Identity & access 页面。
在 SSO 标签页的 Verified domains 部分，输入域名（例如 example.com），然后点击 Add。
Mintlify 会生成一个验证令牌。在你的 DNS 提供商处，创建一条 TXT 记录，名称为 _mintlify-verification.example.com，值为该令牌。某些 DNS 提供商会自动附加域名。如果是这种情况，只需将记录名称设置为 _mintlify-verification 即可。
返回 dashboard 并点击 Verify。记录传播完成后，状态会从 Pending 变为 Verified。

要移除某个域名，请点击其旁边的删除按钮。

Require SSO（强制 SSO）

组织管理员可以要求组织内的所有人都通过身份提供商登录。当 Require SSO（强制 SSO）开启时，Mintlify 会拒绝密码、magic link 和 Google OAuth 登录。

前往 dashboard 中的 Identity & access 页面。
确认 SSO 已端到端正常工作。在无痕浏览器窗口中，分别从你的身份提供商的应用目录（IdP 发起）以及 Mintlify 登录页面使用已验证域名下的邮箱（SP 发起）登录 Mintlify dashboard。两种流程都应通过你的身份提供商跳转，并最终进入 dashboard。
在 SSO 标签页的 Sign-in policy（登录策略）部分，将 Require SSO 开关打开。

你只能在配置了 SSO 连接后才能强制要求 SSO。启用 Require SSO 时不会检查成员是否仍能登录，因此在开启之前，请至少为一名管理员添加应急访问。

要停止强制 SSO，请关闭该设置。其他登录方式会立即重新可用。

应急访问（Break-glass）

指定可以绕过 SSO 并使用密码或 magic link 登录的成员。使用应急访问可以在你的身份提供商发生故障或错误配置导致成员被锁定时恢复访问。

前往 dashboard 中的 Identity & access 页面。
在 SSO 标签页的 Break-glass access 部分，输入应保留非 SSO 访问权限的成员的邮箱地址，然后点击 Add。

每个应急访问邮箱必须已经属于你组织的一位现有成员。应急访问仅在 Require SSO 开启时生效。

为未绑定主身份提供商的管理员账户添加应急访问，将凭据存储在安全的密码管理器中，并在团队成员变动时定期审查该列表。

将 RBAC 角色映射到 SAML 组

根据用户在身份提供商中的组成员身份分配角色。当用户通过 SSO 登录时，Mintlify 会读取 SAML 断言中的 groups 属性，并将这些组映射到 dashboard 角色。

配置组属性声明

在你的 SAML 身份提供商配置中添加 groups 属性声明。该属性必须使用 unspecified 名称格式。生成的 SAML 断言应包含一个 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>

关键要求：

属性名称必须为 groups（区分大小写）
名称格式必须为 urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
用户所属的每个组应为单独的 AttributeValue 元素

Okta
Microsoft Entra

在你的 Okta SAML 应用配置中，添加一个组属性声明：

Name	Name format	Filter	Value
`groups`	Unspecified	Matches regex	`.*`

调整过滤器以匹配你希望发送到 Mintlify 的特定组。

在你的 Microsoft Entra 企业应用中：

前往 Single Sign-On > Attributes & Claims。
点击 Add a group claim。
选择要包含的组（所有组或特定组）。
在 Advanced options 下，勾选 Customize the name of the group claim，并将名称设置为 groups。

配置完成后，Mintlify 会将 SAML 断言中的组名称映射到组织中的角色。要设置或修改组到角色的映射，请联系你的 Mintlify 客户代表。

更改或移除 SSO 提供商

前往 dashboard 中的 Identity & access 页面。
点击 Configure。
选择你的首选 SSO 提供商，或选择不使用 SSO。

如果你移除了 SSO，用户必须改为通过密码、magic link 或 Google OAuth 进行身份验证。

其他提供商

如果你使用 Microsoft Entra 或 Okta SAML 之外的其他提供商，请联系我们以配置 SSO。

使用 SAML 的 Google Workspace

创建应用

在 Google Workspace 中，前往 Web and mobile apps。
在 Add app 下拉菜单中点击 Add custom SAML app。

Google Workspace SAML 应用创建页面的截图，其中高亮显示了 "Add custom SAML app" 菜单项

向我们发送你的 IdP 信息

复制提供的 SSO URL、Entity ID 和 x509 证书，并发送给 Mintlify 团队。

Google Workspace SAML 应用页面的截图，其中高亮显示了 SSO URL、Entity ID 和 x509 证书。每项的具体值均已模糊处理。

配置集成

在 Service provider details 页面，输入以下内容：

ACS URL（由 Mintlify 提供）
Entity ID（由 Mintlify 提供）
Name ID format：EMAIL
Name ID：Basic Information > Primary email

Service provider details 页面的截图，其中高亮显示了 ACS URL 和 Entity ID 输入字段。

在下一页，输入以下属性声明：

Google Directory Attribute	App Attribute
`First name`	`firstName`
`Last name`	`lastName`

完成此步骤并将用户分配到该应用后，请告知我们的团队，我们将为你的账号启用 SSO。

Okta (OIDC)

创建应用

在 Okta 的 Applications 中，使用 OIDC 创建一个新的应用集成。选择 Web Application 类型。

配置集成

选择 authorization code 授权类型，并输入 Mintlify 提供的 Redirect URI。

向我们发送你的 IdP 信息

前往 General 标签页，找到 client ID 和 client secret。请将这些信息以及你的 Okta 实例 URL（例如 <your-tenant-name>.okta.com）以安全的方式提供给我们。你可以通过 1Password 或 SendSafely 等服务发送。

​配置 SSO

​Okta

​Microsoft Entra

​JIT（即时）配置

​已验证域名

​Require SSO（强制 SSO）

​应急访问（Break-glass）

​将 RBAC 角色映射到 SAML 组

​配置组属性声明

​更改或移除 SSO 提供商

​其他提供商

​使用 SAML 的 Google Workspace

​Okta (OIDC)

配置 SSO

Okta

Microsoft Entra

JIT（即时）配置

已验证域名

Require SSO（强制 SSO）

应急访问（Break-glass）

将 RBAC 角色映射到 SAML 组

配置组属性声明

更改或移除 SSO 提供商

其他提供商

使用 SAML 的 Google Workspace

Okta (OIDC)