Did you know that you can try this plugin without talking to anyone for just $10/month with Kong Konnect? Get started in under 5 minutes.
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.
httpbin.org 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.org 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
The OpenID Connect plugin has several features to do coarse grained authorization:
- Claims based authorization
- ACL plugin authorization
- Consumer 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
To set up RBAC in Kong Manager with OIDC, see: