You are browsing documentation for an outdated version of Kong. Go here
to browse the documentation for the latest version.
Table of Contents
This guide covers an example OpenID Connect plugin configuration
to authenticate browser clients using Google's identity provider.
Because OpenID Connect deals with user credentials, all
transactions should take place over HTTPS. Although user passwords
for third party identity providers are only submitted to those
providers and not Kong, authentication tokens do grant access to a
subset of user account data and protected APIs, and should be secured.
As such, you should make Kong's proxy available via a fully-qualified
domain name and
add a certificate
If you have not yet
added a **Service**,
go ahead and do so. Again, note that you should be able to secure
this API with HTTPS, so if you are configuring a host, use a
hostname you have a certificate for.
Google IDP Configuration
Before configuring Kong, you’ll need to set up a Google APIs project and create a credential set. Following Google’s instructions, create a new set of OAuth client ID credentials with the Web application class. Add an authorized redirect URI for part of the API you wish to protect (more complex applications may redirect to a resource that sets additional
You can optionally customize the consent screen to inform clients who/what application is requesting authentication, but this is not required for testing. All steps after can be ignored, as Kong handles the server-side authentication request and token validation.
Basic Plugin Configuration
Add a plugin with the configuration below to your API using an HTTP client or Kong Manager. Make sure to use the same redirect URI as configured earlier:
$ curl -i -X POST http://kong:8001/apis/example/plugins --data name="openid-connect" \
--data config.issuer="https://accounts.google.com/.well-known/openid-configuration" \
--data config.client_id="YOUR_CLIENT_ID" \
--data config.client_secret="YOUR_CLIENT_SECRET" \
--data config.redirect_uri="https://example.com/api" \
Visiting a URL matched by that API in a browser will now redirect to Google’s authentication site and return you to the redirect URI after authenticating. You’ll note, however, that we did not configure anything to map authentication to consumers and that no consumer is associated with the subsequent request. Indeed, if you have configured other plugins that rely on consumer information, such as the ACL plugin, you will not have access. At present, the plugin configuration confirms that
users have a Google account, but doesn’t do anything with that information.
Depending on your needs, it may not be necessary to associate clients with a consumer. You can, for example, configure the
domains parameter to limit access to a internal users if you have a G Suite hosted domain, or configure
upstream_headers_claims to send information about the user upstream (e.g. their email, a profile picture, their name, etc.) for use in your applications or for analytics.
If you need to interact with other Kong plugins using consumer information, you must add configuration that maps account data received from the identity provider to a Kong consumer. For this example, we’ll map the user’s Google account email by setting a
custom_id on their consumer, e.g.
$ curl -i -X POST http://kong:8001/consumers/ \
--data username="Yoda" \
$ curl -i -X PATCH http://kong:8001/apis/example/plugins/<OIDC plugin ID> \
--data config.consumer_by="custom_id" \
Now, if a user logs into a Google account with the email
firstname.lastname@example.org, Kong will apply configuration associated with the consumer
Yoda to their requests. Note that while Google provides account emails, not all identity providers will. OpenID Connect does not have many required claims–the only required user identity claim is
sub, a unique subscriber ID. Many optional claims are
standardized, however–if a provider returns an
email claim, the contents will always be an email address.
This also requires that clients login using an account mapped to some consumer, which may not be desirable (e.g. you apply OpenID Connect to a service, but only use plugins requiring a consumer on some routes). To deal with this, you can set the
anonymous parameter in your OIDC plugin configuration to the ID of a generic consumer, which will then be used for all authenticated users that cannot be mapped to some other consumer.