单点登录（SSO）
使用 Okta、Azure AD 和 Google Workspace 等 SAML 或 OIDC 身份提供商设置单点登录，实现安全的团队身份验证。
SSO 适用于 Enterprise 方案。
Enterprise 管理员可以直接在 Mintlify dashboard 中为 Okta 或 Microsoft Entra 配置 SAML SSO。对于 Google Workspace 或 Okta OIDC 等其他提供商，请联系我们以设置 SSO。
在 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 firstNameBasic user.firstNamelastNameBasic user.lastName
复制 Okta metadata URL
在 Okta 中，进入应用的 Sign On 标签页，复制 metadata URL。
在 Mintlify 中保存
回到 Mintlify dashboard，粘贴 metadata URL，然后点击 Save changes。
在 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 firstNameuser.givennamelastNameuser.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（即时）配置后，通过身份提供商登录的用户会被自动添加到你的 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）开启时，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，请关闭该设置。其他登录方式会立即重新可用。
指定可以绕过 SSO 并使用密码或 magic link 登录的成员。使用应急访问可以在你的身份提供商发生故障或错误配置导致成员被锁定时恢复访问。
- 前往 dashboard 中的 Identity & access 页面。
- 在 SSO 标签页的 Break-glass access 部分，输入应保留非 SSO 访问权限的成员的邮箱地址，然后点击 Add。
每个应急访问邮箱必须已经属于你组织的一位现有成员。应急访问仅在 Require SSO 开启时生效。
为未绑定主身份提供商的管理员账户添加应急访问。将凭据存储在安全的密码管理器中，并在团队成员变动时定期审查该列表。
根据用户在身份提供商中的组成员身份分配角色。当用户通过 SSO 登录时，Mintlify 会读取 SAML 断言中的 groups 属性，并将这些组映射到 dashboard 角色。
在你的 SAML 身份提供商配置中添加 groups 属性声明。该属性必须使用 unspecified 名称格式。
生成的 SAML 断言应包含一个 AttributeStatement。
<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 SAML 应用配置中，添加一个组属性声明：
| Name | Name format | Filter | Value |
|---|---|---|---|
groups | Unspecified | Matches regex | .* |
调整过滤器以匹配你希望发送到 Mintlify 的特定组。
配置完成后，Mintlify 会将 SAML 断言中的组名称映射到组织中的角色。要设置或修改组到角色的映射，请联系你的 Mintlify 客户代表。
- 前往 dashboard 中的 Identity & access 页面。
- 点击 Configure。
- 选择你的首选 SSO 提供商，或选择不使用 SSO。
如果你移除了 SSO，用户必须改为通过密码、magic link 或 Google OAuth 进行身份验证。
如果你使用 Microsoft Entra 或 Okta SAML 之外的其他提供商，请联系我们以配置 SSO。
创建应用
- 在 Google Workspace 中，前往 Web and mobile apps。
- 在 Add app 下拉菜单中点击 Add custom SAML app。
向我们发送你的 IdP 信息
复制提供的 SSO URL、Entity ID 和 x509 证书，并发送给 Mintlify 团队。
配置集成
在 Service provider details 页面，输入以下内容：
- ACS URL（由 Mintlify 提供）
- Entity ID（由 Mintlify 提供）
- Name ID format：
EMAIL - Name ID：
Basic Information > Primary email
在下一页，输入以下属性声明：
| Google Directory Attribute | App Attribute |
|---|---|
First name | firstName |
Last name | lastName |
完成此步骤并将用户分配到该应用后，请告知我们的团队，我们将为你的账号启用 SSO。
创建应用
在 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 等服务发送。