Home / How-to Guides
Edit
Report

Authenticate Principals with basic authentication

Uses: Kong Gateway Kong Identity deck
Deployment Platform
Related Documentation
Gateway Documentation decK Documentation
Tags
#authentication
Related Resources
Authentication
Principals and directories
Minimum Version
Kong Gateway - 3.15
TL;DR

Create a Principal and enable the Basic Authentication plugin globally with principals.enabled: true. Set principals.directory to your directory name, then authenticate with the base64-encoded Principal credentials.

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.64.0+

To complete this tutorial, install decK. We recommend keeping decK up to date with the latest version (1.64.0).

decK is a CLI tool for managing Kong Gateway declaratively with state files. This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance.

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
    protocols:
    - http
    - https
' | deck gateway apply -

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

Kong Identity directory

A directory is a regional collection of principals. Create a directory for this tutorial:

DIRECTORY_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "kong-identity-directory",
       "description": "Directory for this tutorial",
       "allow_all_control_planes": true
     }' | jq -r ".id"
)

Create a Principal

Create the Principal by sending a POST request to the /v2/directories/{directoryId}/principals endpoint:

PRINCIPAL_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "display_name": "example-principal",
       "description": "Example principal"
     }' | jq -r ".id"
)

This script:

  • Creates a Principal named example-principal
  • Saves the returned ID as $PRINCIPAL_ID

Add basic auth credentials

Create basic auth credentials for the Principal in two steps:

Create the username example-user:

BASIC_AUTH_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/basic-auths" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "username": "example-user"
     }' | jq -r ".id"
)

Then, set the password to: example-password

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/basic-auths/$BASIC_AUTH_ID/passwords" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "secret": "example-password"
     }'

This sets the following credentials for the Principal:

  • Username: example-user
  • Password: example-password

Get the directory name

To configure the Basic Auth plugin, you’ll need the name of the directory you created. Store it as DECK_DIRECTORY_NAME with this script:

DECK_DIRECTORY_NAME=$(curl -X GET "https://us.api.konghq.com/v2/directories" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" | jq -r ".data[0].name"
)

Export the directory name so decK can read it during sync:

export DECK_DIRECTORY_NAME

Configure the Basic Auth plugin via decK

Enable the Basic Authentication plugin to allow users to authenticate with a username and password when they make a request.

echo '
_format_version: "3.0"
plugins:
  - config:
      hide_credentials: true
      principals:
        directory: "${{ env "DECK_DIRECTORY_NAME" }}"
        enabled: true
    enabled: true
    name: basic-auth
    protocols:
    - http
    - https
    route: example-route
' | deck gateway apply -

This configuration:

  • Applies the plugin to example-route
  • Sets the authentication method with Principals in the example-directory Directory

Validate

When a Principal authenticates with basic auth, the authorization header must be base64-encoded. For example, since we are using example-user as the username and example-password as the password, then the field’s value is the base64 encoding of example-user:example-password, or ZXhhbXBsZS11c2VyOmV4YW1wbGUtcGFzc3dvcmQ=.

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

curl -i $KONNECT_PROXY_URL/anything \
     -H "authorization: Basic wrongpassword"
curl -i http://localhost:8000/anything \
     -H "authorization: Basic wrongpassword"

This request returns a 401 error with the message Unauthorized.

Then, run the following command to test Principal authentication:

curl -i "$KONNECT_PROXY_URL/anything" \
     --no-progress-meter --fail-with-body  \
     -H "authorization: Basic ZXhhbXBsZS11c2VyOmV4YW1wbGUtcGFzc3dvcmQ="
curl -i "http://localhost:8000/anything" \
     --no-progress-meter --fail-with-body  \
     -H "authorization: Basic ZXhhbXBsZS11c2VyOmV4YW1wbGUtcGFzc3dvcmQ="

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
Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

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 Slack Community
Contact Support