使用 Auth0 配置控制台 SSO

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

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

设置 SSO 集成

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

配置 Auth0

1. 在 Applications（应用程序）下，创建一个新的 application（应用程序），指定一个自定义名称（例如，API7 Dashboard），并选择 Regular Web Applications（常规 Web 应用程序）作为应用程序类型。
   1. 在 Settings（设置）选项卡下，记录 Client ID（客户端 ID）、Client Secret（客户端密钥）和 Domain (Issuer)（域名或签发者）以备后用。
   2. 在 Connections（连接）选项卡下，确保启用了 Username-Password-Authentication 内置数据库连接。
2. 在 User Management > Users（用户管理 > 用户）下，创建一个 user（用户）并配置其密码。根据需要更新用户名。
3. 查看应用程序位于 https://<DOMAIN>/.well-known/openid-configuration 的发现文档 (discovery document)：
   1. 找到 end_session_endpoint URL，例如，https://<DOMAIN>.us.auth0.com/oidc/logout。记录此值以备后用。
   2. 查看 claims_supported 以备稍后在 API7 中配置属性映射。
4. 完成下面的创建控制台登录选项说明，因为后续配置需要来自 API7 的信息。
5. 在该应用程序中，位于 Connections（连接）选项卡下：
   1. 在 Allowed Callback URLs（允许的回调 URL）中配置回调 URL。
   2. 在 Allowed Logout URLs（允许的注销 URL）中配置 post_logout_redirect_uri 的值，例如，https://dashboard.your-company.com。
   3. 在 Allowed Web Origins（允许的 Web 源）中配置控制台地址。

配置现已完成。你现在应该能够使用新的登录选项登录 API7 控制台了。

提示

如果你在应用程序的 Connections（连接）选项卡下启用了 google-oauth2 内置社交连接并允许用户使用其社交账号登录 API7，这些用户在至少登录一次 API7 之前不会出现在 Auth0 的 User Management（用户管理）中。在他们首次登录后，这些用户将在 Auth0 中可见，然后你可以为他们分配角色。

创建控制台登录选项

API7 企业版支持使用多种协议的单点登录 (SSO)。通过与现有的用户系统集成，它允许用户无需创建新账号即可访问 API7 企业版。

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

• 名称 (Name)：唯一的登录名称。该名称应易于用户识别。例如，如果你将名称配置为 Employee Account，你将在控制台登录页面看到 Login with Employee Account（使用员工账号登录）选项。
• 提供商 (Provider)：选择 OIDC。
• 签发者 (Issuer)：OpenID Connect 提供商的签发者 URL，例如 https://<DOMAIN>/。请确保在 URL 末尾包含尾部的斜杠。
• 客户端 ID (Client ID)：OIDC 提供商为你分配的应用程序的唯一标识符，例如 opqOFcwhzoRMRAekG1rfp7VdpU63tKsv。
• 客户端密钥 (Client Secret)：由 OIDC 提供商分配用于身份验证的密钥。
• 请求范围 (Request Scope)：向 OIDC 提供商请求的范围 (Scope) 值，这定义了访问级别和令牌 (Token) 中包含的声明 (Claims)。openid 范围对于所有的 OIDC 请求都是强制的。可以根据需要添加其他范围，以空格分隔。例如，openid profile email。
• 根 URL (Root URL)：用户访问 API7 控制台的根地址，例如 https://dashboard.your-company.com。此 URL 必须与用户在浏览器中输入的内容完全匹配，包括协议（HTTP 或 HTTPS）以及端口号（如果不同于标准端口 80 或 443）。
  • 回调 URL 将自动生成为 <Root_URL>/api/oidc/<LOGIN_OPTION_ID>/callback。
• SSL 验证 (SSL verify)：是否验证 OIDC 提供商的 SSL/TLS 证书。
• 注销 URL (Logout URL)：结束用户会话并将其重定向到登录页面的 URL。这应该是带有设置为 API7 控制台 URL 的 post_logout_redirect_uri 查询参数的 end_session_endpoint URL，例如 https://<DOMAIN>.us.auth0.com/oidc/logout?post_logout_redirect_uri=https://dashboard.your-company.com。
• 属性映射 (Attributes Mapping)：API7 用户字段映射到 OIDC 声明。例如：
  • username: name
  • email: email
  • name: name

4. 点击 添加 (Add)。
5. 在新的 OIDC 登录选项中，找到 回调 URL (Callback URL)，例如 https://dashboard.your-company.com/api/oidc/<LOGIN_OPTION_ID>/callback。
6. 返回到上面的配置 Auth0 步骤 5。

如果完成了上述所有步骤，API7 控制台登录页面上现在应该出现一个新的登录选项，允许你使用在 IdP 中创建的用户进行身份验证。用户登录后，以管理员用户身份登录，导航至顶部导航栏中的 组织 (Organization)，然后选择 用户 (Users) 以查看该用户。

请注意，该用户尚未分配任何角色，因此缺乏在控制台中管理资源的权限。

important

在控制台中删除用户会移除其在 API7 控制台中分配的所有角色和权限边界，但该用户仍然可以作为新用户登录。若要完全撤销对 API7 控制台的访问权限，必须从 IdP 中移除该用户。

管理用户角色和权限

启用自动映射后，导入的用户可以根据其来自身份提供商的属性（如头衔、职位或部门）自动分配角色和权限边界。这些角色和权限边界在用户每次登录时进行同步，确保访问权限的一致性。一个登录选项的映射可以包含多个规则，这些规则共同决定用户的访问权限。

信息

如果你更喜欢手动为用户更新角色和权限边界（最适合临时调整），请参阅 更新用户角色 和 设置权限边界。

自动映射优先于手动修改的角色和权限边界。当映射处于活动状态时，控制台中的手动更改将在用户下次登录时被覆盖。

配置 Auth0

角色和权限边界映射依赖于在 IdP 中配置并传递给 API7 企业版的值。相同的 IdP 配置适用于设置角色和权限边界的映射。

提示

在生产环境中，建议实施细粒度的权限控制。例如，你可以在 API7 中创建详细的权限并将其绑定到一个角色，然后使用 API7 登录选项设置将每个 Auth0 角色显式映射到相应的 API7 角色。最后，在 Auth0 中手动或通过 Action 为每个用户分配适当的角色，以确保适当的访问控制。

1. 在 User Management > Roles（用户管理 > 角色）下，创建一个新角色，例如 admin。

2. 将此角色分配给在 API7 中需要管理员权限的用户。

3. 要使角色对你的应用程序可用，请在 Actions > Triggers（操作 > 触发器）下创建一个 post-login（登录后）触发器。创建一个操作 Inject Roles Claim 并部署以下代码：

   exports.onExecutePostLogin = async (event, api) => {
   // List of roles assigned to users in Auth0
   const roles = (event.authorization && event.authorization.roles) || [];
   
   // Use a namespace in the form of a URL for custom claims to avoid conflicts.
   const claimName = "https://dashboard.your-company.com/roles";
   
   // Write roles to ID Token and Access Token (array)
   api.idToken.setCustomClaim(claimName, roles);
   api.accessToken.setCustomClaim(claimName, roles);
   };

4. 将创建的操作拖拽至 Post Login (登录后) 触发器并应用更改。

在控制台中配置映射

本节描述如何在 API7 企业版控制台中配置角色和权限边界映射，以定义如何将来自身份提供商的用户属性转换为访问控制。

启用角色映射

1. 从顶部导航栏选择 组织 (Organization)，然后选择 设置 (Settings)。
2. 选择该登录选项。
3. 启用 角色映射 (Role Mapping)。
4. 填写配置：

• 内部角色 (Internal Role)：要在 API7 企业版中分配的角色。例如，Super Admin（超级管理员）。
• 角色属性 (Role Attribute)：指向 IdP 中相应属性的 JSONPath。该属性应对应于 UserInfo 中的一个声明，例如 $['https://dashboard.your-company.com/roles']。
• 操作符 (Operation)：用于匹配属性值的比较方法。例如，Exact Match in Array（数组精准匹配）。
• 角色值 (Role Value)：属性的值，例如 admin。

5. 点击 启用 (Enable)。

现在，所有在 IdP 中 roles 属性设置为 admin 的用户将在下次登录时自动被分配 Super Admin（超级管理员）角色。

请注意，角色映射是动态的。如果用户在 IdP 中的属性发生更改，其角色将根据角色映射规则在下次登录 API7 企业版时自动更新。

启用权限边界映射

1. 从顶部导航栏选择 组织 (Organization)，然后选择 设置 (Settings)。
2. 选择之前创建的登录选项。
3. 启用 权限边界映射 (Permission Boundary Mapping)。
4. 填写配置：

• 权限策略 (Permission Policy)：要在 API7 企业版中分配的权限策略。例如，你可以创建一个诸如 Admin License Restricted（管理员许可证受限）的策略，该策略授予完全的资源访问权限但限制更新许可证；并将该策略应用于此字段。
• 权限边界属性 (Permission Boundary Attribute)：指向 IdP 中相应属性的 JSONPath。该属性应对应于 UserInfo 中的一个声明，例如 $['https://dashboard.your-company.com/roles']。
• 操作符 (Operation)：用于匹配属性值的比较方法。例如，Exact Match in Array（数组精准匹配）。
• 权限边界值 (Permission Boundary Value)：IdP 属性的值。例如，admin。

5. 点击 启用 (Enable)。

现在，所有在 IdP 中 roles 属性设置为 admin 的用户将在下次登录时自动被分配 Admin License Restricted（管理员许可证受限）的权限边界。

请注意，权限边界映射是动态的。如果用户在 IdP 中的属性发生更改，其权限边界将根据映射规则在下次登录 API7 企业版时自动更新。

删除登录选项

注意

删除登录选项将移除在 API7 控制台中与该选项关联的所有用户。

1. 从顶部导航栏选择 组织 (Organization)，然后选择 用户 (Users)。
2. 检查是否仍有用户正在使用该登录选项。如果是，在进行任何更改前通知他们。
3. 从顶部导航栏选择 组织 (Organization)，然后选择 设置 (Settings)。
4. 点击目标登录选项的 删除 (Delete)。

附加资源

• 核心概念
  • 角色和权限策略
• 快速入门
  • 创建自定义角色
• 参考指南
  • 权限策略操作和资源
  • 权限策略示例