Authorization code flow

Authorization code flow

The authorization code flow is the three-legged OAuth/OpenID Connect flow. The sequence diagram below describes the participants and their interactions for this usage scenario, including the use of session cookies:

 
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 
(backend 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
  

If using PKCE, the identity provider must contain the code_challenge_methods_supported object in the /.well-known/openid-configuration issuer discovery endpoint response, as required by RFC 8414. If it is not included, the PKCE code_challenge query parameter will not be sent.

Prerequisites

In most cases, the OpenID Connect plugin relies on a third party identity provider (IdP). The examples in this guide use Keycloak as a sample IdP.

Expand the following sections to configure Keycloak and Kong Gateway.

<socket-binding name="https" port="${jboss.https.port:8443}"/>

<socket-binding name="https" port="${jboss.https.port:8440}"/>

Set up the authorization code flow

The following examples are built with simplicity in mind, and are not meant for a production environment. Because httpbin.konghq.com is the upstream service in these examples, we highly recommended that you do not run these examples with a production identity provider as there is a high chance of leaking information. The examples also use the plain HTTP protocol, which you should never use in production.

Using the Keycloak and Kong Gateway configuration from the prerequisites, set up an instance of the OpenID Connect plugin.

For the demo, we’re going to set up the following:

• Issuer, client ID, and client auth: settings that connect the plugin to your IdP (in this case, the sample Keycloak app).
• Auth methods: authorization code flow and session authentication.
• Response mode: set to form_post so that authorization codes won’t get logged to the access logs.
• We want to preserve the original request query arguments over the authorization code flow redirection.
• We want to redirect the client to original request url after the authorization code flow so that the POST request (because of form_post) is turned to the GET request, and the browser address bar is updated with the original request query arguments.
• We don’t want to include any tokens in the browser address bar.

With all of the above in mind, let’s test out the authorization code flow with Keycloak. Enable the OpenID Connect plugin on the openid-connect service:

curl -X POST http://localhost:8001/services/{serviceName|Id}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
  "name": "openid-connect",
  "config": {
    "issuer": "http://keycloak.test:8080/auth/realms/master",
    "client_id": "kong",
    "client_auth": "private_key_jwt",
    "auth_methods": [
      "authorization_code",
      "session"
    ],
    "response_mode": "form_post",
    "preserve_query_args": true,
    "login_action": "redirect",
    "login_tokens": null
  }
}
    '

curl -X POST \
https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/{serviceId}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer TOKEN" \
    --data '{"name":"openid-connect","config":{"issuer":"http://keycloak.test:8080/auth/realms/master","client_id":"kong","client_auth":"private_key_jwt","auth_methods":["authorization_code","session"],"response_mode":"form_post","preserve_query_args":true,"login_action":"redirect","login_tokens":null}}'

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect-example
plugin: openid-connect
config:
  issuer: http://keycloak.test:8080/auth/realms/master
  client_id: kong
  client_auth: private_key_jwt
  auth_methods:
  - authorization_code
  - session
  response_mode: form_post
  preserve_query_args: true
  login_action: redirect
  login_tokens: 
" | kubectl apply -f -

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

plugins:
- name: openid-connect
  service: SERVICE_NAME|ID
  config:
    issuer: http://keycloak.test:8080/auth/realms/master
    client_id: kong
    client_auth: private_key_jwt
    auth_methods:
    - authorization_code
    - session
    response_mode: form_post
    preserve_query_args: true
    login_action: redirect
    login_tokens: 

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

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

resource "konnect_gateway_plugin_openid_connect" "my_openid_connect" {
  enabled = true

  config = {
    issuer = "http://keycloak.test:8080/auth/realms/master"
    client_id = "kong"
    client_auth = "private_key_jwt"
    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
  }
}

Test the authorization code flow

At this point you have created a service, routed traffic to the service, and enabled the OpenID Connect plugin on the service. You can now test the authorization code flow.

1. Check the discovery cache:

    curl -i -X GET http://localhost:8001/openid-connect/issuers
   

   It should contain Keycloak OpenID Connect discovery document and the keys.

2. Open the service page with some query arguments:

   open http://localhost:8000/?hello=world
   

3. The browser should be redirected to the Keycloak login page.

   You can examine the query arguments passed to Keycloak with the browser’s developer tools.

4. And finally you will be presented a response from httpbin.konghq.com that looks something like this:

   {
    "args": {
        "hello": "world"
    },
    "headers": {
        "Authorization": "Bearer <access-token>",
    },
    "method": "GET",
    "url": "http://localhost:8001/anything?hello=world"
   }
   

It looks rather simple from the user point of view, but what really happened is described in the diagram above.