OpenID Connect: Authorization code flow - Plugin

Authorization code flow

This example configures the OpenID Connect plugin with an authorization code flow.

Here’s how the auth code flow works:

 
sequenceDiagram
    autonumber
    participant client as Client 
(e.g. mobile app)
    participant kong as API Gateway 
(Kong)
    participant idp as IdP 
(e.g. Keycloak)
    participant httpbin as Upstream 
(upstream service,
 e.g. httpbin)
    activate client
    activate kong
    client->>kong: HTTP request
    kong->>client: Redirect mobile app to IDP 
    deactivate kong
    activate idp
    client->>idp: Request access and authentication
with client parameter
    Note left of idp: /auth
response_type=code,
scope=openid
    idp->>client: Login (ask for consent)
    client->>idp: /auth with user credentials (grant consent)
    idp->>client: Return authorization code and redirect
    Note left of idp: short-lived authcode
    activate kong
    client->>kong: HTTP redirect with authorization code
    deactivate client
    kong->>kong: Verify authorization code flow
    kong->>idp: Request ID token, access token, and refresh token
    Note left of idp: /token
client_id:client_secret
authcode
    idp->>idp: Authenticate client (Kong)
and validate authcode
    idp->>kong: Returns tokens
    Note left of idp: ID token, access token, and refresh token
    deactivate idp
    kong->>kong: Validate tokens
    Note right of kong: Cryptographic
signature validation,
expiry check
(OIDC Standard JWT validation)
    activate client
    kong->>client: Redirect with session cookie
having session ID (SID)
    Note left of kong: sid: cryptorandom bytes 
(128 bits)
& HMAC protected
    client->>kong: Authenticated request with session cookie
    deactivate client
    kong->>kong: Verify session cookie
    Note right of kong: Retrieve encrypted tokens
from session store (redis)
    activate httpbin
    kong->>httpbin: Backend service request with tokens
    Note right of idp: Access token and ID token
    httpbin->>kong: Backend service response
    deactivate httpbin
    activate client
    kong->>client: HTTP response
    deactivate kong
    deactivate client

For a full example that shows you how to set up the authorization code flow with Keycloak, see Configure OpenID Connect with the auth code flow.

Note: Setting config.client_auth to client_secret_post lets you easily test the connection to your IdP, but we recommend using a more secure auth method in production. You can use any of the supported client auth methods.

Prerequisites

A configured identity provider (IdP)

Environment variables

ISSUER: The issuer authentication URL for your IdP. For example, if you’re using Keycloak as your IdP, the issuer URL looks like this: http://localhost:8080/realms/example-realm
CLIENT_ID: The client ID that the plugin uses when it calls authenticated endpoints of the IdP.
CLIENT_SECRET: The client secret needed to connect to your IdP.

Set up the plugin

Add this section to your declarative configuration file:

_format_version: "3.0"
plugins:
  - name: openid-connect
    config:
      issuer: ${{ env "DECK_ISSUER" }}
      client_id:
      - ${{ env "DECK_CLIENT_ID" }}
      client_secret:
      - ${{ env "DECK_CLIENT_SECRET" }}
      client_auth:
      - client_secret_post
      auth_methods:
      - authorization_code
      - session
      response_mode: form_post
      preserve_query_args: true
      login_action: redirect
      login_tokens: 

Make the following request:

curl -i -X POST http://localhost:8001/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "openid-connect",
      "config": {
        "issuer": "'$ISSUER'",
        "client_id": [
          "'$CLIENT_ID'"
        ],
        "client_secret": [
          "'$CLIENT_SECRET'"
        ],
        "client_auth": [
          "client_secret_post"
        ],
        "auth_methods": [
          "authorization_code",
          "session"
        ],
        "response_mode": "form_post",
        "preserve_query_args": true,
        "login_action": "redirect",
        "login_tokens": null
      }
    }
    '

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "openid-connect",
      "config": {
        "issuer": "'$ISSUER'",
        "client_id": [
          "'$CLIENT_ID'"
        ],
        "client_secret": [
          "'$CLIENT_SECRET'"
        ],
        "client_auth": [
          "client_secret_post"
        ],
        "auth_methods": [
          "authorization_code",
          "session"
        ],
        "response_mode": "form_post",
        "preserve_query_args": true,
        "login_action": "redirect",
        "login_tokens": null
      }
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: openid-connect
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: 'true'
config:
  issuer: '$ISSUER'
  client_id:
  - '$CLIENT_ID'
  client_secret:
  - '$CLIENT_SECRET'
  client_auth:
  - client_secret_post
  auth_methods:
  - authorization_code
  - session
  response_mode: form_post
  preserve_query_args: true
  login_action: redirect
  login_tokens: 
plugin: openid-connect
" | kubectl apply -f -

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_openid_connect" "my_openid_connect" {
  enabled = true

  config = {
    issuer = var.issuer
    client_id = [var.client_id]
    client_secret = [var.client_secret]
    client_auth = ["client_secret_post"]
    auth_methods = ["authorization_code", "session"]
    response_mode = "form_post"
    preserve_query_args = true
    login_action = "redirect"
    login_tokens = 
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "client_secret" {
  type = string
}

Add this section to your declarative configuration file:

_format_version: "3.0"
plugins:
  - name: openid-connect
    service: serviceName|Id
    config:
      issuer: ${{ env "DECK_ISSUER" }}
      client_id:
      - ${{ env "DECK_CLIENT_ID" }}
      client_secret:
      - ${{ env "DECK_CLIENT_SECRET" }}
      client_auth:
      - client_secret_post
      auth_methods:
      - authorization_code
      - session
      response_mode: form_post
      preserve_query_args: true
      login_action: redirect
      login_tokens: 

Make sure to replace the following placeholders with your own values:

serviceName|Id: The id or name of the service the plugin configuration will target.

Make the following request:

curl -i -X POST http://localhost:8001/services/{serviceName|Id}/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "openid-connect",
      "config": {
        "issuer": "'$ISSUER'",
        "client_id": [
          "'$CLIENT_ID'"
        ],
        "client_secret": [
          "'$CLIENT_SECRET'"
        ],
        "client_auth": [
          "client_secret_post"
        ],
        "auth_methods": [
          "authorization_code",
          "session"
        ],
        "response_mode": "form_post",
        "preserve_query_args": true,
        "login_action": "redirect",
        "login_tokens": null
      }
    }
    '

Make sure to replace the following placeholders with your own values:

serviceName|Id: The id or name of the service the plugin configuration will target.

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/{serviceId}/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "openid-connect",
      "config": {
        "issuer": "'$ISSUER'",
        "client_id": [
          "'$CLIENT_ID'"
        ],
        "client_secret": [
          "'$CLIENT_SECRET'"
        ],
        "client_auth": [
          "client_secret_post"
        ],
        "auth_methods": [
          "authorization_code",
          "session"
        ],
        "response_mode": "form_post",
        "preserve_query_args": true,
        "login_action": "redirect",
        "login_tokens": null
      }
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
serviceId: The id of the service the plugin configuration will target.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  issuer: '$ISSUER'
  client_id:
  - '$CLIENT_ID'
  client_secret:
  - '$CLIENT_SECRET'
  client_auth:
  - client_secret_post
  auth_methods:
  - authorization_code
  - session
  response_mode: form_post
  preserve_query_args: true
  login_action: redirect
  login_tokens: 
plugin: openid-connect
" | kubectl apply -f -

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

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

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_openid_connect" "my_openid_connect" {
  enabled = true

  config = {
    issuer = var.issuer
    client_id = [var.client_id]
    client_secret = [var.client_secret]
    client_auth = ["client_secret_post"]
    auth_methods = ["authorization_code", "session"]
    response_mode = "form_post"
    preserve_query_args = true
    login_action = "redirect"
    login_tokens = 
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  service = {
    id = konnect_gateway_service.my_service.id
  }
}

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "client_secret" {
  type = string
}

Add this section to your declarative configuration file:

_format_version: "3.0"
plugins:
  - name: openid-connect
    route: routeName|Id
    config:
      issuer: ${{ env "DECK_ISSUER" }}
      client_id:
      - ${{ env "DECK_CLIENT_ID" }}
      client_secret:
      - ${{ env "DECK_CLIENT_SECRET" }}
      client_auth:
      - client_secret_post
      auth_methods:
      - authorization_code
      - session
      response_mode: form_post
      preserve_query_args: true
      login_action: redirect
      login_tokens: 

Make sure to replace the following placeholders with your own values:

routeName|Id: The id or name of the route the plugin configuration will target.

Make the following request:

curl -i -X POST http://localhost:8001/routes/{routeName|Id}/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "openid-connect",
      "config": {
        "issuer": "'$ISSUER'",
        "client_id": [
          "'$CLIENT_ID'"
        ],
        "client_secret": [
          "'$CLIENT_SECRET'"
        ],
        "client_auth": [
          "client_secret_post"
        ],
        "auth_methods": [
          "authorization_code",
          "session"
        ],
        "response_mode": "form_post",
        "preserve_query_args": true,
        "login_action": "redirect",
        "login_tokens": null
      }
    }
    '

Make sure to replace the following placeholders with your own values:

routeName|Id: The id or name of the route the plugin configuration will target.

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/{routeId}/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "openid-connect",
      "config": {
        "issuer": "'$ISSUER'",
        "client_id": [
          "'$CLIENT_ID'"
        ],
        "client_secret": [
          "'$CLIENT_SECRET'"
        ],
        "client_auth": [
          "client_secret_post"
        ],
        "auth_methods": [
          "authorization_code",
          "session"
        ],
        "response_mode": "form_post",
        "preserve_query_args": true,
        "login_action": "redirect",
        "login_tokens": null
      }
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
routeId: The id of the route the plugin configuration will target.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  issuer: '$ISSUER'
  client_id:
  - '$CLIENT_ID'
  client_secret:
  - '$CLIENT_SECRET'
  client_auth:
  - client_secret_post
  auth_methods:
  - authorization_code
  - session
  response_mode: form_post
  preserve_query_args: true
  login_action: redirect
  login_tokens: 
plugin: openid-connect
" | kubectl apply -f -

Next, apply the KongPlugin resource by annotating the httproute or ingress resource:

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

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

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_openid_connect" "my_openid_connect" {
  enabled = true

  config = {
    issuer = var.issuer
    client_id = [var.client_id]
    client_secret = [var.client_secret]
    client_auth = ["client_secret_post"]
    auth_methods = ["authorization_code", "session"]
    response_mode = "form_post"
    preserve_query_args = true
    login_action = "redirect"
    login_tokens = 
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  route = {
    id = konnect_gateway_route.my_route.id
  }
}

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "client_secret" {
  type = string
}

OpenID Connect

Authorization code flow

Prerequisites

Environment variables

Set up the plugin

Help us make these docs great!

Still need help