[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.

Prerequisites

  • 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:

kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/kubernetes-examples/keycloak.yaml

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

kubectl get svc keycloak

NAME       TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)          AGE
keycloak   LoadBalancer   10.0.27.105   34.125.241.41   8080:31684/TCP   5h22m

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

export KEYCLOAK=34.125.241.41:8080

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.

kubectl apply -f https://raw.githubusercontent.com/solo-io/gloo/v0.8.4/example/petclinic/petclinic.yaml

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

kubectl apply -f - <<EOF
apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: petclinic
  namespace: gloo-system
spec:
  virtualHost:
    domains:
    - '*'
    routes:
    - matchers:
      - prefix: /
      routeAction:
        single:
          kube:
            ref:
              name: petclinic
              namespace: default
            port: 80
EOF

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:

glooctl proxy url
export PROXY_URL=$(glooctl proxy url)

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 34.125.241.41:8080 (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:

glooctl create secret --namespace gloo-system --name keycloak oauth --client-secret 80da0d2f-ccbc-4761-9b95-4fb8cd69695b

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:

kubectl apply -f - <<EOF
apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: oidc
  namespace: gloo-system
spec:
  configs:
  - oauth:
      appUrl: $PROXY_URL
      callbackPath: /callback
      clientId: gloo
      clientSecretRef:
        name: keycloak
        namespace: gloo-system
      issuerUrl: http://$KEYCLOAK/auth/realms/solo/
      scopes:
      - email 
EOF

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

kubectl apply -f - <<EOF
apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: petclinic
  namespace: gloo-system
spec:
  virtualHost:
    domains:
    - '*'
    options:
      extauth:
        configRef:
          name: oidc
          namespace: gloo-system    
    routes:
    - matchers:
      - prefix: /
      routeAction:
        single:
          kube:
            ref:
              name: petclinic
              namespace: default
            port: 80
EOF

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