OIDC with Kong Ingress Controller

TL;DR

Create a KongPlugin instance containing your client_id, client_secret, and grant_type, then annotate a Service or Route with konghq.com/plugins=my-oidc-plugin.

Prerequisites

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

  1. The following Konnect items are required to complete this tutorial:
    • Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'
    
  1. Install the Gateway API CRDs before installing Kong Ingress Controller.

    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml
    
  2. Create a Gateway and GatewayClass instance to use.

echo "
apiVersion: v1
kind: Namespace
metadata:
  name: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: kong
  annotations:
    konghq.com/gatewayclass-unmanaged: 'true'
spec:
  controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
spec:
  gatewayClassName: kong
  listeners:
  - name: proxy
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
         from: All
" | kubectl apply -n kong -f -

Use the Konnect API to create a new CLUSTER_TYPE_K8S_INGRESS_CONTROLLER Control Plane:

CONTROL_PLANE_DETAILS=$(curl -X POST "https://us.api.konghq.com/v2/control-planes" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "My KIC CP",
       "cluster_type": "CLUSTER_TYPE_K8S_INGRESS_CONTROLLER"
     }')

We’ll need the id and telemetry_endpoint for the values.yaml file later. Save them as environment variables:

CONTROL_PLANE_ID=$(echo $CONTROL_PLANE_DETAILS | jq -r .id)
CONTROL_PLANE_TELEMETRY=$(echo $CONTROL_PLANE_DETAILS | jq -r '.config.telemetry_endpoint | sub("https://";"")')

Create mTLS certificates

Kong Ingress Controller talks to Konnect over a connected secured with TLS certificates.

Generate a new certificate using openssl:

openssl req -new -x509 -nodes -newkey rsa:2048 -subj "/CN=kongdp/C=US" -keyout ./tls.key -out ./tls.crt

The certificate needs to be a single line string to send it to the Konnect API with curl. Use awk to format the certificate:

export CERT=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' tls.crt);

Next, upload the certificate to Konnect:

curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/dp-client-certificates" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "cert": "'$CERT'"
     }'

Finally, store the certificate in a Kubernetes secret so that Kong Ingress Controller can read it:

kubectl create namespace kong -o yaml --dry-run=client | kubectl apply -f -
kubectl create secret tls konnect-client-tls -n kong --cert=./tls.crt --key=./tls.key
  1. Add the Kong Helm charts:

    helm repo add kong https://charts.konghq.com
    helm repo update
    
  2. Create a file named license.json containing your Kong Gateway Enterprise license and store it in a Kubernetes secret:

    kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -
    kubectl create secret generic kong-enterprise-license --from-file=license=./license.json -n kong
    
  3. Create a values.yaml file:

    cat <<EOF > values.yaml
    gateway:
      image:
        repository: kong/kong-gateway
      env:
        LICENSE_DATA:
          valueFrom:
            secretKeyRef:
              name: kong-enterprise-license
              key: license
    EOF
    
  4. Install Kong Ingress Controller using Helm:

    helm install kong kong/ingress -n kong --create-namespace --values ./values.yaml
    
  5. Set $PROXY_IP as an environment variable for future commands:

    export PROXY_IP=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{range .status.loadBalancer.ingress[0]}{@.ip}{@.hostname}{end}')
    echo $PROXY_IP
    

This how-to requires some Kubernetes services to be available in your cluster. These services will be used by the resources created in this how-to.

kubectl apply -f https://developer.konghq.com/manifests/kic/echo-service.yaml -n kong

This how-to also requires 1 pre-configured route:

About OpenID Connect

Kong Gateway Enterprise’s OIDC plugin can authenticate requests using the OpenID Connect protocol. Learn how to set up the OIDC plugin using the Kong Ingress Controller.

Deploy Keycloak

This how-to uses Keycloak as an OpenID Connect provider.

Install Keycloak

kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/refs/heads/main/kubernetes/keycloak.yaml -n kong

Create a Route

We’ll use Kong Gateway to expose Keycloak in our cluster on a custom domain:

Register a client and user

Set two variables containing your client ID and secret:

export CLIENT_ID=kong
export CLIENT_SECRET=this_is_sup3r_secret

To call the Keycloak admin API, fetch an access token using the password grant type:

You may need to wait for Keycloak to be deployed before calling the API. Run kubectl get pods -n kong and wait until the Keycloak pod is ready.

ACCESS_TOKEN=$(curl -sSk -X POST "https://keycloak.$PROXY_IP.nip.io/realms/master/protocol/openid-connect/token" \
     -d client_id="admin-cli" -d username=admin -d password=admin -d grant_type=password | jq -r .access_token)

Next, create a new openid-connect client:

curl -k -X POST "https://https://keycloak.$PROXY_IP.nip.io/admin/realms/master/clients" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --json '{
       "protocol": "openid-connect",
       "clientId": "'$CLIENT_ID'",
       "secret": "'$CLIENT_SECRET'",
       "standardFlowEnabled": true,
       "redirectUris": [
         "http://'$PROXY_IP'/*"
       ]
     }'

Finally, register a user named alex with the password password:

curl -k -X POST "https://https://keycloak.$PROXY_IP.nip.io/admin/realms/master/users" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --json '{
       "username": "alex",
       "enabled": true,
       "credentials": [
         {
           "type": "password",
           "value": "password",
           "temporary": false
         }
       ]
     }'

You are now ready to configure the OpenID Connect plugin

Configure the OpenID Connect plugin

This example uses keycloak.$PROXY_IP.nip.io as the host, but you can use any domain name of your choice. For demo purposes, you can use the nip.io service to avoid setting up a DNS record.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  issuer: https://keycloak.$PROXY_IP.nip.io/realms/master
  client_id:
  - '$CLIENT_ID'
  client_secret:
  - '$CLIENT_SECRET'
  redirect_uri:
  - http://$PROXY_IP/echo
plugin: openid-connect
" | kubectl apply -f -

Next, apply the KongPlugin resource by annotating the service resource:

kubectl annotate -n kong service echo konghq.com/plugins=openid-connect

Validate your configuration

Once the resource has been reconciled, you’ll be able to call the /echo endpoint and Kong Gateway will route the request to the echo Service.

If you make a request without any authentication credentials, the request will fail with an HTTP 302 and a redirect to the Keycloak login page:

curl -i "$PROXY_IP/echo"
curl -i "$PROXY_IP/echo"

If you provide a password the request will be proxied successfully:

curl "$PROXY_IP/echo" \
     -u alex:password
curl "$PROXY_IP/echo" \
     -u alex:password

Cleanup

kubectl delete -n kong -f https://developer.konghq.com/manifests/kic/echo-service.yaml
helm uninstall kong -n kong
Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!