Skip to content
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

OpenID Connect

By Kong Inc.
You are browsing unreleased documentation.

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:

  1. Session Authentication
  2. JWT Access Token Authentication
  3. Kong OAuth Token Authentication
  4. Introspection Authentication
  5. User Info Authentication
  6. Refresh Token Grant
  7. Password Grant
  8. Client Credentials Grant
  9. 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:

  1. Claims based authorization
  2. ACL plugin authorization
  3. 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 kong.conf.

To set up RBAC in Kong Manager with OIDC, see:

More information