Home / How-to Guides
Edit
Report

Authenticate Consumers with the Key Auth and Sessions plugins

Uses: Kong Gateway deck
Deployment Platform
Related Documentation
Gateway Documentation decK Documentation
Tags
#authentication #key-auth #session
Minimum Version
Kong Gateway - 3.4
TL;DR

You can use the Session plugin, along with an authentication plugin like Key Authentication, to authenticate Consumers with session cookies. In summary, you need to:

  1. Configure the authentication plugin with credentials, an anonymous Consumer, and associate it with a Gateway Service.
  2. Create a named Consumer with a credential for the authentication plugin, as well as an anonymous Consumer.
  3. Configure the Session plugin and associate it with the Gateway Service, then configure the Request Termination plugin to prevent anonymous access.

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

     export KONNECT_TOKEN='YOUR_KONNECT_PAT'

  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

     curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN --deck-output

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

     export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
 export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='http://localhost:8000'

    Copy and paste these into your terminal to configure your session.

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.

  1. Export your license to an environment variable:

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

  2. 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   v1.43+

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial, install decK version 1.43 or later.

This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance. We recommend upgrading your decK installation to take advantage of this tool.

You can check your current decK version with deck version.

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:

  1. 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 "$KONNECT_PROXY_URL/anything" \
     --no-progress-meter --fail-with-body  \
     -H "apikey: hello_world"

You should see the following response:

OK

curl "http://localhost:8000/anything" \
     --no-progress-meter --fail-with-body  \
     -H "apikey: hello_world"

You should see the following response:

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 "$KONNECT_PROXY_URL/anything" \
     --no-progress-meter --fail-with-body  \
     -H "cookie: $COOKIE_HEADER"

You should see the following response:

OK

curl "http://localhost:8000/anything" \
     --no-progress-meter --fail-with-body  \
     -H "cookie: $COOKIE_HEADER"

You should see the following response:

OK

Cleanup

Destroy the Kong Gateway container

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

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.

Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support