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'
Copied to clipboard!
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