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

使用 Microsoft Entra ID 和 SAML 配置控制台 SSO

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

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

设置 SSO 集成​

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

配置 Microsoft Entra ID​

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

  1. 在 Azure Portal（Azure 门户）中，导航至 Microsoft Entra ID。
  2. 创建一个 enterprise application（企业应用程序）。选择 create your own application（创建你自己的应用程序）选项：
    1. 填写应用程序的名称，例如 API7。
    2. 选择 Integrate any other application you don't find in the gallery (Non-gallery)（集成你在库中找不到的任何其他应用程序 (非库)）选项。
  3. 在该应用程序中，选择 users and groups（用户和组）选项卡以添加所有必要的用户和组。只有被添加的用户和组才能通过 SSO 登录 API7。
  4. 在该应用程序中，导航至 single sign-on（单点登录）选项卡并启用 SAML。启用 SAML 后，为你的应用找到以下信息：
    1. App Federation Metadata URL（应用联合元数据 URL）：公开 SAML 配置详细信息的 URL，例如 https://login.microsoftonline.com/<TENANT_ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP_ID>。
    2. Claim Names（声明名称）：SAML 令牌中用户属性的唯一标识符，用于将身份提供商的数据映射到服务提供商中的相应字段。找到 username（用户名）和 email（电子邮件）的声明名称，例如 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 和 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress。
  5. 完成下面的创建控制台登录选项说明，因为后续配置需要来自 API7 的信息。
  6. 在该应用程序中，导航至 single sign-on（单点登录）选项卡并编辑 Basic SAML Configuration（基本 SAML 配置）：
    1. Identifier (Entity ID)（标识符 (实体 ID)）：用于在 SAML 联合中表示特定实体的唯一标识符。此标识符必须在 API7 和 IdP 之间保持唯一且一致。建议使用 API7 控制台 URL，例如 https://dashboard.your-company.com，尽管可以使用任何唯一的字符串。
    2. Reply URL (Assertion Consumer Service URL)（回复 URL (断言消费者服务 URL)）：用户成功登录后，身份提供商向其发送 SAML 身份验证响应的服务提供商端点，例如 https://dashboard.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs。

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

创建控制台登录选项​

  1. 从顶部导航栏选择 组织 (Organization)，然后选择 设置 (Settings)。
  2. 点击 添加登录选项 (Add Login Option)。
  3. 填写配置：
  • 名称 (Name)：唯一的登录名称。该名称应易于用户识别。例如，如果你将名称配置为 Employee Account，你将在控制台登录页面看到 Login with Employee Account（使用员工账号登录）选项。
  • 提供商 (Provider)：选择 SAML。
  • 身份提供商元数据 URL (Identity Provider Metadata URL)：身份提供商的元数据 URL，例如 https://login.microsoftonline.com/<TENANT_ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP_ID>。
  • 服务提供商根 URL (Service Provider Root URL)：你的服务提供商的根 URL。通常是 API7 控制台的地址，例如 https://dashboard.your-company.com。
  • 实体 ID (Entity ID)：用于在 SAML 联合中表示特定实体的唯一标识符。此标识符必须在 API7 和 IdP 之间保持唯一且一致。建议使用 API7 控制台 URL，例如 https://dashboard.your-company.com，尽管可以使用任何唯一的字符串。
  • 属性映射 (Attributes Mapping)：API7 用户字段映射到 SAML 声明。例如：
    • username: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    • email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    • name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • 注销时终止 IdP 会话 (Terminates IdP Session on Logout)：你可以选择性地启用在注销时终止 IdP 会话。
  1. 点击 添加 (Add)。
  2. 在新的 SAML 登录选项中，找到 服务提供商 ACS URL (Service Provider ACS URL)，例如 https://dashboard.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs。
  3. 返回到上面的配置 Microsoft Entra ID，步骤 6。

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

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

important

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

管理用户角色和权限​

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

信息

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

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

配置 Microsoft Entra ID​

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

例如，要将属性分配给 Microsoft Entra ID 中的用户，你可以将其配置为用户属性或通过组成员身份进行配置。本节描述在 Microsoft Entra ID (Azure AD) 中的示例配置。如果你使用的是其他的身份提供商 (IdP)，请参阅你 IdP 的文档并相应地调整配置。

提示

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

配置为用户属性​

  1. 在 Microsoft Entra ID 中，转到 Users（用户），并为稍后应具有 API7 管理员角色的用户添加 admin 作为 job title（职位）。
  2. 在你的企业应用程序中，导航至 single sign-on（单点登录）选项卡并编辑 Attributes & Claims（属性和声明）。
  3. 选择 Add new claim（添加新声明）。将名称配置为 position，选择 Attribute（属性）作为来源，并使用 user.jobtitle 作为 Source attribute（源属性）。

这会在这些用户的 SAML 断言中分配值为 admin 的 position 属性。在 API7 控制台中，你可以使用 position, Exact Match, admin 映射规则。有关配置步骤，请参阅在控制台中配置映射。

通过组成员身份配置​

  1. 在 Microsoft Entra ID 中，转到 Groups（组）并创建一个名为 admin 的新安全组。记下组 ID，例如 40cec5d2-72f2-43f5-b096-b4189012a386。
  2. 将用户添加到组中。该组中的成员稍后应具有 API7 管理员角色。
  3. 在你的企业应用程序中，导航至 single sign-on（单点登录）选项卡并编辑 Attributes & Claims（属性和声明）。
  4. 选择 Add a group claim（添加组声明）。选择 Security groups（安全组）作为组类型，并使用 Group ID（组 ID）作为 Source attribute（源属性）。

这会创建一个名为 http://schemas.microsoft.com/ws/2008/06/identity/claims/groups 的新声明。

在 API7 控制台中，你可以使用 http://schemas.microsoft.com/ws/2008/06/identity/claims/groups, Exact Match in Array, 40cec5d2-72f2-43f5-b096-b4189012a386 映射规则。有关配置步骤，请参阅在控制台中配置映射。

在控制台中配置映射​

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

启用角色映射​

  1. 从顶部导航栏选择 组织 (Organization)，然后选择 设置 (Settings)。
  2. 选择该登录选项。
  3. 启用 角色映射 (Role Mapping)。
  4. 填写配置：
  • 内部角色 (Internal Role)：要在 API7 企业版中分配的角色。例如，Super Admin（超级管理员）。
  • 角色属性 (Role Attribute)：指向 IdP 中相应属性的 JSONPath。该属性应对应于 SAML 断言中的一个属性，例如 position。
  • 操作符 (Operation)：用于匹配属性值的比较方法。例如，Exact Match（精准匹配）。
  • 角色值 (Role Value)：IdP 属性的值，例如 admin。
  1. 点击 启用 (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。该属性应对应于 SAML 断言中的一个属性，例如 position。
  • 操作符 (Operation)：用于匹配属性值的比较方法。例如，Exact Match（精准匹配）。
  • 权限边界值 (Permission Boundary Value)：IdP 属性的值。例如，admin。
  1. 点击 启用 (Enable)。

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

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

删除登录选项​

注意

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

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

附加资源​