使用 Keycloak 配置控制台单点登录 (SSO)

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

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

探索我们的交互式演示，了解如何将 Keycloak SSO 与 API7 企业版无缝集成。

设置 SSO 集成

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

配置 Keycloak

本节描述了 Keycloak 26.3.3 中的示例配置。如果你使用的是不同版本，请相应地调整配置。

1. 创建一个 realm，例如 quickstart-realm。
2. 创建一个 client，例如 apisix-quickstart-client。在客户端中：
   1. 启用 client authentication（客户端身份验证），这会将访问类型设置为 confidential（机密）。
   2. 启用 standard flow（标准流程，即授权码授权）。
   3. 配置 redirect URL（重定向 URL），例如 *。
   4. 创建客户端后，导航到 Credentials 选项卡并获取 client secret（客户端密钥）。记录此值以供稍后使用。
3. 创建一个 user。在用户中：
   1. 创建用户密码。
   2. 根据需要配置用户电子邮件、名字和姓氏。
4. 在 realm settings 中，找到指向发现文档（discovery document）的链接。在发现文档中，记录这些值以供稍后使用：
   1. issuer URL，例如，http://192.168.10.101:8080/realms/quickstart-realm。
   2. end_session_endpoint URL，例如，http://192.168.10.101:8080/realms/quickstart-realm/protocol/openid-connect/logout。

创建控制台登录选项

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

1. 从顶部导航栏中选择 Organization，然后选择 Settings。
2. 点击 Add Login Option。
3. 填写配置：

• Name：唯一的登录名称。该名称应易于用户识别。例如，如果你将名称配置为 Employee Account，你将在控制台登录页面上看到 Login with Employee Account 选项。
• Provider：选择 OIDC。
• Issuer：OpenID Connect 提供商的 issuer URL，例如 http://192.168.10.101:8080/realms/quickstart-realm。
• Client ID：OIDC 提供商分配给你的应用程序的唯一标识符，例如 apisix-quickstart-client。
• Client Secret：OIDC 提供商分配的用于身份验证的密钥。
• Request Scope：从 OIDC 提供商请求的作用域值，它定义了令牌（token）中包含的访问级别和声明（claims）。对于所有 OIDC 请求，openid 作用域是必需的。可以根据需要包含其他作用域，用空格分隔。例如，openid profile email。
• Root URL：用户访问 API7 控制台的根地址，例如 https://dashboard.your-company.com。此 URL 必须与用户在浏览器中输入的完全匹配，包括协议（HTTP 或 HTTPS）以及端口号（如果不同于标准端口 80 或 443）。
  • 回调 URL 将自动生成为 <Root_URL>/api/oidc/<LOGIN_OPTION_ID>/callback。
• SSL verify：是否验证 OIDC 提供商的 SSL/TLS 证书。
• Logout URL：结束用户会话并将其重定向到登录页面的 URL。这应该是 end_session_endpoint URL，并带有将 post_logout_redirect_uri 查询参数设置为 API7 控制台 URL 的配置，例如 http://192.168.10.101:8080/realms/quickstart-realm/protocol/openid-connect/logout?post_logout_redirect_uri=https://dashboard.your-company.com。
• Attributes Mapping：API7 用户字段到 OIDC 声明的映射。例如：
  • username：preferred_username
  • email：email
  • name：name

4. 点击 Add。

新的登录选项现在应出现在 API7 控制台登录页面上，允许你使用在 IdP 中创建的用户进行身份验证。用户登录后，以管理员用户身份登录，在顶部导航栏中导航到 Organization，然后选择 Users 以查看该用户。

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

important

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

管理用户角色和权限

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

信息

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

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

配置 Keycloak

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

例如，要在 Keycloak 中为用户分配值为 admin 的 position 属性，你可以将其配置为用户属性或通过组成员身份（Group Membership）进行配置。本节描述了 Keycloak 26.3.3 中的示例配置。如果你使用的是不同版本，请相应地调整配置。

提示

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

配置用户属性

1. 从 Realm Settings 启用 Unmanaged Attributes。

2. 在 Keycloak 中导航到该用户。

3. 转到 Attributes 选项卡。

4. 添加新属性，例如，将 Key 设置为 position，将 Value 设置为 admin。

5. 导航到 Client Scopes 并选择要向其添加映射器（mapper）的作用域，例如 profile。请注意，所选作用域应在 API7 控制台 Request Scope 中配置。

6. 通过配置（by configuration）添加一个映射器。从列表中选择 User Attribute，并填写配置：

   • Name：映射器的名称，例如 position。
   • User Attribute：用户属性的名称，例如 position。
   • Token Claim Name：要插入令牌的声明的名称，例如 position。
   • 默认情况下，此属性将包含在 UserInfo 中，API7 企业版使用它来获取用户属性。例如：

   {
     "email":"johndoe@api7.ai",
     "email_verified":false,
     "name":"John Doe",
     "preferred_username":"johndoe",
     "sub":"b724c7ed-ad74-4330-9365-e599fdfbffcc",
     ...
     "position":"admin"
   }

在 API7 控制台中，你可以使用 $.position，Exact Match，admin 映射规则。有关配置步骤，请参阅在控制台中配置映射。

通过组成员身份配置

1. 导航到 Keycloak 中的 Groups。

2. 创建一个新组，例如 admin。

3. 将用户添加到此组。

4. 导航到 Client Scopes 并选择要向其添加映射器的作用域，例如 profile。请注意，所选作用域应在 API7 控制台 Request Scope 中配置。

5. 通过配置（by configuration）添加一个映射器。从列表中选择 Group Membership，并填写配置：

   • Name：映射器的名称，例如 groups。
   • Token Claim Name：要插入令牌的声明的名称，例如 groups。
   • 默认情况下，此属性将包含在 UserInfo 中，API7 企业版使用它来获取用户属性。例如：

   {
     "email":"johndoe@api7.ai",
     "email_verified":false,
     "name":"John Doe",
     "preferred_username":"johndoe",
     "sub":"b724c7ed-ad74-4330-9365-e599fdfbffcc",
     ...
     "groups": ["/admin"]
   }

在 API7 控制台中，你可以使用 $.groups[*], Contains String, admin 作为映射规则。有关配置步骤，请参阅在控制台中配置映射。

在控制台中配置映射

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

启用角色映射

1. 从顶部导航栏中选择 Organization，然后选择 Settings。
2. 选择该登录选项。
3. 启用 Role Mapping。
4. 填写配置：

• Internal Role：要在 API7 企业版中分配的角色。例如，Super Admin。
• Role Attribute：IdP 中相应属性的 JSONPath。该属性应对应于 UserInfo 中的一个声明，例如 $.position。
• Operation：用于匹配属性值的比较方法。例如 Exact Match。
• Role Value：IdP 属性的值，例如 admin。

5. 点击 Enable。

现在，所有在 IdP 中 position 属性设置为 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 中的一个声明，例如 $.position。
• Operation：用于匹配属性值的比较方法。例如 Exact Match。
• Permission Boundary Value：IdP 属性的值。例如 admin。

5. 点击 Enable。

现在，所有在 IdP 中 position 属性设置为 admin 的用户，在下次登录时将自动分配 Admin License Restricted 权限边界。

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

删除登录选项

注意

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

1. 从顶部导航栏中选择 Organization，然后选择 Users。
2. 检查是否有任何用户仍在使用此登录选项。如果是，请在进行任何更改之前通知他们。
3. 从顶部导航栏中选择 Organization，然后选择 Settings。
4. 点击目标登录选项的 Delete。

附加资源

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