OIDC with Kong Ingress Controller
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
Kong Konnect
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
- 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.
-
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
Enable the Gateway API
-
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
-
Create a
Gateway
andGatewayClass
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 -
Create a KIC Control Plane
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
Kong Ingress Controller running (with an Enterprise license)
-
Add the Kong Helm charts:
helm repo add kong https://charts.konghq.com helm repo update
-
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
-
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
-
Install Kong Ingress Controller using Helm:
helm install kong kong/ingress -n kong --create-namespace --values ./values.yaml
-
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
Required Kubernetes resources
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
Delete created Kubernetes resources
kubectl delete -n kong -f https://developer.konghq.com/manifests/kic/echo-service.yaml
Uninstall KIC from your cluster
helm uninstall kong -n kong