# OAuth 2.0 和 OIDC

API7 网关通过 OAuth 2.0 和 OpenID Connect（OIDC）支持现代化的 Token 身份认证。使用 `openid-connect` 插件，可以将用户身份认证委托给集中式身份提供商（IdP），并对 API 实施细粒度访问控制。

## 功能[​](#功能 "功能的直接链接")

* **无缝集成**：连接任何符合 OIDC 标准的 IdP（Okta、Keycloak、Auth0、Azure AD）。
* **Token 验证**：自动验证 JWT 签名、过期时间和颁发者。
* **刷新 Token 处理**：在网关层安全处理 Token 刷新流程。
* **作用域访问控制**：根据 OAuth 2.0 作用域或 OIDC 声明限制 API 访问。

## 配置 OIDC 身份认证[​](#配置-oidc-身份认证 "配置 OIDC 身份认证的直接链接")

要使用 OIDC 保护路由，需要使用 IdP 的详细信息配置 `openid-connect` 插件。

开始前，请按照[从控制台获取 Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md)中的步骤获取 Token。

* Admin API
* ADC

```
# 为要保护的上游创建服务

curl -k "https://localhost:7443/apisix/admin/services/oidc-protected-service?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "oidc-protected-service",

    "upstream": {

      "type": "roundrobin",

      "scheme": "https",

      "nodes": [

        { "host": "your-upstream.example.com", "port": 443, "weight": 100 }

      ]

    }

  }'



# 在该服务下创建路由并启用 openid-connect 插件

curl -k "https://localhost:7443/apisix/admin/routes/oidc-protected-route?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "oidc-protected-route",

    "service_id": "oidc-protected-service",

    "paths": ["/secure-api/*"],

    "plugins": {

      "openid-connect": {

        "client_id": "YOUR_CLIENT_ID",

        "client_secret": "YOUR_CLIENT_SECRET",

        "discovery": "https://{IDP_DOMAIN}/.well-known/openid-configuration",

        "scope": "openid profile email",

        "bearer_only": true

      }

    }

  }'
```

如果不是在本地运行，请将 `localhost` 替换为 Admin API 主机。如果 Admin API 使用自签名 TLS 证书，则必须使用 `-k` 标志。将 `{gateway_group_id}` 替换为控制台的 **网关组** 页面中显示的网关组 ID（快速入门创建的网关组使用 `default`）。

adc.yaml

```
services:

  - name: oidc-protected-service

    upstream:

      scheme: https

      nodes:

        - host: your-upstream.example.com

          port: 443

          weight: 100

    routes:

      - name: oidc-protected-route

        uris:

          - /secure-api/*

        plugins:

          openid-connect:

            client_id: YOUR_CLIENT_ID

            client_secret: YOUR_CLIENT_SECRET

            discovery: "https://{IDP_DOMAIN}/.well-known/openid-configuration"

            scope: "openid profile email"

            bearer_only: true

    labels:

      docs-example: oidc-protected-service
```

预览本示例管理的资源变更，确认没有非预期的更新或删除：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=oidc-protected-service
```

审查变更后同步配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=oidc-protected-service
```

## Token 验证和声明[​](#令牌验证和声明 "Token 验证和声明的直接链接")

身份认证成功后，网关可以：

1. 使用 IdP 的公钥验证 Token 签名（通过发现端点自动获取）。
2. 检查 Token 过期时间（`exp`）和颁发者（`iss`）。
3. 将用户信息或声明注入请求头，供上游使用。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* [控制台单点登录（SSO）](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-dashboard.md)，以集中管理内部用户访问。
* [基于角色的访问控制（RBAC）](https://docs.apiseven.com/api7-gateway/security-and-compliance/role-based-access-control.md)：根据 OIDC 声明实施访问控制。
