跳到主要内容
版本：3.10.x

使用 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
  1. 点击 添加 (Add)。
  2. 在新的 OIDC 登录选项中，找到 回调 URL (Callback URL)，例如 https://dashboard.your-company.com/api/oidc/<LOGIN_OPTION_ID>/callback。
  3. 返回到上面的配置 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。
  1. 点击 启用 (Enable)。

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

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

启用权限边界映射​

  1. 从顶部导航栏选择 组织 (Organization)，然后选择 设置 (Settings)。
  2. 选择之前创建的登录选项。
  3. 启用 权限边界映射 (Permission Boundary Mapping)。
  4. 填写配置：
  • 权限策略 (Permission Policy)：要在 API7 企业版中分配的权限策略。例如，你可以创建一个诸如管理员许可证受限的策略，该策略授予完全的资源访问权限但限制更新许可证；并将该策略应用于此字段。
  • 权限边界属性 (Permission Boundary Attribute)：指向 IdP 中相应属性的 JSONPath。该属性应对应于 UserInfo 中的一个声明，例如 $['https://dashboard.your-company.com/roles']。
  • 操作符 (Operation)：用于匹配属性值的比较方法。例如，Exact Match in Array（数组精准匹配）。
  • 权限边界值 (Permission Boundary Value)：IdP 属性的值。例如，admin。
  1. 点击 启用 (Enable)。

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

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

删除登录选项​

注意

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

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

附加资源​