openid-connect

    The openid-connect Plugin offers three modes of operation:

    1. The Plugin can be configured to authenticate requests without a valid token against an identity provider through OIDC authorization. The Plugin then acts as an OIDC Relying Party. In such cases, after successful authentication, the Plugin obtains and manages an access token in a session cookie. Subsequent requests that contain the cookie will use the access token. This requires the bearer_only attribute to be set to false. This mode of operation can be used to support cases where the client or the requester is a human interacting through a web browser.

    2. The Plugin can also be configured to support both the scenarios by setting to false and also configuring either the introspection_endpoint or public_key attribute. In such cases, introspection of an existing token from a request header takes precedence over the Relying Party flow. That is, if a request contains an invalid token, it will be rejected without redirecting to the ID provider to obtain a valid token.

    The method used to authenticate a request also affects the headers that can be enforced on the request before sending it to an Upstream service. You can learn more about this on the sections below.

    Token introspection validates a request by verifying the token with an OAuth 2 authorization server.

    The image below shows an example token introspection flow via a Gateway:

    The example below shows how you can enable the Plugin on Route. The Rouet below will protect the Upstream by introspecting the token provided in the request header:

    Now, to access the Route:

    In this example, the Plugin enforces that the access token and the Userinfo object be set in the request headers.

    When the OAuth 2 authorization server returns an expire time with the token, it is cached in APISIX until expiry. For more details, read:

    1. lua-resty-openidc‘s documentation and source code.

    The example below shows how you can add public key introspection to a Route:

    In this example, the Plugin can only enforce that the access token should be set in the request headers.

    When an incoming request does not contain an access token in its header nor in an appropriate session cookie, the Plugin can act as an OIDC Relying Party and redirect to the authorization endpoint of the identity provider to go through the .

    Once the user has authenticated with the identity provider, the Plugin will obtain and manage the access token and further interaction with the identity provider. The access token will be stored in a session cookie.

    The example below adds the Plugin with this mode of operation to the Route:

    In this example, the Plugin can enforce that the access token, the ID token, and the UserInfo object to be set in the request headers.