使用 SAML 配置 SSO

本指南介绍如何使用 SAML 2.0 协议为 API7 控制台配置单点登录（SSO）。SAML SSO 允许用户通过企业身份提供商（IdP）进行认证，并在无需维护单独账户的情况下访问控制台。

工作原理

1. 用户在控制台登录页选择 SAML 登录选项。
2. 控制台向 IdP 发送 SAML AuthnRequest。
3. 认证完成后，IdP 会将 SAMLResponse POST 到控制台的断言消费服务（ACS）URL。
4. 控制台验证 SAML 断言，提取用户属性，并创建或更新用户账户。
5. 如果配置了角色和权限边界映射，这些映射会在每次登录时应用。

前置条件

开始前，请确保你已具备：

• 正在运行且可访问控制台的 API7 网关部署。
• 符合 SAML 2.0 标准的身份提供商，例如 Microsoft Entra ID、Okta 或 Ping Identity。
• 来自 IdP 的以下信息：
  • IdP Metadata URL：提供 IdP SAML 元数据 XML 的 URL。
  • 属性名称：username、email 以及所有角色相关属性的声明名称。

第 1 步：创建 SAML 登录选项

首先在 API7 中创建登录选项，以生成服务提供商（SP）元数据 URL，后续配置 IdP 时需要使用这些 URL。

1. 在 API7 控制台中，进入 Organization > Settings。
2. 点击 Add Login Option。
3. 填写配置：

字段	描述	示例
Name	登录页显示的名称，格式为 "Login with {Name}"	Corporate SAML
Provider	选择 SAML	—
Identity Provider Metadata URL	IdP SAML 元数据 XML 的 URL	https://login.microsoftonline.com/{tenant}/federationmetadata/...
Service Provider Root URL	用户访问控制台的 URL	https://dashboard.example.com
Entity ID	SAML 联邦中 SP 的唯一标识。建议使用控制台 URL。	https://dashboard.example.com
Attributes Mapping	将 SAML 断言属性映射到 API7 用户字段	见下方提供商专用部分
Terminate IdP Session on Logout	退出时是否重定向到 IdP 进行 Single Logout（SLO）	false

4. 点击 Add。

创建后，登录选项会显示以下自动生成的 URL：

URL	用途
ACS URL	https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/acs——IdP POST SAML 响应的端点
SLO URL	https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/slo——Single Logout 回调端点
SP Metadata URL	https://<DASHBOARD_URL>/api/saml/<LOGIN_OPTION_ID>/metadata——可导入 IdP 的 SP 元数据 XML

备注

如果你没有提供自定义证书，API7 会自动生成自签名证书和私钥用于 SAML 请求签名。你也可以在登录选项配置中提供自定义 SP 证书和私钥。

第 2 步：配置 IdP

使用第 1 步中的 ACS URL 和 Entity ID，在身份提供商中将 API7 控制台注册为服务提供商。

关于特定 IdP 的详细说明，请参阅下方提供商专用配置部分。

第 3 步：验证 SSO 登录

1. 退出 API7 控制台。
2. 在登录页，你应看到一个新选项：Login with {Name}。
3. 点击该选项，通过 IdP 完成认证。
4. 认证成功后，你会被重定向回控制台。

SSO 用户会出现在 Organization > Users 下。默认情况下，该用户未分配任何角色。

important

在控制台中删除用户会移除其角色和权限边界，但该用户仍可再次作为新用户登录。若要完全撤销访问权限，请从 IdP 中移除该用户。

配置角色映射

角色映射会根据 SAML 断言属性自动为 SSO 用户分配 API7 角色。请配置 IdP，使其在 SAML 响应中包含角色相关属性，然后在 API7 中设置映射规则。

信息

自动角色映射优先于手动角色分配。启用映射后，用户下次登录时会覆盖任何手动更改。

启用角色映射

1. 在 API7 控制台中，进入 Organization > Settings。
2. 选择你的 SAML 登录选项。
3. 启用 Role Mapping。
4. 配置映射规则：

字段	描述	示例
Internal Role	要分配的 API7 角色	Super Admin
Role Attribute	指向 SAML 属性的 JSONPath	$.Role
Operation	比较方式：Exact Match、Contains String、Exact Match in Array 或 Contains String in Array	Exact Match
Role Value	期望的属性值	admin

5. 点击 Enable。

权限边界映射

权限边界映射的工作方式与角色映射相同，但它将权限策略作为边界分配，而不是附加角色。有关策略和边界的定义，请参阅权限策略和权限边界。请在登录选项设置中启用 Permission Boundary Mapping，并使用相同的属性匹配方式配置映射规则。

提供商专用配置

Microsoft Entra ID (Azure AD)

IdP 设置

1. 在 Azure portal 中，进入 Microsoft Entra ID > Enterprise applications。
2. 点击 New application > Create your own application：
   • 输入名称，例如 API7 Dashboard。
   • 选择 Integrate any other application you don't find in the gallery (Non-gallery)。
3. 在 Users and groups 下，添加需要拥有 API7 SSO 访问权限的用户和组。
4. 在 Single sign-on 下，选择 SAML 并配置：
   • Identifier (Entity ID)：使用 API7 中的 Entity ID，例如 https://dashboard.example.com。
   • Reply URL (ACS URL)：使用 API7 中的 ACS URL，例如 https://dashboard.example.com/api/saml/<LOGIN_OPTION_ID>/acs。
5. 在 SAML Signing Certificate 部分找到 App Federation Metadata URL，并将其作为 API7 中的 Identity Provider Metadata URL。

属性映射配置

Azure AD 默认使用完整 URI 格式的声明名称：

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

角色映射

1. 在 App roles 下创建角色，例如 Admin。
2. 在 Enterprise applications > Users and groups 下，将角色分配给用户。
3. 在 Azure 中，进入 Single sign-on > Attributes & Claims，并添加包含已分配角色的声明，例如声明名称 Role。
4. 在 API7 中使用映射规则：属性 $.Role，操作 Exact Match，值 Admin。

Okta

IdP 设置

1. 在 Okta Admin Console 中，进入 Applications > Applications。
2. 点击 Create App Integration 并选择 SAML 2.0。
3. 配置 SAML 设置：
   • Single sign-on URL：使用 API7 中的 ACS URL，例如 https://dashboard.example.com/api/saml/<LOGIN_OPTION_ID>/acs。
   • Audience URI (SP Entity ID)：使用 API7 中相同的 Entity ID，例如 https://dashboard.example.com。
   • Name ID format：EmailAddress 或 Unspecified。
4. 在 Attribute Statements 下配置：
   • 将 username 映射到 user.login。
   • 将 email 映射到 user.email。
   • 将 name 映射到 user.firstName + " " + user.lastName。
5. 创建应用后，在 Sign On 标签页下找到 Identity Provider metadata URL。
6. 在 Assignments 标签页下将用户分配给该应用。

属性映射配置

API7 字段	SAML 属性
username	username
email	email
name	name

角色映射

1. 在 Attribute Statements 下添加 role 属性，例如映射到用户资料属性或组成员关系。
2. 在 API7 中使用映射规则：属性 $.role，操作 Exact Match，值 admin。

删除登录选项

注意

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

1. 进入 Organization > Users，确认哪些用户与该登录选项关联。
2. 进入 Organization > Settings。
3. 在登录选项上点击 Delete。

备注

必须始终至少保留一个启用状态的登录选项。你不能删除或禁用最后一个仍启用的登录选项。

其他资源

• 使用 OIDC 配置 SSO
• 使用 LDAP 实现单点登录
• 控制台单点登录
• 角色与权限策略
• 基于角色的访问控制（RBAC）