openid-connect

The openid-connect plugin supports the integration with OpenID Connect (OIDC) 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.

Examples​

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 illustrates the interaction between different entities when you implement the authorization code flow:

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 Implement Authorization Code Grant for an example to use the openid-connect plugin to integrate with Keycloak using the authorization code flow.

Proof Key for Code Exchange (PKCE)​

The Proof Key for Code Exchange (PKCE) is defined in RFC 7636. PKCE enhances the authorization code flow by adding a code challenge and verifier to prevent authorization code interception attacks.

The following diagram illustrates the interaction between different entities when you implement the authorization code flow with PKCE:

See Implement Authorization Code Grant for an example to use the openid-connect plugin to integrate with Keycloak using the authorization code flow with PKCE.

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.

The following diagram illustrates the interaction between different entities when you implement the client credential flow:

See Implement Client Credentials Grant for an example to use the openid-connect plugin to integrate with Keycloak using the client credentials flow.

Introspection Flow​

The introspection flow is defined in RFC 7662. It involves verifying the validity and details of an access token by querying an authorization server’s introspection endpoint.

In this flow, when a client presents an access token to the resource server, the resource server sends a request to the authorization server’s introspection endpoint, which responds with token details if the token is active, including information like token expiration, associated scopes, and the user or client it belongs to.

The following diagram illustrates the interaction between different entities when you implement the authorization code flow with token introspection:

See Implement Client Credentials Grant for an example to use the openid-connect plugin to integrate with Keycloak using the client credentials flow with token introspection.

Password Flow​

The password flow is defined in RFC 6749, Section 4.3. It is designed for trusted applications, allowing them to obtain an access token directly using a user’s username and password. In this grant type, the client app sends the user’s credentials along with its own client ID and secret to the authorization server, which then authenticates the user and, if valid, issues an access token.

Though efficient, this flow is intended for highly trusted, first-party applications only, as it requires the app to handle sensitive user credentials directly, posing significant security risks if used in third-party contexts.

The following diagram illustrates the interaction between different entities when you implement the password flow:

See Implement Password Grant for an example to use the openid-connect plugin to integrate with Keycloak using the password flow.

Refresh Token Grant​

The refresh token grant is defined in RFC 6749, Section 6. It enables clients to request a new access token without requiring the user to re-authenticate, using a previously issued refresh token. This flow is typically used when an access token expires, allowing the client to maintain continuous access to resources without user intervention. Refresh tokens are issued along with access tokens in certain OAuth flows and their lifespan and security requirements depend on the authorization server’s configuration.

The following diagram illustrates the interaction between different entities when implementing password flow with refresh token flow:

See Refresh Token for an example to use the openid-connect plugin to integrate with Keycloak using the password flow with token refreshes.

User Info​

The UserInfo endpoint in OpenID Connect (OIDC) is defined in OpenID Connect Core 1.0, Section 5.3. It enables clients to retrieve additional claims about an authenticated user by presenting a valid access token. This endpoint is particularly useful for obtaining user profile information, such as name, email, and other attributes, after the user has been authenticated. The data returned by the UserInfo endpoint depends on the scope of the access token and the claims configured by the authorization server.

The following diagram illustrates the interaction between different entities when APISIX verifies the user info:

See Control Access by Examining User Information from External Identity Provider for an example to use the openid-connect plugin to integrate with Keycloak, and implement access control with the Enterprise acl plugin based on the user info.

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.

6. PKCE IdP Configuration​

If you are enabling PKCE with the authorization code flow, make sure you have configured the IdP client to use PKCE. For example, in Keycloak, you should configure the PKCE challenge method in the client's advanced settings: