You are browsing unreleased documentation. See the latest documentation here.

OIDC

Kong Gateway Enterprise’s OIDC plugin can authenticate requests using OpenID Connect protocol. Learn to setup the OIDC plugin using the Ingress Controller. It is important that you create a domain name to use OIDC plugin in a production environment.

Deploy an echo service

To proxy requests, you need an upstream application to send a request to. Deploying this echo server provides a simple application that returns information about the Pod it’s running in:

kubectl apply -f https://docs.konghq.com/assets/kubernetes-ingress-controller/examples/echo-service.yaml

The results should look like this:

service/echo created
deployment.apps/echo created

Add routing configuration

Create routing configuration to proxy /echo requests to the echo server:

echo "
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo
  annotations:
    konghq.com/strip-path: 'true'
spec:
  parentRefs:
  - name: kong
  hostnames:
  - '127.0.0.1.nip.io'
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /echo
    backendRefs:
    - name: echo
      kind: Service
      port: 1027
" | kubectl apply -f -

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo
  annotations:
    konghq.com/strip-path: 'true'
spec:
  ingressClassName: kong
  rules:
  - host: 127.0.0.1.nip.io
    http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 1027
" | kubectl apply -f -

The results should look like this:

httproute.gateway.networking.k8s.io/echo created

ingress.networking.k8s.io/echo created

Test the routing rule:

curl -i -H 'Host:127.0.0.1.nip.io' $PROXY_IP/echo

The results should look like this:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 140
Connection: keep-alive
Date: Fri, 21 Apr 2023 12:24:55 GMT
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 1
Via: kong/3.2.2

Welcome, you are connected to node docker-desktop.
Running on Pod echo-7f87468b8c-tzzv6.
In namespace default.
With IP address 10.1.0.237.
...

If everything is deployed correctly, you should see the above response. This verifies that Kong Gateway can correctly route traffic to an application running inside Kubernetes.

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

Test the Ingress rule:

$ curl -i 127.0.0.1.nip.io/echo
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 137
Connection: keep-alive
Date: Tue, 31 Oct 2023 21:26:56 GMT
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 1
Via: kong/3.4.1.0-enterprise-edition

Welcome, you are connected to node orbstack.
Running on Pod echo-74d47cc5d9-cqnh6.
In namespace default.
With IP address 192.168.194.7.

Setup OIDC plugin

Now we are going to protect our dummy service with OpenID Connect protocol using Google as our identity provider.

1. Setup an OAuth 2.0 application in Google. And set the redirect_uri to http://127.0.0.1.nip.io/echo.

   Your OAuth 2.0 application must have the openid scope.

2. After you have setup your application in Google, use the client ID and client secret and create a KongPlugin resource in Kubernetes.

    $ echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: oidc-auth
    config:
      issuer: https://accounts.google.com/.well-known/openid-configuration
      client_id:
      - <client-id>
      client_secret:
      - <client-secret>
      redirect_uri:
      - http://127.0.0.1.nip.io/echo
    plugin: openid-connect
    " | kubectl apply -f -
   

   The results should look like this:

    kongplugin.configuration.konghq.com/oidc-auth created
   

   The redirect_uri parameter must be a URI that matches the Ingress rule that you created. You must also add it to your Google OIDC configuration.

3. Enable the plugin on ingress.

    $ kubectl patch ingress echo -p '{"metadata":{"annotations":{"konghq.com/plugins":"oidc-auth"}}}'
    ingress.extensions/demo patched
   

Test the configuration

Now, if you visit http://127.0.0.1.nip.io/echo in your web browser Kong should redirect you to Google to verify your identity. After you identify yourself, you should be able to browse our dummy service once again.

This basic configuration permits any user with a valid Google account to access the dummy service. For setting up more complicated authentication and authorization flows, see the plugin docs.