openid-connect

描述

OpenID Connect（OIDC）是基于 OAuth 2.0 的身份认证协议，APISIX 可以与支持该协议的身份认证服务对接，如 Okta、Keycloak、Ory Hydra、Authing 等，实现对客户端请求的身份认证。

属性

注意：schema 中还定义了 encrypt_fields = {"client_secret"}，这意味着该字段将会被加密存储在 etcd 中。具体参考 加密存储字段。

使用场景

tip

教程：使用 Keycloak 与 API 网关保护你的 API

该插件提供两种使用场景：

1. 应用之间认证授权：将 bearer_only 设置为 true，并配置 introspection_endpoint 或 public_key 属性。该场景下，请求头（Header）中没有令牌或无效令牌的请求将被拒绝。

2. 浏览器中认证授权：将 bearer_only 设置为 false。认证成功后，该插件可获得并管理 Cookie 中的令牌，后续请求将使用该令牌。在这种模式中，用户 session 将作为 Cookie 存储在浏览器中，这些数据是加密的，因此你必须通过 session.secret 设置一个密钥用于加密。

令牌内省

令牌内省是通过针对 OAuth 2.0 授权的服务器来验证令牌及相关请求，详情请阅读 Token Introspection。

首先，需要在身份认证服务器中创建受信任的客户端，并生成用于内省的有效令牌（JWT）。下图是通过网关进行令牌内省的成功示例流程：

以下示例是在路由上启用插件。该路由将通过内省请求头中提供的令牌来保护上游：

note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

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

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
  "uri": "/get",
  "plugins":{
    "openid-connect":{
      "client_id": "${CLIENT_ID}",
      "client_secret": "${CLIENT_SECRET}",
      "discovery": "${DISCOVERY_ENDPOINT}",
      "introspection_endpoint": "${INTROSPECTION_ENDPOINT}",
      "bearer_only": true,
      "realm": "master",
      "introspection_endpoint_auth_method": "client_secret_basic"
    }
  },
  "upstream":{
    "type": "roundrobin",
    "nodes":{
      "httpbin.org:443":1
    }
  }
}'

以下命令可用于访问新路由：

curl -i -X GET http://127.0.0.1:9080/get -H "Authorization: Bearer {JWT_TOKEN}"

在此示例中，插件强制在请求头中设置访问令牌和 Userinfo 对象。

当 OAuth 2.0 授权服务器返回结果里除了令牌之外还有过期时间，其中令牌将在 APISIX 中缓存直至过期。更多信息请参考：

1. lua-resty-openidc 的文档和源代码。
2. exp 字段的定义：Introspection Response。

公钥内省

除了令牌内省外，还可以使用 JWT 令牌的公钥进行验证。如果使用了公共密钥和令牌内省端点，就会执行公共密钥工作流，而不是通过身份服务器进行验证。该方式适可用于减少额外的网络调用并加快认证过程。

以下示例展示了如何将公钥添加到路由中：

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
  "uri": "/get",
  "plugins":{
    "openid-connect":{
      "client_id": "${CLIENT_ID}",
      "client_secret": "${CLIENT_SECRET}",
      "discovery": "${DISCOVERY_ENDPOINT}",
      "bearer_only": true,
      "realm": "master",
      "token_signing_alg_values_expected": "RS256",
      "public_key": "-----BEGIN PUBLIC KEY-----
      {public_key}
      -----END PUBLIC KEY-----"
    }
  },
  "upstream":{
    "type": "roundrobin",
    "nodes":{
      "httpbin.org:443":1
    }
  }
}'

通过 OIDC 依赖方认证流程进行身份验证

当一个请求在请求头或 session cookie 中不包含访问令牌时，该插件可以充当 OIDC 依赖方并重定向到身份提供者的授权端点以通过 OIDC authorization code flow。

一旦用户通过身份提供者进行身份验证，插件将代表用户从身份提供者获取和管理访问令牌和更多信息。该信息当前存储在 session cookie 中，该插件将会识别 Cookie 并使用其中的信息，以避免再次执行认证流程。

以下示例是将此操作模式添加到 Route：

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
  "uri": "/get",
  "plugins": {
    "openid-connect": {
      "client_id": "${CLIENT_ID}",
      "client_secret": "${CLIENT_SECRET}",
      "discovery": "${DISCOVERY_ENDPOINT}",
      "bearer_only": false,
      "realm": "master"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:443": 1
    }
  }
}'

在以上示例中，该插件可以强制在配置的请求头中设置访问令牌、ID 令牌和 UserInfo 对象。

故障排除

本节介绍使用此插件时的一些常见问题，以帮助您排除故障。

APISIX 无法连接到 OpenID 提供商

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

No Session State Found

如果您在使用授权码流 时遇到 500 内部服务器错误并在日志中显示以下消息，则可能有多种原因。

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

1. 重定向 URI 配置错误

一个常见的错误配置是将 redirect_uri 配置为与路由的 URI 相同。当用户发起访问受保护资源的请求时，请求直接命中重定向 URI，且请求中没有 session cookie，从而导致 no session state found 错误。

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

您还应该确保 redirect_uri 包含 scheme，例如 http 或 https 。

2. 缺少 Session Secret

如果您在standalone 模式下部署 APISIX，请确保配置了 session.secret。

用户 session 作为 cookie 存储在浏览器中，并使用 session 密钥进行加密。如果没有通过 session.secret 属性配置机密，则会自动生成机密并将其保存到 etcd。然而，在独立模式下，etcd 不再是配置中心。因此，您应该在 YAML 配置中心 apisix.yaml 中为此插件显式配置 session.secret。

3. Cookie 未发送或不存在

检查 SameSite cookie 属性是否已正确设置（即您的应用程序是否需要跨站点发送 cookie），看看这是否会成为阻止 cookie 保存到浏览器的 cookie jar 或从浏览器发送的因素。

4. 上游发送的标头太大

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

upstream sent too big header while reading response header from upstream

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

5. 无效的客户端密钥

验证 client_secret 是否有效且正确。无效的 client_secret 将导致身份验证失败，并且不会返回任何令牌并将其存储在 session 中。