跳到主要内容

openid-connect

openid-connect 插件支持与 OpenID Connect (OIDC) 身份提供商（IdP）集成，例如 Keycloak、Auth0、Microsoft Entra ID、Google、Amazon Cognito、Okta 等。它允许 APISIX 在允许或拒绝客户端访问上游受保护资源之前，对其进行身份认证并从身份提供商获取其信息。

示例​

授权码流程​

授权码流程在 RFC 6749, Section 4.1 中定义。它涉及将临时授权码交换为访问 Token，通常用于机密客户端和公共客户端。

下图说明了在实现授权码流程时不同实体之间的交互：


当传入请求的请求头或相应的会话 Cookie 中不包含访问 Token 时，插件将充当依赖方，并重定向到授权服务器以继续授权码流程。

身份认证成功后，插件将 Token 保存在会话 Cookie 中，后续请求将使用存储在 Cookie 中的 Token。

参见使用 Keycloak 设置 SSO，了解如何使用 openid-connect 插件通过授权码流程与 Keycloak 集成。

参见使用 PAR 和 DPoP 保护 OIDC，了解如何使用 openid-connect 插件通过 PAR、DPoP、PKCE 和 private_key_jwt 客户端身份认证与 Keycloak 集成。

用于代码交换的证明密钥 (PKCE)​

用于代码交换的证明密钥 (PKCE) 在 RFC 7636 中定义。PKCE 通过添加代码挑战和验证器来增强授权码流程，以防止授权码拦截攻击。

下图说明了在实现带有 PKCE 的授权码流程时不同实体之间的交互：


参见使用 Keycloak 设置 SSO，了解如何使用 openid-connect 插件通过带有 PKCE 的授权码流程与 Keycloak 集成。

结合 PAR 和 DPoP 的授权码流程​

PAR、PKCE、private_key_jwt 和 DPoP 可以组合在同一个授权码流程中。请分别配置用于客户端身份认证和 DPoP 的签名密钥。此工作流自 API7 企业版 3.9.18 和 3.10.5 以及 APISIX 3.18.0 起支持。


在此工作流中，网关是向授权服务器发起 Token 请求和用户信息请求的 DPoP 客户端。它不会验证外部客户端调用受保护路由时提交的 DPoP 证明。

对于 APISIX 部署，请参阅使用 PAR 和 DPoP 保护 OIDC，其中提供了经过验证的 Keycloak 示例，涵盖密钥生成、配置和验证。

客户端凭据流程​

客户端凭据流程在 RFC 6749, Section 4.4 中定义。它涉及客户端使用自己的凭据请求访问 Token 以访问受保护资源，通常用于机器对机器的身份认证，不代表特定用户。

下图说明了使用本地 JWT 验证（例如配置 public_key 或 use_jwks）实现客户端凭据流程时，不同实体之间的交互：


参见使用 Keycloak 对 M2M 请求进行授权，了解如何使用 openid-connect 插件通过客户端凭据流程与 Keycloak 集成，并在本地验证 JWT。

内省流程​

内省流程在 RFC 7662 中定义。它涉及通过查询授权服务器的内省端点来验证访问 Token 的有效性和详细信息。

在此流程中，当客户端向资源服务器出示访问 Token 时，资源服务器向授权服务器的内省端点发送请求，如果 Token 处于活动状态，该端点将响应 Token 详细信息，包括 Token 过期时间、关联的范围以及它所属的用户或客户端等信息。

下图说明了在实现带有 Token 内省的授权码流程时不同实体之间的交互：


参见使用 Keycloak 对 M2M 请求进行授权，了解如何使用 openid-connect 插件通过客户端凭据流程与 Keycloak 集成，并使用 Token 内省。

刷新 Token 授予​

刷新 Token 授予在 RFC 6749, Section 6 中定义。客户端可以使用之前颁发的刷新 Token 请求新的访问 Token，而无需用户再次进行身份认证。能否使用刷新 Token 及其生命周期取决于授权服务器，以及最初颁发 Token 时采用的流程。

用户信息​

OpenID Connect (OIDC) 中的 UserInfo 端点在 OpenID Connect Core 1.0, Section 5.3 中定义。它使客户端能够通过出示有效的访问 Token 来检索有关已认证用户的其他 Claim。此端点对于在用户通过身份认证后获取用户个人资料信息（如姓名、电子邮件和其他属性）特别有用。UserInfo 端点返回的数据取决于访问 Token 的范围和授权服务器配置的 Claim。

下图说明了当 APISIX 验证用户信息时不同实体之间的交互：


参见根据 OIDC 用户组控制访问，了解如何使用 openid-connect 插件与 Keycloak 集成，并基于用户信息使用 API7 企业版 acl 插件实现访问控制。

故障排除​

本节涵盖了在使用此插件时常见的一些问题，以帮助您进行故障排除。

APISIX 无法连接到 OpenID 提供商​

如果 APISIX 无法解析或无法连接到 OpenID 提供商，请仔细检查配置文件 config.yaml 中的 DNS 设置，并根据需要进行修改。

授权回调中的 State 不匹配​

授权状态完成、被重放或被删除后，回调仍可能到达。自 API7 企业版 3.9.18 和 3.10.5 以及 APISIX 3.18.0 起，Multi Auth 之外过期的 GET 回调会重定向到最初请求的 URL，从而启动新的身份认证流程。如果身份提供商中仍存在 SSO 会话，该流程可以在无需再次提示用户的情况下完成。

使用其他 HTTP 方法、无法恢复目标 URL 或在 Multi Auth 中运行的回调仍会失败，而不会重定向。

身份提供商暂时不可用​

在 APISIX 3.18.0 中，如果授权回调包含 OAuth 错误 temporarily_unavailable，且其 state 可以验证，则回调会重定向到最初请求的 URL。这样会重新启动身份认证流程，而不是返回 500 Internal Server Error。

其他 OAuth 错误、缺失或无效的 state，以及非 GET 回调不会自动重试。

找不到会话状态​

如果您在使用 授权码流程 时遇到 500 internal server error 并在日志中看到以下消息，可能有多种原因。

the error request to the redirect_uri path, but there's no session state found

1. 重定向 URI 错误​

一种常见配置错误是将 redirect_uri 设置为与路由 URI 相同。当用户请求受保护资源时，请求会在不携带会话 Cookie 的情况下直接到达重定向 URI，从而产生 no session state found 错误。

请把 redirect_uri 配置为完全限定 URI，其路径应当匹配路由，但不能与受保护的请求路径完全相同。例如，如果路由 uri 为 /api/v1/*，请把 redirect_uri 设为 https://gateway.example.com/api/v1/redirect。同时，请在 OpenID 提供商中把同一 URI 配置为允许的重定向 URI。

如果未配置 redirect_uri，或其值是以 / 开头的根相对路径，网关会根据请求的协议方案和主机构建 URI。完全限定 URI 可以避免依赖这个从请求推导的来源。

2. 缺少 Session Secret​

当 bearer_only 为 false 时，请显式配置 session.secret。无论配置存储在 etcd 中，还是从 Standalone YAML 加载，缺少此字段时 APISIX 都会拒绝插件配置。密钥应至少包含 16 个字符；在多实例部署中，需要读取加密会话 Cookie 的每个网关实例都应使用相同的密钥。

检查 SameSite Cookie 属性是否设置正确（即，如果您的应用程序需要跨站点发送 Cookie），以查看这是否是阻止 Cookie 保存到浏览器 Cookie 存储或从浏览器发送的因素。

4. 身份认证会话已过期​

APISIX 在将浏览器重定向到身份提供商前，会把 state 参数和原始请求 URL 存入会话。如果浏览器返回重定向 URI 前该会话已过期，APISIX 将无法验证回调或恢复原始 URL。

请重新访问受保护的 URL，以发起新的身份认证流程。如果用户需要更多时间完成身份认证，请为 session.idling_timeout 配置合适的值。默认空闲超时时间为 900 秒。

5. 上游发送的响应头过大​

如果您的 APISIX 前面有 NGINX 代理客户端流量，请查看 NGINX 的 error.log 中是否观察到以下错误：

upstream sent too big header while reading response header from upstream

如果是这样，请尝试将 proxy_buffers、proxy_buffer_size 和 proxy_busy_buffers_size 调整为更大的值。

或者，调整插件的 session_contents 参数以仅包含必要的信息。例如，要仅包含访问 Token 和刷新 Token，您可以按如下方式配置插件：

{
  ...
  "plugins": {
    "openid-connect": {
      ...,
      "session_contents": {
        "access_token": true
      }
    }
  }
}

可用选项包括 id_token、user、enc_id_token 和 access_token（其中包括刷新 Token）。未配置时，所有内容都包含在会话中。

6. 无效的客户端密钥​

对于使用共享密钥向身份提供商认证的流程（例如 Token 内省，或未使用 PKCE 的授权码流程），请验证 client_secret。在仅使用 Bearer Token 的本地 JWT/JWKS 验证、非 Bearer Token 的 PKCE 流程，以及适用的 private_key_jwt 模式下，此字段为可选。在需要密钥的流程中，无效值会导致认证失败，且不会在会话中存储 Token。

introspection_endpoint_auth_method 默认为 client_secret_basic，它通过 Authorization 请求头发送客户端凭证。如果身份提供商要求在内省请求体中发送凭证，请将该方法设为 client_secret_post。

7. PKCE IdP 配置​

如果您正在启用带有授权码流程的 PKCE，请确保您已将 IdP 客户端配置为使用 PKCE。例如，在 Keycloak 中，您应该在客户端的高级设置中配置 PKCE 挑战方法：

PKCE keycloak configuration