openid-connect

描述

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

属性

注意：schema 中还定义了 encrypt_fields = {"client_secret", "client_rsa_private_key"}，这意味着这些字段将在 etcd 中加密存储。详见加密存储字段。

此外，你可以使用环境变量或 APISIX Secret 来存储和引用插件属性。APISIX 目前支持两种存储密钥的方式——环境变量和 HashiCorp Vault。

例如，使用以下命令设置环境变量：

export KEYCLOAK_CLIENT_SECRET=abc

并在插件配置中引用：

"client_secret": "$ENV://KEYCLOAK_CLIENT_SECRET"

示例

以下示例展示了如何针对不同场景配置 openid-connect 插件。

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

授权码流程

授权码流程在 RFC 6749 第 4.1 节中定义。它涉及将临时授权码换取访问令牌，通常由机密客户端和公共客户端使用。

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

当传入请求的头中或合适的会话 Cookie 中不包含访问令牌时，插件作为依赖方重定向到授权服务器以继续授权码流程。

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

以下示例创建一个路由，并配置 openid-connect 插件以使用 Keycloak 作为身份提供商的授权码流程：

Admin API

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "openid-connect-route",
    "uri": "/api/v1/*",
    "plugins": {
      "openid-connect": {
        "client_id": "apisix",
        "client_secret": "your-client-secret",
        "discovery": "http://keycloak:8080/realms/master/.well-known/openid-configuration",
        "scope": "openid email profile",
        "redirect_uri": "http://127.0.0.1:9080/api/v1/redirect",
        "ssl_verify": false,
        "session": {
          "secret": "your-session-secret-min-16-chars"
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

ADC

routes:
  - id: openid-connect-route
    uri: /api/v1/*
    plugins:
      openid-connect:
        client_id: apisix
        client_secret: your-client-secret
        discovery: http://keycloak:8080/realms/master/.well-known/openid-configuration
        scope: openid email profile
        redirect_uri: http://127.0.0.1:9080/api/v1/redirect
        ssl_verify: false
        session:
          secret: your-session-secret-min-16-chars
    upstream:
      type: roundrobin
      nodes:
        httpbin.org:80: 1

Ingress Controller

Gateway API

apiVersion: v1
kind: Service
metadata:
  name: httpbin
  namespace: default
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  name: openid-connect-plugin-config
  namespace: default
spec:
  plugins:
    - name: openid-connect
      config:
        client_id: apisix
        client_secret: your-client-secret
        discovery: http://keycloak:8080/realms/master/.well-known/openid-configuration
        scope: openid email profile
        redirect_uri: http://127.0.0.1:9080/api/v1/redirect
        ssl_verify: false
        session:
          secret: your-session-secret-min-16-chars
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: openid-connect-route
  namespace: default
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1
      backendRefs:
        - name: httpbin
          port: 80
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: openid-connect-plugin-config

APISIX Ingress Controller

apiVersion: v1
kind: Service
metadata:
  name: httpbin
  namespace: default
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  name: openid-connect-route
  namespace: default
spec:
  http:
    - name: rule1
      match:
        paths:
          - /api/v1/*
      backends:
        - serviceName: httpbin
          servicePort: 80
      plugins:
        - name: openid-connect
          enable: true
          config:
            client_id: apisix
            client_secret: your-client-secret
            discovery: http://keycloak:8080/realms/master/.well-known/openid-configuration
            scope: openid email profile
            redirect_uri: http://127.0.0.1:9080/api/v1/redirect
            ssl_verify: false
            session:
              secret: your-session-secret-min-16-chars

详见实现授权码授权，获取使用 openid-connect 插件与 Keycloak 集成并使用授权码流程的完整示例。

PKCE (Proof Key for Code Exchange)

PKCE 在 RFC 7636 中定义。PKCE 通过添加代码挑战和验证器来增强授权码流程，防止授权码截取攻击。

下图展示了实现带 PKCE 的授权码流程时不同实体之间的交互：

要使用 PKCE，在插件配置中将 use_pkce 设置为 true。同时确保已配置 IdP 客户端以使用 PKCE。

详见实现授权码授权，获取使用 openid-connect 插件与 Keycloak 集成并使用带 PKCE 的授权码流程的示例。

客户端凭证流程

客户端凭证流程在 RFC 6749 第 4.4 节中定义。它涉及客户端使用自身凭证请求访问令牌以访问受保护资源，通常用于机器间认证，不代表特定用户。

下图展示了实现客户端凭证流程时不同实体之间的交互：

详见实现客户端凭证授权，获取使用 openid-connect 插件与 Keycloak 集成并使用客户端凭证流程的示例。

内省流程

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

在此流程中，当客户端向资源服务器提供访问令牌时，资源服务器向授权服务器的内省端点发送请求，如果令牌有效，端点将返回令牌详细信息，包括令牌过期时间、关联范围以及令牌所属的用户或客户端等信息。

下图展示了实现带令牌内省的授权码流程时不同实体之间的交互：

详见实现客户端凭证授权，获取使用 openid-connect 插件与 Keycloak 集成并使用带令牌内省的客户端凭证流程的示例。

密码流程

密码流程在 RFC 6749 第 4.3 节中定义。它专为受信任的应用程序设计，允许它们直接使用用户的用户名和密码获取访问令牌。在此授权类型中，客户端应用程序将用户凭证连同其自身的客户端 ID 和密钥一起发送到授权服务器，授权服务器对用户进行身份验证，如果有效则颁发访问令牌。

尽管效率较高，但此流程仅适用于高度受信任的第一方应用程序，因为它要求应用程序直接处理敏感的用户凭证，如果在第三方场景中使用会带来重大安全风险。

下图展示了实现密码流程时不同实体之间的交互：

详见实现密码授权，获取使用 openid-connect 插件与 Keycloak 集成并使用密码流程的示例。

刷新令牌授权

刷新令牌授权在 RFC 6749 第 6 节中定义。它使客户端无需用户重新认证，即可使用之前颁发的刷新令牌请求新的访问令牌。此流程通常在访问令牌过期时使用，允许客户端在无需用户干预的情况下保持对资源的持续访问。刷新令牌与访问令牌一起在某些 OAuth 流程中颁发，其生命周期和安全要求取决于授权服务器的配置。

下图展示了实现带刷新令牌的密码流程时不同实体之间的交互：

详见刷新令牌，获取使用 openid-connect 插件与 Keycloak 集成并使用带令牌刷新的密码流程的示例。

用户信息

OpenID Connect (OIDC) 中的 UserInfo 端点在 OpenID Connect Core 1.0 第 5.3 节中定义。它使客户端能够通过提供有效的访问令牌来检索已认证用户的额外 claim。此端点对于获取用户个人资料信息（如姓名、电子邮件和其他属性）特别有用，这些信息在用户认证后可通过该端点获取。UserInfo 端点返回的数据取决于访问令牌的范围以及授权服务器配置的 claim。

下图展示了在 APISIX 验证用户信息时，不同实体之间的交互过程。

当 set_userinfo_header 为 true（默认值）时，插件在 X-Userinfo 请求头中设置用户信息数据，上游服务可使用该数据进行进一步处理。

故障排除

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

APISIX 无法连接到 OpenID 提供商

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

未找到会话状态

如果在使用授权码流程时，日志中出现 500 internal server error 和以下消息，可能有多种原因。

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

1. 重定向 URI 配置错误

一个常见的配置错误是将 redirect_uri 配置为与路由 URI 相同。当用户发起访问受保护资源的请求时，请求直接到达重定向 URI，但请求中没有会话 Cookie，导致未找到会话状态的错误。

要正确配置重定向 URI，确保 redirect_uri 与配置了插件的路由匹配，但不完全相同。例如，正确的配置是将路由的 uri 配置为 /api/v1/*，将 redirect_uri 的路径部分配置为 /api/v1/redirect。

同时确保 redirect_uri 包含协议，例如 http 或 https。

2. 缺少会话密钥

如果你以独立模式部署 APISIX，请确保配置了 session.secret。

用户会话以 Cookie 形式存储在浏览器中，并使用会话密钥加密。如果未通过 session.secret 属性配置密钥，则会自动生成密钥并保存到 etcd。但在独立模式下，etcd 不再是配置中心。因此，你应在 YAML 配置中心 apisix.yaml 中为此插件显式配置 session.secret。

3. Cookie 未发送或缺失

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

4. 上游发送的头太大

如果你在 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 属性来调整存储在会话中的数据。例如，可以将 session_contents.access_token 设置为 true。

5. 客户端密钥无效

验证 client_secret 是否有效且正确。无效的 client_secret 会导致认证失败，且不会返回令牌并存储在会话中。

6. PKCE IdP 配置

如果你在授权码流程中启用了 PKCE，请确保你已配置 IdP 客户端以使用 PKCE。例如，在 Keycloak 中，你应在客户端的高级设置中配置 PKCE 挑战方法：