openid-connect

The openid-connect plugin supports the integration with OpenID Connect (OIDC) identity providers, such as Keycloak and Auth0. It allows APISIX to authenticate clients and obtain their information from the identity provider before allowing or denying their access to upstream protected resources.

Examples​

The plugin can be used to implement primarily authorization code flow and client credential flow with OpenID providers.

Authorization Code Flow​

The authorization code flow is defined in RFC 6749, Section 4.1. It involves exchanging an temporary authorization code for an access token, and is typically used by confidential and public clients.

The following diagram demonstrates the interaction between different entities when you implement this flow using the openid-connect plugin:

To implement authorization code flow with this plugin, set bearer_only to false, which is the default.

When an incoming request does not contain an access token in its header nor in an appropriate session cookie, the plugin acts as a relying party and redirects to the authorization server to continue the authorization code flow.

After successful authentication, the plugin keeps the token in the session cookie, and subsequent requests will use the token stored in the cookie.

See Authenticate With User Credentials for an example to use this plugin to integrate with Keycloak using the authorization code flow.

Client Credential Flow​

The client credential flow is defined in RFC 6749, Section 4.4. It involves clients requesting an access token with its own credentials to access protected resources, typically used in machine to machine authentication and is not on behalf of a specific user.

To implement authorization code flow with this plugin, set bearer_only to true and configure the introspection_endpoint or public_key attribute.

See Authenticate With Client Credentials for an example to use this plugin to integrate with Keycloak using client credentials flow.

Troubleshooting​

This section covers a few commonly seen issues when working with this plugin to help you troubleshoot.

APISIX Cannot Connect to OpenID provider​

If APISIX fails to resolve or cannot connect to the OpenID provider, double check the DNS settings in your configuration file config.yaml and modify as needed.

No Session State Found​

If you encounter a 500 internal server error with the following message in the log when working with authorization code flow, there could be a number of reasons.

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

1. Misconfigured Redirection URI​

A common misconfiguration is to configure the redirect_uri the same as the URI of the route. When a user initiates a request to visit the protected resource, the request directly hits the redirection URI with no session cookie in the request, which leads to the no session state found error.

To properly configure the redirection URI, make sure that the redirect_uri matches the route where the plugin is configured, without being fully identical. For instance, a correct configuration would be to configure uri of the route to /api/v1/* and the path portion of the redirect_uri to /api/v1/redirect.

You should also ensure that the redirect_uri include the scheme, such as http or https.

2. Missing Session Secret​

If you deploy APISIX in the standalone mode, make sure that session.secret is configured.

User sessions are stored in browser as cookies and encrypted with session secret. The secret is automatically generated and saved to etcd if no secret is configured through the session.secret attribute. However, in standalone mode, etcd is no longer the configuration center. Therefore, you should explicitly configure session.secret for this plugin in the YAML configuration center apisix.yaml.

3. Cookie Not Sent or Absent​

Check if the SameSite cookie attribute is properly set (i.e. if your application needs to send the cookie cross sites) to see if this could be a factor that prevents the cookie being saved to the browser's cookie jar or being sent from the browser.

4. Upstream Sent Too Big Header​

If you have NGINX sitting in front of APISIX to proxy client traffic, see if you observe the following error in NGINX's error.log:

upstream sent too big header while reading response header from upstream

If so, try adjusting proxy_buffers, proxy_buffer_size, and proxy_busy_buffers_size to larger values.

5. Invalid Client Secret​

Verify if client_secret is valid and correct. An invalid client_secret would lead to an authentication failure and no token shall be returned and stored in session.