[Tutorial] Securing APIs with OIDC Using Keycloak

Adam Sayah | September 3, 2020

API Gateways act as a control point between external clients (or end users) and your backend application services to make the connection, set policies around how much traffic should be accepted at any given time, to gracefully handle system failures, and to secure the environment and connection.  Authentication is one of the ways to protect the APIs (services) that you want to expose to the outside world.

In this tutorial, we’ll walk through an example of integrating Gloo API gateway with a well-known identity provider like Keycloack. Gloo is our modern API gateway and control plane for Envoy Proxy that supports a variety of different authN/Z implementations to suit your use case with a dedicated auth server; OpenID Connect (OIDC) is one of those methods. OIDC is an identity layer on top of the OAuth 2.0 protocol where the auth is performed by an external identity provider (like Keycloack), which will return an Access Token to represent the user identity if the auth workflow is successful.

Included below are step-by-step instructions on installing and configuring the software components to try this integrated auth workflow.


  • Kubernetes cluster (Any Kubernetes cluster will work, this example uses GKE)
  • Gloo Enterprise (Request a Trial license here or launch a GKE cluster with Gloo installed here)
  • Keycloak (Identity Provider for this tutorial, download here)
  • Demo application (Protected Resource)


Installing Keycloak

To install Keyclock on the Kubernetes cluster, run the following command:

After a few seconds, and depending on the type of your Kubernetes cluster, a public IP/host will be displayed for the service:

we will save Keycloak IP/host as an environment variable:

Installing a demo application

In this tutorial, we will use a demo application called petclinic that will be used as a protected resource, run the following command to install it on the Kubernetes cluster.

Then, create a virtual service to expose the demo application through the gateway:

Validate that the service is exposed through the gateway, using the browser, navigate to the URL of the gateway-proxy service, an easy way to find the gateway URL is to run:

Configuring Keycloak

In the following chapter, we will configure Keyclaok to create a realm, a client, and a user for testing.

Creating a realm

The first step is to create a realm, for that we will connect on the Keyclaok interface using the IP/host, in this tutorial the admin interface is accessible on (Keyclock Kubernetes service external address) and the default password is admin/admin

Creating a client

A client is needed to allow the authentication flow, in this example, we will create a client called gloo and configure it, to create a client, go to clients->create.
After the creation of the client, we will configure it, note the important fields: Client ID, client Protocol, Access Type, and Valid Redirect URIs.

Valid Redirect URIs is the URL where will we will be redirected to after the authentication, in this case, it is the Gloo gateway URL, the endpoint /callback is the redirect_uri needed in the OIDC authentication flow, it can be anything as long as it defined in the Gloo gateway, in this example we configured the Gloo gateway with a catch-all (/) so /callback is included.


After the creation of the client, in the Credentials tab, save the Secret as a Kubernetes secret, it will be needed to configure the OIDC on Gloo later in this tutorial:

Creating a user

To validate the authentication we will create a test user, in Keycloak navigate to Users->add user

keycloak add user

Then we need to set a password for the user:

Now we are ready to configure the OIDC on Gloo.


Configuring Gloo

Gloo uses a CRD to configure the OIDC called AuthConfig, in the example, we will define a simple configuration for Keycloak OIDC:

Finally, we will modify the virtual service to add the OIDC config to it:

Now, the user needs to be authenticated to access the demo application.

The demo application is accessed after authentication using the test user created in the previous chapter:

Want to try more Gloo?

We hope you find this tutorial useful and stay tuned for more examples with other Identity Providers. You can find previously published tutorials for Canary Releases and Network Encryption or try Gloo in our hosted Katacoda lab environment, here.

Back to Blog