使用 Okta 和 SAML 配置控制台 SSO

单点登录 (SSO) 允许用户使用一组凭证访问多个应用程序，从而简化身份验证过程。在 API7 企业版中，SSO 支持多种协议，并提供了从现有身份提供商 (IdP) 导入并管理用户的能力。

本指南将引导你通过 SAML 协议使用 Okta 作为身份提供商，为 API7 企业版控制台配置单点登录 (SSO)，并为导入的用户设置角色映射。

设置 SSO 集成

本节将指导你使用 Okta 作为身份提供商为 API7 企业版控制台配置单点登录 (SSO)。

配置 Okta

本节描述在 Okta 中的示例配置。如果你使用的是其他的身份提供商 (IdP)，请参阅你 IdP 的文档并相应地调整配置。

1. 在 Okta Admin Console（管理控制台）中，导航至 Applications > Applications（应用程序 > 应用程序），然后点击 Create App Integration（创建应用集成）。选择 SAML 2.0，然后点击 Next（下一步）。

2. 在 General Settings（常规设置）中，设置应用程序名称，例如 API7 SAML，然后点击 Next（下一步）。

3. 在 Configure SAML（配置 SAML）中，设置以下值，然后点击 Next（下一步）：
   1. Single sign-on URL（单点登录 URL）：设置一个占位符，例如 http://placeholder。你稍后在 API7 控制台中创建登录选项后，将更新此值。
   2. 启用 Use this for Recipient URL and Destination URL（将其用于收件人 URL 和目标 URL）。
   3. Audience URI (SP Entity ID)（受众 URI (SP 实体 ID)）：设置一个唯一标识符，例如 api7。此值必须与 API7 控制台中的 实体 ID (Entity ID) 匹配。

4. 在 Feedback（反馈）中，选择 This is an internal app that we have created（这是我们创建的一个内部应用），然后点击 Finish（完成）。

5. 在应用程序的 Sign On（登录）选项卡中，复制 Metadata URL（元数据 URL）。你将在 API7 控制台中使用它。

6. 在 Sign On（登录）选项卡中，添加以下 Attribute Statements（属性声明）：
   • email: user.profile.email
   • name: user.profile.displayName
   • username: user.profile.login

创建控制台登录选项

1. 从顶部导航栏选择 组织 (Organization)，然后选择 设置 (Settings)。
2. 点击 添加登录选项 (Add Login Option)。

3. 填写配置：

• 名称 (Name)：唯一的登录名称。该名称应易于用户识别。例如，如果你将名称配置为 okta-saml，你将在控制台登录页面看到 Login with okta-saml（使用 okta-saml 登录）选项。
• 提供商 (Provider)：选择 SAML。
• 身份提供商元数据 URL (Identity Provider Metadata URL)：之前复制的 Okta 元数据 URL。
• 服务提供商根 URL (Service Provider Root URL)：你的服务提供商的根 URL。通常是 API7 控制台的地址，例如 https://dashboard.your-company.com。
• 实体 ID (Entity ID)：与 Okta 中配置的 Audience URI (SP Entity ID) 相匹配的唯一标识符，例如 api7。
• 属性映射 (Attributes Mapping)：API7 用户字段映射到 SAML 声明。例如：
  • username: username
  • email: email
  • name: name

4. 可选：启用 角色映射 (Role Mapping) 并配置一个规则将 Okta 属性映射到 API7 角色。

5. 点击 添加 (Add)。
6. 在新的 SAML 登录选项中，复制 服务提供商 ACS URL (Service Provider ACS URL)。

使用 ACS URL 更新 Okta

1. 返回 Okta 应用程序并打开 Sign On（登录）选项卡。
2. 在 SAML Settings（SAML 设置）部分中点击 Edit（编辑）。
3. 使用从 API7 控制台复制的 服务提供商 ACS URL 更新 Single sign-on URL（单点登录 URL），然后保存更改。

将用户分配给 Okta 应用程序

1. 在 Okta 应用程序中，打开 Assignments（分配）选项卡。
2. 点击 Assign（分配）并选择 Assign to People（分配给人员）。
3. 选择应访问 API7 控制台的用户，然后点击 Done（完成）。

验证 SSO 登录

1. 打开 API7 控制台登录页面并选择 Login with okta-saml。

2. 使用你的 Okta 凭证登录。

3. 等待重定向完成。

4. 确认你可以访问 API7 控制台，如果你启用了角色映射，请验证角色映射。

启用签名请求 (Sign Request)

如果你希望 API7 控制台对 SAML 身份验证请求进行签名，请启用 签名请求 (Sign Request) 并使用 API7 证书配置 Okta。

1. 在 SAML 登录选项中，启用 签名请求 (Sign Request)。如果没有配置证书，API7 控制台会自动生成一个。你也可以选择上传自己的证书和私钥。保存更改并复制证书值以便在 Okta 中使用。

2. 在 Okta 应用程序的 General（常规）选项卡中，点击 SAML Settings（SAML 设置）中的 Edit（编辑）。

3. 更新 Name ID format（名称 ID 格式）。

4. 将从 API7 控制台复制的证书上传到 Signature Certificate（签名证书）部分，启用签名请求，然后保存更改。

5. 再次登录以验证签名请求流程。

通过组成员身份配置

使用 Okta 组成员身份基于 SAML 断言中的 groups 属性来映射 API7 角色。

1. 在 Okta Admin Console（管理控制台）中，导航至 Directory > Groups（目录 > 组），点击 Add Group（添加组），并创建一个组，例如 group_1。

2. 确认组已创建并打开组详细信息。

3. 点击 Add People（添加人员）并添加用户。

4. 在 Okta 应用程序的 Assignments（分配）选项卡中，点击 Assign（分配）并选择 Assign to Groups（分配给组），然后将 group_1 组分配给该应用程序。

5. 在 Okta 应用程序的 Sign On（登录）选项卡中，编辑 SAML Settings（SAML 设置）并添加一个 Groups Attribute Statement（组属性声明）：
   • Name（名称）：groups
   • Filter（过滤器）：user.getGroups({"group.profile.name": {"group_1"}}).![profile.name]。请参阅 Okta Group functions 了解更多详细信息。

备注

要检查 SAML 断言，请使用浏览器 SAML 跟踪扩展（例如 SAML-tracer）。在 API7 控制台中点击 SAML 登录选项后，捕获 POST /xxxx/acs 请求并查看解码后的断言，如图所示。

使用此负载中的 groups 值在 API7 控制台中配置角色映射。

6. 在 API7 控制台中，打开 SAML 登录选项，启用 角色映射 (Role Mapping)，并添加一个规则：
   • 内部角色 (Internal Role)：Super Admin（超级管理员）（或其他角色）
   • 角色属性 (Role Attribute)：groups
   • 操作符 (Operation)：Exact Match in Array（数组精准匹配）
   • 角色值 (Role Value)：group_1

7. 保存登录选项并确认映射规则已列出。

8. 使用 Okta 组中的用户登录，并确认已应用该角色。

附加资源

• 核心概念
  • 角色和权限策略
• 快速入门
  • 创建自定义角色
• 最佳实践
  • 使用 LDAP 配置控制台 SSO
  • 使用 Microsoft Entra ID 配置控制台 SSO