[Tutorial] Securing APIs with OIDC Using Keycloak
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)
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 18.104.22.168 8080:31684/TCP 5h22m
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.
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)
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 22.214.171.124: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
Then we need to set a password for the user:
Now we are ready to configure the OIDC on 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.