Yilialinn commented on code in PR #13247: URL: https://github.com/apache/apisix/pull/13247#discussion_r3109455559
########## docs/zh/latest/plugins/openid-connect.md: ########## @@ -31,251 +31,411 @@ description: openid-connect 插件支持与 OpenID Connect (OIDC) 身份提供 <link rel="canonical" href="https://docs.api7.ai/hub/openid-connect"; /> </head> +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 描述 -`openid-connect` 插件支持与 [OpenID Connect (OIDC)](https://openid.net/connect/) 身份提供商集成，例如 Keycloak、Auth0、Microsoft Entra ID、Google、Okta 等。它允许 APISIX 对客户端进行身份验证，并从身份提供商处获取其信息，然后允许或拒绝其访问上游受保护资源。 +`openid-connect` 插件支持与 [OpenID Connect (OIDC)](https://openid.net/connect/) 身份提供商集成，例如 Keycloak、Auth0、Microsoft Entra ID、Google、Okta 等。它允许 APISIX 在允许或拒绝客户端访问受保护的上游资源之前，先对客户端进行身份验证并从身份提供商获取相关信息。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ------------------------------------ | ------- | ------ | --------------------- | ------------- | ------------------------------------------------------------------------------------------------ | -| client_id | string | 是 | | | OAuth 客户端 ID。 | -| client_secret | string | 是 | | | OAuth 客户端 secret。 | -| discovery | string | 是 | | | OpenID 提供商的知名发现文档的 URL，其中包含 OP API 端点列表。插件可以直接利用发现文档中的端点。您也可以单独配置这些端点，这优先于发现文档中提供的端点。 | -| scope | string | 否 | openid | | 与应返回的有关经过身份验证的用户的信息相对应的 OIDC 范围，也称为 [claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)。这用于向用户授权适当的权限。默认值为 `openid`，这是 OIDC 返回唯一标识经过身份验证的用户的 `sub` 声明所需的范围。可以附加其他范围并用空格分隔，例如 `openid email profile`。 | -| required_scopes | array[string] | 否 | | | 访问令牌中必须存在的范围。当 `bearer_only` 为 `true` 时与自省端点结合使用。如果缺少任何必需的范围，插件将以 403 禁止错误拒绝请求。| -| realm | string | 否 | apisix | | 由于持有者令牌无效，[`WWW-Authenticate`](https://www.rfc-editor.org/rfc/rfc6750#section-3) 响应标头中的领域伴随 401 未经授权的请求。 | -| bearer_only | boolean | 否 | false | | 如果为 true，则严格要求在身份验证请求中使用持有者访问令牌。 | -| logout_path | string | 否 | /logout | | 激活注销的路径。 | -| post_logout_redirect_uri | string | 否 | | | `logout_path` 收到注销请求后将用户重定向到的 URL。| -| redirect_uri | string | 否 | | | 通过 OpenID 提供商进行身份验证后重定向到的 URI。请注意，重定向 URI 不应与请求 URI 相同，而应为请求 URI 的子路径。例如，如果路由的 `uri` 是 `/api/v1/*`，则 `redirect_uri` 可以配置为 `/api/v1/redirect`。如果未配置 `redirect_uri`，APISIX 将在请求 URI 后附加 `/.apisix/redirect` 以确定 `redirect_uri` 的值。| -| timeout | integer | 否 | 3 | [1,...] | 请求超时时间（秒）。| -| ssl_verify | boolean | 否 | true | | 如果为 true，则验证 OpenID 提供商的 SSL 证书。| -| introspection_endpoint | string | 否 | | |用于自检访问令牌的 OpenID 提供程序的 [令牌自检](https://datatracker.ietf.org/doc/html/rfc7662) 端点的 URL。如果未设置，则将使用众所周知的发现文档中提供的自检端点[作为后备](https://github.com/zmartzone/lua-resty-openidc/commit/cdaf824996d2b499de4c72852c91733872137c9c)。| -| introspection_endpoint_auth_method | string | 否 | client_secret_basic | | 令牌自检端点的身份验证方法。该值应为 `introspection_endpoint_auth_methods_supported` [授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414.html) 中指定的身份验证方法之一，如众所周知的发现文档中所示，例如 `client_secret_basic`、`client_secret_post`、`private_key_jwt` 和 `client_secret_jwt`。| -| token_endpoint_auth_method | string | 否 | client_secret_basic | | 令牌端点的身份验证方法。该值应为 `token_endpoint_auth_methods_supported` [授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414.html) 中指定的身份验证方法之一，如众所周知的发现文档中所示，例如 `client_secret_basic`、`client_secret_post`、`private_key_jwt` 和 `client_secret_jwt`。如果配置的方法不受支持，则回退到 `token_endpoint_auth_methods_supported` 数组中的第一个方法。| -| public_key | string | 否 | | | 用于验证 JWT 签名 id 的公钥使用非对称算法。提供此值来执行令牌验证将跳过客户端凭据流中的令牌自检。您可以以 `-----BEGIN PUBLIC KEY-----\\n……\\n-----END PUBLIC KEY-----` 格式传递公钥。| -| use_jwks | boolean | 否 | false | | 如果为 true 并且未设置 `public_key`，则使用 JWKS 验证 JWT 签名并跳过客户端凭据流中的令牌自检。JWKS 端点是从发现文档中解析出来的。| -| use_pkce | boolean | 否 | false | | 如果为 true，则使用 [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) 中定义的授权码流的代码交换证明密钥 (PKCE)。| +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------|------|--------|--------|--------|------| +| client_id | string | 是 | | | OAuth 客户端 ID。 | +| client_secret | string | 是 | | | OAuth 客户端密钥。 | +| discovery | string | 是 | | | OpenID 提供商的 well-known 发现文档 URL，包含 OP API 端点列表。插件可直接使用发现文档中的端点。您也可以单独配置这些端点，单独配置的值优先于发现文档中提供的端点。 | +| scope | string | 否 | openid | | 与认证用户相关信息对应的 OIDC 范围，也称为 [claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)。用于授权具有适当权限的用户。默认值为 `openid`，这是 OIDC 返回唯一标识认证用户的 `sub` claim 所需的范围。可以附加额外的范围并以空格分隔，例如 `openid email profile`。 | +| required_scopes | array[string] | 否 | | | 访问令牌中必须存在的范围。在 `bearer_only` 为 `true` 时与 introspection 端点结合使用。如果缺少任何必需范围，插件将以 403 forbidden 错误拒绝请求。 | +| realm | string | 否 | apisix | | 由于无效 bearer token 导致 401 未授权请求时，[`WWW-Authenticate`](https://www.rfc-editor.org/rfc/rfc6750#section-3) 响应头中的 Realm 值。 | +| bearer_only | boolean | 否 | false | | 如果为 true，则严格要求请求中携带 bearer 访问令牌进行身份验证。 | +| logout_path | string | 否 | /logout | | 触发注销的路径。 | +| post_logout_redirect_uri | string | 否 | | | `logout_path` 收到注销请求后重定向用户的 URL。 | +| redirect_uri | string | 否 | | | 与 OpenID 提供商完成身份验证后的重定向 URI。注意，重定向 URI 不应与请求 URI 相同，而应为请求 URI 的子路径。例如，如果路由的 `uri` 为 `/api/v1/*`，则 `redirect_uri` 可配置为 `/api/v1/redirect`。如果未配置 `redirect_uri`，APISIX 将在请求 URI 后追加 `/.apisix/redirect` 作为 `redirect_uri` 的值。 | +| timeout | integer | 否 | 3 | [1,...] | 请求超时时间，单位为秒。 | +| ssl_verify | boolean | 否 | true | | 如果为 true，则验证 OpenID 提供商的 SSL 证书。注意：该属性的默认值在 APISIX 3.16.0 中从 `false` 更改为 `true`，这是一个破坏性变更。如果您从早期版本升级，请确保您的 OpenID 提供商 SSL 证书有效，或显式将其设置为 `false` 以保持之前的行为。 | +| introspection_endpoint | string | 否 | | | OpenID 提供商用于内省访问令牌的[令牌内省](https://datatracker.ietf.org/doc/html/rfc7662)端点 URL。如果未设置，则使用 well-known 发现文档中提供的内省端点作为[备选项](https://github.com/zmartzone/lua-resty-openidc/commit/cdaf824996d2b499de4c72852c91733872137c9c)。 | +| introspection_endpoint_auth_method | string | 否 | client_secret_basic | | 令牌内省端点的认证方法。值应为 well-known 发现文档中 `introspection_endpoint_auth_methods_supported` [授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414.html)指定的认证方法之一，例如 `client_secret_basic`、`client_secret_post`、`private_key_jwt` 和 `client_secret_jwt`。 | +| token_endpoint_auth_method | string | 否 | client_secret_basic | | 令牌端点的认证方法。值应为 well-known 发现文档中 `token_endpoint_auth_methods_supported` [授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414.html)指定的认证方法之一，例如 `client_secret_basic`、`client_secret_post`、`private_key_jwt` 和 `client_secret_jwt`。如果配置的方法不受支持，则回退到 `token_endpoint_auth_methods_supported` 数组中的第一个方法。 | +| public_key | string | 否 | | | 使用非对称算法时用于验证 JWT 签名的公钥。提供此值进行令牌验证将跳过客户端凭证流中的令牌内省。可以以 `-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----` 格式传递公钥。 | +| use_jwks | boolean | 否 | false | | 如果为 true 且未设置 `public_key`，则使用 JWKS 验证 JWT 签名并跳过客户端凭证流中的令牌内省。JWKS 端点从发现文档中解析。 | +| use_pkce | boolean | 否 | false | | 如果为 true，则按照 [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) 定义，在授权码流程中使用 PKCE（Proof Key for Code Exchange）。 | | token_signing_alg_values_expected | string | 否 | | | 用于签署 JWT 的算法，例如 `RS256`。 | -| set_access_token_header | boolean | 否 | true | | 如果为 true，则在请求标头中设置访问令牌。默认情况下，使用 `X-Access-Token` 标头。| -| access_token_in_authorization_header | boolean | 否 | false | | 如果为 true 并且 `set_access_token_header` 也为 true，则在 `Authorization` 标头中设置访问令牌。 | -| set_id_token_header | boolean | 否 | true | | 如果为 true 并且 ID 令牌可用，则在 `X-ID-Token` 请求标头中设置值。 | -| set_userinfo_header | boolean | 否 | true | | 如果为 true 并且用户信息数据可用，则在 `X-Userinfo` 请求标头中设置值。 | -| set_refresh_token_header | boolean | 否 | false | | 如果为 true 并且刷新令牌可用，则在 `X-Refresh-Token` 请求标头中设置值。 | -| session | object | 否 | | | 当 `bearer_only` 为 `false` 且插件使用 Authorization Code 流程时使用的 Session 配置。 | -| session.secret | string | 是 | | 16 个字符以上 | 当 `bearer_only` 为 `false` 时，用于 session 加密和 HMAC 运算的密钥。| +| set_access_token_header | boolean | 否 | true | | 如果为 true，则在请求头中设置访问令牌。默认使用 `X-Access-Token` 头。 | +| access_token_in_authorization_header | boolean | 否 | false | | 如果为 true 且 `set_access_token_header` 也为 true，则在 `Authorization` 头中设置访问令牌。 | +| set_id_token_header | boolean | 否 | true | | 如果为 true 且 ID 令牌可用，则在 `X-ID-Token` 请求头中设置其值。 | +| set_userinfo_header | boolean | 否 | true | | 如果为 true 且用户信息数据可用，则在 `X-Userinfo` 请求头中设置其值。 | +| set_refresh_token_header | boolean | 否 | false | | 如果为 true 且刷新令牌可用，则在 `X-Refresh-Token` 请求头中设置其值。 | +| session | object | 否 | | | 当 `bearer_only` 为 `false` 且插件使用授权码流程时的会话配置。 | +| session.secret | string | 是 | | 16 个或更多字符 | `bearer_only` 为 `false` 时用于会话加密和 HMAC 操作的密钥。 | | session.cookie | object | 否 | | | Cookie 配置。 | -| session.cookie.lifetime | integer | 否 | 3600 | | Cookie 生存时间（秒）。| +| session.cookie.lifetime | integer | 否 | 3600 | | Cookie 生命周期，单位为秒。 | | session.storage | string | 否 | cookie | ["cookie", "redis"] | 会话存储方式。 | -| session.redis | object | 否 | | | 当 `storage` 为 `redis` 时的 Redis 配置。 | -| session.redis.host | string | 否 | 127.0.0.1 | | Redis 主机地址。 | +| session.redis | object | 否 | | | `storage` 为 `redis` 时的 Redis 配置。 | +| session.redis.host | string | 否 | 127.0.0.1 | | Redis 主机。 | | session.redis.port | integer | 否 | 6379 | | Redis 端口。 | -| session.redis.password | string | 否 | | | Redis 密码。 | | session.redis.username | string | 否 | | | Redis 用户名。 | +| session.redis.password | string | 否 | | | Redis 密码。 | | session.redis.database | integer | 否 | 0 | | Redis 数据库索引。 | | session.redis.prefix | string | 否 | sessions | | Redis 键前缀。 | -| session.redis.ssl | boolean | 否 | false | | 启用 Redis SSL 连接。 | -| session.redis.ssl_verify | boolean | 否 | true | | 验证 SSL 证书。 | -| session.redis.server_name | string | 否 | | | Redis SNI 服务器名称。 | -| session.redis.connect_timeout | integer | 否 | 1000 | | 连接超时时间（毫秒）。 | -| session.redis.send_timeout | integer | 否 | 1000 | | 发送超时时间（毫秒）。 | -| session.redis.read_timeout | integer | 否 | 1000 | | 读取超时时间（毫秒）。 | -| session.redis.keepalive_timeout | integer | 否 | 10000 | | Keepalive 超时时间（毫秒）。 | -| unauth_action | string | 否 | auth | ["auth","deny","pass"] | 未经身份验证的请求的操作。设置为 `auth` 时，重定向到 OpenID 提供程序的身份验证端点。设置为 `pass` 时，允许请求而无需身份验证。设置为 `deny` 时，返回 401 未经身份验证的响应，而不是启动授权代码授予流程。| -| session_contents | object | 否 | | | 会话内容配置。如果未配置，将把所有数据存储在会话中。 | -| session_contents.access_token | boolean | 否 | | | 若为 true，则将访问令牌存储在会话中。 | -| session_contents.id_token | boolean | 否 | | | 若为 true，则将 ID 令牌存储在会话中。 | -| session_contents.enc_id_token | boolean | 否 | | | 若为 true，则将加密的 ID 令牌存储在会话中。 | -| session_contents.user | boolean | 否 | | | 若为 true，则将用户信息存储在会话中。 | -| proxy_opts | object | 否 | | | OpenID 提供程序背后的代理服务器的配置。| -| proxy_opts.http_proxy | string | 否 | | | HTTP 请求的代理服务器地址，例如 `http://<proxy_host>:<proxy_port>`。| +| session.redis.ssl | boolean | 否 | false | | 为 Redis 连接启用 SSL。 | +| session.redis.ssl_verify | boolean | 是 | false | | 验证 Redis 连接的 SSL 证书。 | Review Comment: https://github.com/apache/apisix/blob/3072a5e5cf9d6f66e600393375fdd2248d8f9acd/apisix/plugins/openid-connect.lua#L48 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
