You are browsing documentation for an outdated plugin version.
Looking for the plugin's configuration parameters? You can find them in the OpenID Connect configuration reference doc.
The OpenID Connect (1.0) plugin (also known as OIDC) allows for integration with a third party identity provider (IdP) in a standardized way. This plugin can be used to implement Kong as a (proxying) OAuth 2.0 resource server (RS) and/or as an OpenID Connect relying party (RP) between the client and the upstream service.
The plugin supports several types of credentials and grants, and has been tested with several OpenID Connect providers. Review the support reference to see all of them.
About OpenID Connect
What does OpenID Connect do?
OpenID Connect provides a way to form a federation with identity providers (IdPs). Identity providers are third parties that store account credentials. If the identity provider authenticates a user, the application trusts that provider and allows access to the user. The identity provider bears some responsibility for protecting the user’s credentials and ensuring authenticity, so applications no longer need to on their own.
Besides delegating responsibility to an identity provider, OpenID Connect also makes single sign-on possible without storing any credentials on a user’s local machine.
Finally, enterprises may want to manage access control for many applications from one central system of record. For example, they may want employees to be able to access many different applications using their email address and password. They may want to also change access (for example, if an employee leaves or changes roles) from one central point. OpenID Connect addresses this challenge by providing a way for many different applications to authenticate users through the same third-party identity provider.
What does Kong’s OpenID Connect plugin do?
Just as OpenID Connect enables developers to offload authentication to another party, Kong enables developers to separate entire processes from their applications. Rather than needing to hand write the code for OpenID Connect within a service, developers can place Kong in front of the service and have Kong handle authentication. This separation allows developers to focus on the business logic within their application. It also allows them to easily swap out services while preserving authentication at the front door, and to effortlessly spread the same authentication to new services.
Kong users may prefer OpenID Connect to other authentication types, such as Key Auth and Basic Auth, because they will not need to manage the database storing passwords. Instead, they can offload the task to a trusted identity provider of their choice.
While the OpenID Connect plugin can suit many different use cases and extends to other plugins such as JWT (JSON Web Token) and 0Auth 2.0, the most common use case is the authorization code flow.
How-to guides and demos
The following examples are built with simplicity in mind, and are not meant for a production environment. Because
httpbin.konghq.com
is the upstream service in these examples, we highly recommended that you do not run these examples with a production identity provider as there is a high chance of leaking information. The examples also use the plain HTTP protocol, which you should never use in production.
We recommend reviewing the important configuration parameters before implementing any flows or grants.
Authentication flows and grants
We use HTTPie to execute the examples. The output is stripped for better readability. httpbin.konghq.com is used as an upstream service.
Using the Admin API is convenient when testing the plugin, but you can set up similar configs in declarative format as well.
When this plugin is configured with multiple grants/flows, there is a hardcoded search order for the credentials:
- Session Authentication
- JWT Access Token Authentication
- Kong OAuth Token Authentication
- Introspection Authentication
- User Info Authentication
- Refresh Token Grant
- Password Grant
- Client Credentials Grant
- Authorization Code Flow
Once credentials are found, the plugin will stop searching further. Multiple grants may
share the same credentials. For example, both the password and client credentials grants can use
basic access authentication through the Authorization
header.
Authorization
The OpenID Connect plugin has several features to do coarse grained authorization:
OIDC authentication in Kong Manager
Kong Gateway can use OpenID Connect to secure Kong Manager. It offers the ability to bind authentication for Kong Manager admins to an organization’s OpenID Connect Identity Provider, using the OpenID Connect plugin in the background.
You don’t need to set up the plugin directly.
Instead, Kong Gateway accesses the OIDC plugin through settings in kong.conf
.
To set up RBAC in Kong Manager with OIDC, see:
OIDC authentication in Dev Portal
The OpenID Connect plugin allows the Kong Dev Portal to hook into existing authentication setups using third-party identity providers such as Google, Okta, Microsoft Azure AD, Curity, and so on.
OIDC must be used with the session
method, utilizing cookies for Dev Portal File API requests.
You don’t need to set up the plugin directly.
Instead, Kong Gateway accesses the OIDC plugin through settings in kong.conf
, or from Konnect.
Konnect:
Self-managed Kong Gateway:
Application registration
You can also use OIDC for application registration in Dev Portal.
Application registration in Konnect:
- Configure Auth0 for Dynamic Client Registration
- Configure Curity for Dynamic Client Registration
- Configure Okta for Dynamic Client Registration
Application registration in self-managed Kong Gateway:
- Application Registration plugin
- Third-party OAuth2 Support for Application Registration
- External Portal Application Authentication with Azure AD and OIDC
- Set Up External Portal Application Authentication with Okta and OIDC