Enable key authentication on a Gateway Service with Kong Gateway

Uses: Kong Gateway decK

Deployment Platform:

Prerequisites

Enable Keyring

Before configuring this plugin, you must enable Kong Gateway’s encryption Keyring.

Use the openssl CLI to generate an RSA key pair that can be used to export and recover Keyring material:

openssl genrsa -out key.pem 2048
openssl rsa -in key.pem -pubout -out cert.pem

To enable data encryption, you must modify the Kong Gateway configuration.

Create the following environment variables:

export KONG_KEYRING_ENABLED=on
export KONG_KEYRING_STRATEGY=cluster
export KONG_KEYRING_RECOVERY_PUBLIC_KEY=$(cat cert.pem | base64)

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 \
      -e KONG_KEYRING_ENABLED \
      -e KONG_KEYRING_STRATEGY \
      -e KONG_KEYRING_RECOVERY_PUBLIC_KEY

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.

Generate a Keyring key

Using the Admin API, generate a new key in the Keyring:

curl -X POST "http://localhost:8001/keyring/generate" \
     -H "Accept: application/json"

You will get a 201 Created response with the key and key ID. The generated key will now be used to encrypt sensitive fields in the database.

Enable the Key Authentication Encrypted plugin

Authentication lets you identify a Consumer. In this how-to, we’ll be using the Key Auth Encrypted 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-enc
    service: example-service
    config:
      key_names:
      - apikey
' | deck gateway apply -

Create a Consumer and key

Consumers let you identify the client that’s interacting with Kong Gateway. First, you need to create a Consumer:

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

The Consumer needs an API key to access any Gateway Services. We recommend not specifying the key, as Kong Gateway will autogenerate one for you in the response. Only specify a key if you are migrating an existing system to Kong Gateway.

curl -X POST "http://localhost:8001/consumers/jsmith/key-auth-enc" \
     -H "Accept: application/json"

Copy the key in the response and export it as an environment variable:

export CONSUMER_KEY='CONSUMER KEY'

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 unauthorized requests return an error:

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

You should see the following response:

Unauthorized

Then, run the following command to test Consumer authentication:

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

This request returns a 200 error with the message OK.

Cleanup

Destroy the Kong Gateway container

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