Enable OAuth 2.0 authentication for WebSocket requests

Uses: Kong Gateway decK

Deployment Platform:

Prerequisites

Kong Gateway running

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

Export your license to an environment variable:

 export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

Run the quickstart script:

 curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA 

Once Kong Gateway is ready, you will see the following message:

 Kong Gateway Ready

decK

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.

Pre-configured entities

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

Run the following command:

echo '
_format_version: "3.0"
services:
  - name: example-websocket-service
    url: ws://echo.websocket.org/
routes:
  - name: example-websocket-route
    paths:
    - "/anything"
    protocols:
    - ws
    service:
      name: example-websocket-service
' | deck gateway apply -

To learn more about entities, you can read our entities documentation.

Create an HTTP Service and Route to handle token creation

In the prerequisites, you created a WebSocket Service and Route.

To use the OAuth 2.0 Authentication plugin with WebSocket services, you need an additional non-WebSocket Route to issue tokens:

echo '
_format_version: "3.0"
routes:
  - name: websocket-token-route
    protocols:
    - https
    paths:
    - "/token-route"
    methods:
    - POST
' | deck gateway apply -

Generate a provision key

Use uuidgen to generate a provision key for the OAuth 2.0 Authentication plugin:

export DECK_PROVISION_KEY=$(uuidgen)

Enable the OAuth 2.0 plugin

Enable the plugin on:

The WebSocket Gateway Service we created in the prerequisites, to secure it
The HTTP Route, to enable token generation

Set config.global_credentials to true to allow tokens created by other plugin instances.

echo '
_format_version: "3.0"
plugins:
  - name: oauth2
    service: example-websocket-service
    config:
      scopes:
      - email
      - profile
      global_credentials: true
      provision_key: "${{ env "DECK_PROVISION_KEY" }}"
      enable_client_credentials: true
  - name: oauth2
    route: websocket-token-route
    config:
      scopes:
      - email
      - profile
      global_credentials: true
      provision_key: "${{ env "DECK_PROVISION_KEY" }}"
      enable_client_credentials: true
' | deck gateway apply -

Create a Consumer

Consumers let you identify the client that’s interacting with Kong Gateway. Create a new Consumer with just a username:

echo '
_format_version: "3.0"
consumers:
  - username: alex
' | deck gateway apply -

Create an application

Create an application for the Consumer:

curl -X POST "http://localhost:8001/consumers/alex/oauth2" \
     -H "Accept: application/json"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "TestApp",
       "redirect_uris": [
         "http://localhost:8000/anything"
       ]
     }'

Export the autogenerated client ID and client secret to environment variables:

export CLIENT_ID={client_id}
export CLIENT_SECRET={client_secret}

Generate a token

Use the applications’s client credentials to generate a token:

curl -X POST "https://localhost:8443/token-route/oauth2/token" \
  --header "Content-Type: application/json" \
  --json '{ 
    "client_id": "'$CLIENT_ID'", 
    "client_secret": "'$CLIENT_SECRET'", 
    "grant_type": "client_credentials" 
  }'

Note: This request requires HTTPS, so we need to use the 8443 port instead of 8000.

Validate

To validate that the configuration works as expected, open a WebSocket connection to ws://localhost:8000/anything using the Authorization header with the Bearer token we generated. You can do this using Insomnia.

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

Destroy the Kong Gateway container

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d