kayx23 commented on code in PR #11889: URL: https://github.com/apache/apisix/pull/11889#discussion_r2048540750
########## docs/en/latest/plugins/openid-connect.md: ########## @@ -27,58 +27,62 @@ description: OpenID Connect allows the client to obtain user information from th # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/openid-connect"; /> +</head> + ## Description -[OpenID Connect](https://openid.net/connect/) (OIDC) is an authentication protocol based on the OAuth 2.0. It allows the client to obtain user information from the identity provider (IdP), e.g., Keycloak, Ory Hydra, Okta, Auth0, etc. API Gateway Apache APISIX supports to integrate with the above identity providers to protect your APIs. +The `openid-connect` Plugin supports the integration with [OpenID Connect (OIDC)](https://openid.net/connect/) identity providers, such as Keycloak, Auth0, Microsoft Entra ID, Google, Okta, and more. It allows APISIX to authenticate clients and obtain their information from the identity provider before allowing or denying their access to upstream protected resources. ## Attributes -| Name | Type | Required | Default | Valid values | Description | +| Name | Type | Required | Default | Valid values | Description | |--------------------------------------|----------|----------|-----------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| client_id | string | True | | | OAuth client ID. | -| client_secret | string | True | | | OAuth client secret. | -| discovery | string | True | | | Discovery endpoint URL of the identity server. | -| scope | string | False | "openid" | | OIDC scope that corresponds to information that should be returned about the authenticated user, also known as [claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). The default value is `openid`, the required scope for OIDC to return a `sub` claim that uniquely identifies the authenticated user. Additional scopes can be appended and delimited by spaces, such as `openid email profile`. | -| required_scopes | string[] | False | | | Array of strings. Used in conjunction with the introspection endpoint (when `bearer_only` is `true`). If present, the plugin will check if the token contains all required scopes. If not, 403 will be returned with an error message | -| realm | string | False | "apisix" | | Realm used for authentication. | -| claim_validator | object | False | | | Define the JWT claim validator. | -| claim_validator.audience | object | False | | | OpenID Connect Audience (["aud"](https://openid.net/specs/openid-connect-core-1_0.html)) validator. | -| claim_validator.audience.claim | string | False | "aud" | | Customize the claim used to store the audience. | -| claim_validator.audience.required | boolean | False | false | | Requires that the audience claim must exist and that it follows the custom claim. | -| claim_validator.audience.match_with_client_id | boolean | False | false | | Requires that the audience claim value must be equal to the client_id (when the value is a string) or contain the client_id (when the value is an array of strings), as required by the OpenID Connect specification. | -| bearer_only | boolean | False | false | | When set to `true`, APISIX will only check if the authorization header in the request matches a bearer token. | -| logout_path | string | False | "/logout" | | Path for logging out. | -| post_logout_redirect_uri | string | False | | | URL to redirect to after logging out. If the OIDC discovery endpoint does not provide an [`end_session_endpoint`](https://openid.net/specs/openid-connect-rpinitiated-1_0.html), the plugin internally redirects using the [`redirect_after_logout_uri`](https://github.com/zmartzone/lua-resty-openidc). Otherwise, it redirects using the [`post_logout_redirect_uri`](https://openid.net/specs/openid-connect-rpinitiated-1_0.html). | -| redirect_uri | string | False | | | URI to which the identity provider redirects back to. If not configured, APISIX will append the `.apisix/redirect` suffix to determine the default `redirect_uri`. Note that the provider should be properly configured to allow such `redirect_uri` values. | -| timeout | integer | False | 3 | [1,...] | Request timeout time in seconds. | -| ssl_verify | boolean | False | false | | When set to true, verifies the identity provider's SSL certificates. | -| introspection_endpoint | string | False | | | URL of the token verification endpoint of the identity server. | -| introspection_endpoint_auth_method | string | False | "client_secret_basic" | | Authentication method name for token introspection. | -| token_endpoint_auth_method | string | False | | | Authentication method name for token endpoint. The default will get the first supported method specified by the OP. | -| public_key | string | False | | | Public key to verify the token. | -| use_jwks | boolean | False | false | | When set to `true`, uses the JWKS endpoint of the identity server to verify the token. | -| use_pkce | boolean | False | false | | when set to `true`, the "Proof Key for Code Exchange" as defined in RFC 7636 will be used. | -| token_signing_alg_values_expected | string | False | | | Algorithm used for signing the authentication token. | -| set_access_token_header | boolean | False | true | | When set to true, sets the access token in a request header. By default, the `X-Access-Token` header is used. | -| access_token_in_authorization_header | boolean | False | false | | When set to true and `set_access_token_header` is also true, sets the access token in the `Authorization` header. | -| set_id_token_header | boolean | False | true | | When set to true and the ID token is available, sets the ID token in the `X-ID-Token` request header. | -| set_userinfo_header | boolean | False | true | | When set to true and the UserInfo object is available, sets it in the `X-Userinfo` request header. | -| set_refresh_token_header | boolean | False | false | | When set to true and a refresh token object is available, sets it in the `X-Refresh-Token` request header. | -| session | object | False | | | When bearer_only is set to false, openid-connect will use Authorization Code flow to authenticate on the IDP, so you need to set the session-related configuration. | -| session.secret | string | True | Automatic generation | 16 or more characters | The key used for session encrypt and HMAC operation. | -| session.cookie | object | False | | | | +| client_id | string | True | | | OAuth client ID. | +| client_secret | string | True | | | OAuth client secret. | +| discovery | string | True | | | URL to the well-known discovery document of the OpenID provider, which contains a list of OP API endpoints. The Plugin can directly utilize the endpoints from the discovery document. You can also configure these endpoints individually, which takes precedence over the endpoints supplied in the discovery document. | +| scope | string | False | openid | | OIDC scope that corresponds to information that should be returned about the authenticated user, also known as [claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This is used to authorize users with proper permission. The default value is `openid`, the required scope for OIDC to return a `sub` claim that uniquely identifies the authenticated user. Additional scopes can be appended and delimited by spaces, such as `openid email profile`. | +| required_scopes | array[string] | False | | | Scopes required to be present in the access token. Used in conjunction with the introspection endpoint when `bearer_only` is `true`. If any required scope is missing, the Plugin rejects the request with a 403 forbidden error. | +| realm | string | False | apisix | | Realm in [`WWW-Authenticate`](https://www.rfc-editor.org/rfc/rfc6750#section-3) response header accompanying a 401 unauthorized request due to invalid bearer token. | +| bearer_only | boolean | False | false | | If true, strictly require bearer access token in requests for authentication. | +| logout_path | string | False | /logout | | Path to activate the logout. | +| post_logout_redirect_uri | string | False | | | URL to redirect users to after the `logout_path` receive a request to log out. | +| redirect_uri | string | False | | | URI to redirect to after authentication with the OpenID provider. Note that the redirect URI should not be the same as the request URI, but a sub-path of the request URI. For example, if the `uri` of the Route is `/api/v1/*`, `redirect_uri` can be configured as `/api/v1/redirect`. If `redirect_uri` is not configured, APISIX will append `/.apisix/redirect` to the request URI to determine the value for `redirect_uri`. | +| timeout | integer | False | 3 | [1,...] | Request timeout time in seconds. | +| ssl_verify | boolean | False | false | | If true, verify the OpenID provider 's SSL certificates. | +| introspection_endpoint | string | False | | | URL of the [token introspection](https://datatracker.ietf.org/doc/html/rfc7662) endpoint for the OpenID provider used to introspect access tokens. If this is unset, the introspection endpoint presented in the well-known discovery document is used [as a fallback](https://github.com/zmartzone/lua-resty-openidc/commit/cdaf824996d2b499de4c72852c91733872137c9c). | +| introspection_endpoint_auth_method | string | False | client_secret_basic | | Authentication method for the token introspection endpoint. The value should be one of the authentication methods specified in the `introspection_endpoint_auth_methods_supported` [authorization server metadata](https://www.rfc-editor.org/rfc/rfc8414.html) as seen in the well-known discovery document, such as `client_secret_basic`, `client_secret_post`, `private_key_jwt`, and `client_secret_jwt`. | +| token_endpoint_auth_method | string | False | client_secret_basic | | Authentication method for the token endpoint. The value should be one of the authentication methods specified in the `token_endpoint_auth_methods_supported` [authorization server metadata](https://www.rfc-editor.org/rfc/rfc8414.html) as seen in the well-known discovery document, such as `client_secret_basic`, `client_secret_post`, `private_key_jwt`, and `client_secret_jwt`. If the configured method is not supported, fall back to the first method in the `token_endpoint_auth_methods_supported` array. | +| public_key | string | False | | | Public key used to verify JWT signature id asymmetric algorithm is used. Providing this value to perform token verification will skip token introspection in client credentials flow. You can pass the public key in `-----BEGIN PUBLIC KEY-----\\n……\\n-----END PUBLIC KEY-----` format. | +| use_jwks | boolean | False | false | | If true and if `public_key` is not set, use the JWKS to verify JWT signature and skip token introspection in client credentials flow. The JWKS endpoint is parsed from the discovery document. | +| use_pkce | boolean | False | false | | If true, use the Proof Key for Code Exchange (PKCE) for Authorization Code Flow as defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636). | +| token_signing_alg_values_expected | string | False | | | Algorithm used for signing JWT, such as `RS256`. | +| set_access_token_header | boolean | False | true | | If true, set the access token in a request header. By default, the `X-Access-Token` header is used. | +| access_token_in_authorization_header | boolean | False | false | | If true and if `set_access_token_header` is also true, set the access token in the `Authorization` header. | +| set_id_token_header | boolean | False | true | | If true and if the ID token is available, set the value in the `X-ID-Token` request header. | +| set_userinfo_header | boolean | False | true | | If true and if user info data is available, set the value in the `X-Userinfo` request header. | +| set_refresh_token_header | boolean | False | false | | If true and if the refresh token is available, set the value in the `X-Refresh-Token` request header. | +| session | object | False | | | Session configuration used when `bearer_only` is `false` and the Plugin uses Authorization Code flow. | +| session.secret | string | True | | 16 or more characters | Key used for session encryption and HMAC operation when `bearer_only` is `false`. It is automatically generated and saved to etcd if not configured. When using APISIX in the standalone mode where etcd is no longer the configuration center, the `secret` should be configured. | +| session.cookie | object | False | | | Cookie configurations. | | session.cookie.lifetime | integer | False | 3600 | | Cookie lifetime in seconds. | -| unauth_action | string | False | "auth" | ["auth","deny","pass"] | Specify the response type on unauthenticated requests. "auth" redirects to identity provider, "deny" results in a 401 response, "pass" will allow the request without authentication. | -| proxy_opts | object | False | | | HTTP proxy that the OpenID provider is behind. | -| proxy_opts.http_proxy | string | False | | http://proxy-server:port | HTTP proxy server address. | -| proxy_opts.https_proxy | string | False | | http://proxy-server:port | HTTPS proxy server address. | -| proxy_opts.http_proxy_authorization | string | False | | Basic [base64 username:password] | Default `Proxy-Authorization` header value to be used with `http_proxy`. Can be overridden with custom `Proxy-Authorization` request header. | -| proxy_opts.https_proxy_authorization | string | False | | Basic [base64 username:password] | Default `Proxy-Authorization` header value to be used with `https_proxy`. Cannot be overridden with custom `Proxy-Authorization` request header since with with HTTPS the authorization is completed when connecting. | -| proxy_opts.no_proxy | string | False | | | Comma separated list of hosts that should not be proxied. | -| authorization_params | object | False | | | Additional parameters to send in the request to the authorization endpoint. | -| client_rsa_private_key | string | False | | | Client RSA private key used to sign JWT. | -| client_rsa_private_key_id | string | False | | | Client RSA private key ID used to compute a signed JWT. | -| client_jwt_assertion_expires_in | integer | False | 60 | | Life duration of the signed JWT in seconds. | +| session_contents | object | False | | | Session content configurations. If unconfigured, all data will be stored in the session. | Review Comment: About this `session_contents` update from https://github.com/apache/apisix/pull/11892 @bzp2010 I think we should update the plugin schema as well. Could you help confirm updating the schema & associated tests are sufficient? Should these changes be done in this PR or open a new one? Thanks. -- 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: notifications-unsubscr...@apisix.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
