You are browsing documentation for an outdated version. See the latest documentation here.
Third-party OAuth2 Support for Application Registration
Third-party OAuth2 support allows developers to centralize application
credentials management with the supported Identity Provider of their
choice. To use the external IdP feature, set the
configuration option to
external-oauth2 in the
kong.conf.default configuration file. For more information, see setting the
Authorization Provider Strategy.
The Kong OIDC and Portal Application Registration plugins are used in conjunction with each other on a Service:
The OIDC plugin handles all aspects of the OAuth2 handshake, including looking up the Consumer via custom claim (the
custom_idmatches the identity provider
The Application Registration plugin is responsible for checking the mapped Consumer and ensuring the Consumer has the correct ACL (Access Control List) permissions to access the Route.
Supported identity providers
The Kong OIDC plugin supports many identity providers out of the box. The following providers have been tested for the current version of the Kong Portal Application Registration plugin used in tandem with the Kong OIDC plugin:
- Okta. See the Okta setup example.
- Azure. See the Azure setup example.
- Ping Identity.
How you authenticate with a Service depends on its underlying OAuth2 implementation. For more information, reference the documentation below for your implemented identity provider and OAuth flow.
- Ping Identity
Supported OAuth flows
- Client Credentials (RFC 6742 Section 4.4)
- Authorization Code (RFC 6742 Section 4.1)
- Implicit Grant (RFC 6742 Section 4.2)
- Password Grant (RFC 6742 Section 4.3)
Password Grant and Implicit Grant flows are available but not recommended because they are less secure than the Authorization Code and Client Credentials flows.
Client Credentials Flow
The OIDC plugin makes authenticating using Client Credentials very
straightforward. This flow should be used for server-side and secure
machine-to-machine communication. The Client Credentials flow requires the
authorizing party to store and send the application’s
In this flow, a developer makes a request against the Service with the OIDC and Application
Registration plugins applied. This request should contain the
client_secret as a Basic Auth authentication header:
Authorization: Basic client_id:client_secret
client_id:client_secret should be base64-encoded.
The following sequence diagram illustrates the Client Credentials flow through the OIDC and Application Registration plugins. Click on the image to expand its view.
|a||Developer sends the Okta application’s
|b||Okta reads the
|c||Okta returns the access token to Kong.|
|d||The OIDC plugin reads the resulting access token and associates the request with the application via the
|e||If the resolved application has permission to consume the Service via its Portal Application Registration plugin, Kong forwards the request to the Upstream.|
Authorization Code Flow
Due to limitations of the OIDC plugin, a single plugin instance cannot handle
client_id's provisioned from multiple sources (applications).
To circumvent this issue, the IdP Issuer URL is exposed to developers on the
Dev Portal application show page when
show_issuer is enabled in the
Application Registration plugin. Developers can hit the Issuer URL directly to
provision an access token. After getting the access token, requests can be made
against the proxy.
Set up the application to secure an access token against the IdP directly. For more information about implementing the Authorization Code flow with Okta, refer to the Okta developer guide.
After the initial access token handshake has been completed, make subsequent requests to the Kong service using that access token as a bearer token. After the first successful request, the OIDC plugin will establish a session with the client so that the access token does not need to be continually passed with every request.
The following sequence diagram illustrates the Authorization Code flow through the OIDC and Application Registration plugins. Click on the image to expand its view.
|a||A developer copies the target Service’s
|b||Okta redirects the user to a login page.|
|c||The user inputs their Single Sign-On (SSO) information.|
|d||The user submits the SSO form that contains their Okta username and password.|
|e||Upon a successful login, the application is given an access token to make against calls for all subsequent requests.|
|f||The user makes a request to the protected Service and Route.|
|g||The OIDC plugin takes the access token and runs introspection, consulting the Okta authorization server if necessary. After the access token has been verified, the plugin matches the custom claim to find the associated application Consumer via its
|h||The request is passed to the Application Registration plugin, which checks to make sure the Consumer has the appropriate ACL (Access Control List) permissions.|
|i||The request is proxied to the Upstream.|
Implicit Grant Flow
The Implicit Grant flow is not recommended if the Authorization Code flow is possible.
Set up the application to secure an access token against the IdP directly. For more information about implementing the Implicit Grant flow with Okta, refer to the Okta developer guide.
After the access token handshake has been completed, make subsequent requests to the Kong service using that access token as a bearer token. After the first successful request, the OIDC plugin will establish a session with the client so that the access token does not need to be passed continuously.