# 使用 OIDC 配置 SSO

本指南介绍如何使用 OpenID Connect（OIDC）协议为 API7 控制台配置单点登录（SSO）。OIDC SSO 允许用户使用现有企业凭证进行认证，无需单独维护控制台账户。

## 工作原理[​](#工作原理 "工作原理的直接链接")

<!-- -->

1. 用户在控制台登录页选择 OIDC 登录选项。
2. 浏览器会重定向到 IdP 授权端点。
3. 认证完成后，IdP 会携带授权码重定向回控制台。
4. 控制台使用授权码换取 Token，获取用户信息，并创建或更新用户账户。
5. 如果配置了角色和权限边界映射，这些映射会在每次登录时应用。

## 前置条件[​](#前置条件 "前置条件的直接链接")

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

* 正在运行且可访问控制台的 API7 网关部署。

* 符合 OIDC 标准的身份提供商，例如 Keycloak、Microsoft Entra ID、Auth0 或 Okta。

* 来自 IdP 的以下信息：

  <!-- -->

  * **Issuer URL**：OIDC 发现端点，不包含 `/.well-known/openid-configuration`。
  * **Client ID**：在 IdP 中注册的应用标识符。
  * **Client Secret**：应用密钥。

## 第 1 步：在 IdP 中注册 API7 控制台[​](#第-1-步在-idp-中注册-api7-控制台 "第 1 步：在 IdP 中注册 API7 控制台的直接链接")

在你的身份提供商中将 API7 控制台注册为 OIDC 客户端应用程序：

1. 创建一个新的应用程序，授权类型选择 **Authorization Code**（也称为 "standard flow" 或 "confidential client"）。

2. 将重定向 URI 设置为：`https://<DASHBOARD_URL>/api/oidc/<LOGIN_OPTION_ID>/callback`。

   备注

   `LOGIN_OPTION_ID` 会在 API7 中创建登录选项后生成（第 2 步）。完成第 2 步后，你可能需要回到 IdP 更新重定向 URI。

3. 记录 **Client ID**、**Client Secret** 和 **Issuer URL**，供下一步使用。

关于特定 IdP 的详细说明，请参阅下方[提供商专用配置](#provider-specific-configuration)部分。

## 第 2 步：创建 OIDC 登录选项[​](#第-2-步创建-oidc-登录选项 "第 2 步：创建 OIDC 登录选项的直接链接")

1. 在 API7 控制台中，进入 **组织 > 设置**。
2. 点击 **新增登录选项**。
3. 填写配置：

| 字段           | 描述                                                                   | 示例                                                                                        |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **名称**       | 登录页显示的名称，格式为 "使用 {Name} 登录"                            | `Corporate SSO`                                                                             |
| **提供商**     | 选择 `OIDC`                                                            | —                                                                                           |
| **发行方**     | OIDC 提供商的 Issuer URL，不包含 `/.well-known/openid-configuration`   | `https://idp.example.com/realms/my-realm`                                                   |
| **客户端 ID**  | 来自 IdP 的应用标识符                                                  | `api7-dashboard`                                                                            |
| **客户端密钥** | 来自 IdP 的应用密钥                                                    | `********`                                                                                  |
| **请求范围**   | 空格分隔的作用域列表。`openid` 是必需项。                              | `openid profile email`                                                                      |
| **根地址**     | 用户访问控制台的 URL。必须匹配协议、主机和端口。                       | `https://dashboard.example.com`                                                             |
| **SSL 验证**   | 是否验证 IdP 的 TLS 证书                                               | `true`                                                                                      |
| **登出 URL**   | IdP 的 `end_session_endpoint` URL，可选携带 `post_logout_redirect_uri` | `https://idp.example.com/.../logout?post_logout_redirect_uri=https://dashboard.example.com` |
| **属性映射**   | 将 IdP 声明映射到 API7 用户字段：`username`、`email`、`name`           | `preferred_username`、`email`、`name`                                                       |

4. 点击 **新增**。

创建后，登录选项会显示其 **回调 URL**。复制该 URL，并将其作为重定向 URI 注册到你的 IdP 中（如果第 1 步尚未完成）。

## 第 3 步：验证 SSO 登录[​](#第-3-步验证-sso-登录 "第 3 步：验证 SSO 登录的直接链接")

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

SSO 用户会出现在 **组织 > 用户** 下。默认情况下，该用户未分配任何角色，无法管理资源，直到你配置角色映射或手动分配角色。

important

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

## 配置角色映射[​](#配置角色映射 "配置角色映射的直接链接")

角色映射会根据身份提供商中的属性自动为 SSO 用户分配 API7 角色。这样可以免去手动分配角色，并保持权限同步。

信息

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

### 第 1 步：在 IdP 中暴露角色属性[​](#第-1-步在-idp-中暴露角色属性 "第 1 步：在 IdP 中暴露角色属性的直接链接")

配置 IdP，使其在用户信息或 Token 声明中包含角色相关属性。具体方式因 IdP 而异：

* **用户属性**：直接在用户资料中添加属性，例如 `position: admin`。
* **组成员关系**：将用户加入某个组，例如 `api7-admins`，并将组成员关系作为声明提供。

详细说明请参阅[提供商专用配置](#provider-specific-configuration)部分。

### 第 2 步：在 API7 中启用角色映射[​](#第-2-步在-api7-中启用角色映射 "第 2 步：在 API7 中启用角色映射的直接链接")

1. 在 API7 控制台中，进入 **组织 > 设置**。
2. 选择你的 OIDC 登录选项。
3. 启用 **角色映射**。
4. 配置映射规则：

| 字段         | 描述                                                                                 | 示例                       |
| ------------ | ------------------------------------------------------------------------------------ | -------------------------- |
| **内部角色** | 要分配的 API7 角色                                                                   | `Super Admin`              |
| **角色属性** | 指向 IdP 属性的 [JSONPath](https://goessner.net/articles/JsonPath)                   | `$.position` 或 `$.groups` |
| **操作**     | 比较方式：**精确匹配**、**包含字符串**、**数组中的精确匹配** 或 **数组中包含字符串** | **精确匹配**               |
| **角色值**   | 期望的属性值                                                                         | `admin`                    |

5. 点击 **开启**。

具有匹配属性的用户会在下次登录时自动分配指定角色。

### 权限边界映射[​](#权限边界映射 "权限边界映射的直接链接")

权限边界映射的工作方式与角色映射相同，但它将权限策略作为边界分配，而不是附加角色。有关策略和边界的定义，请参阅[权限策略和权限边界](https://docs.apiseven.com/api7-gateway/security-and-compliance/permission-policies-and-boundaries.md)。请在登录选项设置中启用 **权限边界映射**，并使用相同的属性匹配方式配置映射规则。

## 提供商专用配置[​](#provider-specific-configuration "提供商专用配置的直接链接")

### Keycloak[​](#keycloak "Keycloak的直接链接")

#### IdP 设置[​](#idp-设置 "IdP 设置的直接链接")

1. 创建一个 **realm**，例如 `my-realm`。

2. 创建一个 **client**，例如 `api7-dashboard`：

   <!-- -->

   * 启用 **client authentication**（confidential access type）。
   * 启用 **standard flow**（authorization code grant）。
   * 将重定向 URI 设置为 `https://<DASHBOARD_URL>/api/oidc/<LOGIN_OPTION_ID>/callback`。

3. 在 client 的 **Credentials** 标签页中，复制 **Client Secret**。

4. 根据需要创建带密码的 **users**。

5. 在 **Realm Settings** 中找到 **OpenID Connect Discovery** 链接并记录：

   <!-- -->

   * `issuer` URL，例如 `https://keycloak.example.com/realms/my-realm`。
   * 用作 Logout URL 的 `end_session_endpoint` URL。

#### 属性映射配置[​](#属性映射配置 "属性映射配置的直接链接")

| 属性映射 | IdP 声明             | API7 字段  |
| -------- | -------------------- | ---------- |
| username | `preferred_username` | `username` |
| email    | `email`              | `email`    |
| name     | `name`               | `name`     |

#### 通过用户属性映射角色[​](#通过用户属性映射角色 "通过用户属性映射角色的直接链接")

1. 在 **Realm Settings** 中启用 **Unmanaged Attributes**。

2. 进入用户的 **Attributes** 标签页，并添加键值对，例如 `position: admin`。

3. 在 **Client Scopes** 中，选择 **Request Scope** 中包含的作用域，例如 `profile`。

4. 添加 **User Attribute** mapper：

   <!-- -->

   * **User Attribute**：`position`
   * **Token Claim Name**：`position`

5. 在 API7 中使用映射规则：属性 `$.position`，操作 **精确匹配**，值 `admin`。

#### 通过组成员关系映射角色[​](#通过组成员关系映射角色 "通过组成员关系映射角色的直接链接")

1. 创建一个 **group**，例如 `admin`，并将用户加入该组。
2. 在 **Client Scopes** 中添加 **Group Membership** mapper：
   <!-- -->
   * **Token Claim Name**：`groups`
3. 检查 ID Token 中的 `groups` Claim，并复制该组的确切值。在 API7 中使用映射规则：属性 `$.groups`，操作 **数组中的精确匹配**，值 `/admin`（如果 Token 中的确切值不同，请使用该值）。

### Microsoft Entra ID (Azure AD)[​](#microsoft-entra-id-azure-ad "Microsoft Entra ID (Azure AD)的直接链接")

#### IdP 设置[​](#idp-设置-1 "IdP 设置的直接链接")

1. 在 [Azure portal](https://portal.azure.com/) 中，进入 **Microsoft Entra ID > App registrations** 并注册一个新应用。
2. 在 **Certificates & secrets** 下创建新的客户端密钥并保存。
3. 在 **Endpoints** 下找到 **OpenID Connect metadata document** URL。提取颁发者 URL，例如 `https://login.microsoftonline.com/{tenant-id}/v2.0`。
4. 在 **Authentication** 下添加重定向 URI：`https://<DASHBOARD_URL>/api/oidc/<LOGIN_OPTION_ID>/callback`。

#### 属性映射配置[​](#属性映射配置-1 "属性映射配置的直接链接")

| 属性映射 | IdP 声明             | API7 字段  |
| -------- | -------------------- | ---------- |
| username | `preferred_username` | `username` |
| email    | `email`              | `email`    |
| name     | `name`               | `name`     |

备注

Issuer URL 不应包含 `/.well-known/openid-configuration`。

#### 角色映射[​](#角色映射 "角色映射的直接链接")

1. 在 **App roles** 下创建角色，例如 `SuperAdmin`。
2. 在 **Enterprise applications** 下将角色分配给用户。
3. 在 API7 中使用映射规则：属性 `$.roles`，操作 **数组中的精确匹配**，值 `SuperAdmin`。

### Auth0[​](#auth0 "Auth0的直接链接")

#### IdP 设置[​](#idp-设置-2 "IdP 设置的直接链接")

1. 在 **Applications** 下创建一个 **Regular Web Application**。

2. 记录 **Client ID**、**Client Secret** 和 **Domain**（issuer）。

3. Issuer URL 为 `https://<DOMAIN>/`（包含末尾斜杠）。

4. 在应用的 **Settings** 标签页下：

   <!-- -->

   * 将回调 URL 添加到 **Allowed Callback URLs**。
   * 将控制台 URL 添加到 **Allowed Logout URLs** 和 **Allowed Web Origins**。

5. 查看 `https://<DOMAIN>/.well-known/openid-configuration` 中的发现文档，找到 `end_session_endpoint`。

#### 属性映射配置[​](#属性映射配置-2 "属性映射配置的直接链接")

| 属性映射 | IdP 声明 | API7 字段  |
| -------- | -------- | ---------- |
| username | `name`   | `username` |
| email    | `email`  | `email`    |
| name     | `name`   | `name`     |

#### 角色映射[​](#角色映射-1 "角色映射的直接链接")

Auth0 需要通过登录后操作（post-login Action）将角色写入 Token 声明：

1. 在 **User Management > Roles** 下创建角色，例如 `admin`，并分配用户。
2. 在 **Actions > Triggers** 下创建一个 `post-login` 操作：

```
exports.onExecutePostLogin = async (event, api) => {

  const roles = (event.authorization && event.authorization.roles) || [];

  const claimName = "https://dashboard.example.com/roles";

  api.idToken.setCustomClaim(claimName, roles);

  api.accessToken.setCustomClaim(claimName, roles);

};
```

3. 将该操作绑定到 **Post Login** 触发器。
4. 在 API7 中使用映射规则：属性 `$['https://dashboard.example.com/roles']`，操作 **数组中的精确匹配**，值 `admin`。

## 删除登录选项[​](#删除登录选项 "删除登录选项的直接链接")

注意

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

1. 进入 **组织 > 用户**，确认哪些用户与该登录选项关联。
2. 进入 **组织 > 设置**。
3. 在登录选项上点击 **删除**。

备注

始终必须保留至少一个已启用的登录选项。你无法删除或禁用最后一个已启用的登录选项。

## 其他资源[​](#其他资源 "其他资源的直接链接")

* [使用 SAML 配置 SSO](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-saml.md)
* [使用 LDAP 实现单点登录](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-ldap.md)
* [控制台单点登录](https://docs.apiseven.com/api7-gateway/enterprise-features/dashboard-sso.md)
* [角色与权限策略](https://docs.apiseven.com/api7-gateway/security-and-compliance/role-based-access-control.md)
* [基于角色的访问控制（RBAC）](https://docs.apiseven.com/api7-gateway/security-and-compliance/role-based-access-control.md)
