Authenticate Consumers with the Key Auth and Sessions plugins

Uses: Kong Gateway decK

Deployment Platform:

Prerequisites

Kong Konnect

This is a Konnect tutorial. 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.
- Control Plane Name: You can use an existing Control Plane or create a new one to use for this tutorial.
- Konnect Proxy URL: By default, a self-hosted Data Plane uses http://localhost:8000. You can set up Data Plane nodes for your Control Plane from the Gateway Manager in Konnect.

Set the personal access token, the Control Plane name, the Control Plane URL, and the Konnect proxy URL as environment variables:

 export DECK_KONNECT_TOKEN='YOUR KONNECT TOKEN'
 export DECK_KONNECT_CONTROL_PLANE_NAME='YOUR CONTROL PLANE NAME'
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='KONNECT PROXY URL'

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.

Required 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-service
    url: http://httpbin.konghq.com/anything
routes:
  - name: example-route
    paths:
    - "/anything"
    service:
      name: example-service
' | deck gateway apply -

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

Enable the Key Authentication plugin

Authentication lets you identify a Consumer. In this tutorial, we’ll be using the Key Auth plugin for authentication, which allows users to authenticate with a key when they make a request.

Enable the plugin for the Gateway Service you created in the prerequisites:

echo '
_format_version: "3.0"
plugins:
  - name: key-auth
    service: example-service
    config:
      key_names:
      - apikey
      anonymous: 81823632-10c0-4098-a4f7-31062520c1e6
' | deck gateway apply -

Create Consumers

Consumers let you identify the client that’s interacting with Kong Gateway. In this tutorial, we’ll create one named Consumer with a credential as well as an anonymous Consumer to prevent anonymous access with the Key Authentication plugin.

Create Consumers and an authentication credential for the named Consumer:

echo '
_format_version: "3.0"
consumers:
  - username: alex
    keyauth_credentials:
    - key: hello_world
  - username: anonymous_users
    id: 81823632-10c0-4098-a4f7-31062520c1e6
' | deck gateway apply -

Enable the Session plugin

The Session plugin allows you to manage browser sessions for APIs proxied through the Kong Gateway.

We’ll be setting config.cookie_secure to false for the sake of this tutorial so we don’t have to use HTTPS, but in a production instance, leave this as the default value of true.

Enable the plugin for the Gateway Service you created in the prerequisites:

echo '
_format_version: "3.0"
plugins:
  - name: session
    service: example-service
    config:
      storage: kong
      cookie_secure: false
' | deck gateway apply -

Enable the Request Termination plugin

In this tutorial, we’ll be using the Request Termination plugin to prevent unauthorized access by anonymous Consumers:

echo '
_format_version: "3.0"
plugins:
  - name: request-termination
    service: example-service
    consumer: anonymous_users
    config:
      status_code: 403
      message: Forbidden
' | deck gateway apply -

Validate

After configuring the Key Authentication Encryption plugin, you can verify that it was configured correctly and is working by sending requests with and without the API key you created for your Consumer.

First, run the following to verify that anonymous requests return an error:

curl -i $KONNECT_PROXY_URL/anything

curl -i http://localhost:8000/anything

This request returns a 403 error with the message Forbidden.

Then, run the following command to verify that a user can authenticate via sessions:

curl -i $KONNECT_PROXY_URL/anything \
     -H "apikey: hello_world"

curl -i http://localhost:8000/anything \
     -H "apikey: hello_world"

This request returns a 200 error with the message OK.

The response should now have the Set-Cookie header. Make sure that this cookie works by copying the contents (for example: session=emjbJ3MdyDsoDUkqmemFqw..|1544654411|4QMKAE3I-jFSgmvjWApDRmZHMB8.) and exporting it in an environment variable:

export COOKIE_HEADER='YOUR-COOKIE-HEADER-HERE'

Use your session token in the request, but don’t provide the API key. Even without the key, you will still be authenticated because Kong Gateway is using the session cookie granted by the Session plugin:

curl -i $KONNECT_PROXY_URL/anything \
     -H "cookie: "$COOKIE_HEADER""

curl -i http://localhost:8000/anything \
     -H "cookie: "$COOKIE_HEADER""