From c399939a034fe9b7180c006e8e8be75944b2d4cc Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Fri, 19 Jun 2026 13:29:08 +0200 Subject: [PATCH 1/7] feat(identity): draft auth key guide --- .../authenticate-principals-with-key-auth.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 app/_how-tos/gateway/authenticate-principals-with-key-auth.md diff --git a/app/_how-tos/gateway/authenticate-principals-with-key-auth.md b/app/_how-tos/gateway/authenticate-principals-with-key-auth.md new file mode 100644 index 0000000000..9ffdb3505e --- /dev/null +++ b/app/_how-tos/gateway/authenticate-principals-with-key-auth.md @@ -0,0 +1,155 @@ +--- +title: Authenticate Principals with the Key Authentication plugin +permalink: /how-to/authenticate-principals-with-key-auth/ +content_type: how_to +related_resources: + - text: Authentication + url: /gateway/authentication/ + +description: Use the Key Authentication plugin to allow Principals to authenticate with. +products: + - gateway + +plugins: + - basic-auth + +works_on: + - on-prem + - konnect + +min_version: + gateway: '3.4' + +entities: + - plugin + - service + - route + - principal + +tags: + - authentication + +tldr: + q: How do I authenticate Principals with basic authentication? + a: | + Create a Principal and enable the Basic Authentication plugin globally with `principals.enabled: true`. Set `principals.directory` to your directory ID, then authenticate with the base64-encoded Principal credentials. +tools: + - deck + +prereqs: + entities: + services: + - example-service + routes: + - example-route + inline: + - title: Kong Identity directory + include_content: prereqs/kong-identity-directory + icon_url: /assets/icons/identity.svg + +cleanup: + inline: + - title: Clean up Konnect environment + include_content: cleanup/platform/konnect + icon_url: /assets/icons/gateway.svg + - title: Destroy the {{site.base_gateway}} container + include_content: cleanup/products/gateway + icon_url: /assets/icons/gateway.svg +--- + +## Create a Principal + +Create the Principal by sending a POST request to the `/v2/directories/{directoryId}/principals` [endpoint](/api/konnect/kong-identity/v2/#/operations/createPrincipal). This creates a Principal named `example-principal` and saves the returned ID as `$PRINCIPAL_ID`: + + +{% konnect_api_request %} +url: /v2/directories/$DIRECTORY_ID/principals +status_code: 201 +method: POST +body: + display_name: "example-principal" + description: "Example principal" +capture: + - variable: PRINCIPAL_ID + jq: ".id" +{% endkonnect_api_request %} + + +## Add key auth + +Add an API key credential to the principal so clients can authenticate at {{site.base_gateway}} with key auth. + +The following example: +- Sets a system-generated key (`v1`) +- Stores the key secret as `$KEY_SECRET` + +VERIFY THE NAME OF THE KEY OUTPUT BY THE CLI + + +{% konnect_api_request %} +url: /v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/api-keys +status_code: 201 +method: POST +body: + type: v1 +capture: + - variable: KEY_SECRET + jq: ".secret" +{% endkonnect_api_request %} + + + + +## Configure the Key Auth plugin via decK + +Save the `directory_id` as a decK variable: + +```sh +export DECK_DIRECTORY_ID=$DIRECTORY_ID +``` + +Enable the [Key Auth](/plugins/key-auth/) plugin to allow clients to authenticate with a key when they make a request: + +{% entity_examples %} +entities: + plugins: + - name: key-auth + route: example-route + config: + identity_realms: [] + principals: + enabled: true + directory: ${directory_id} +variables: + directory_id: + value: $DIRECTORY_ID +formats: + - deck +{% endentity_examples %} + +This configuration: + +- Enables the pluging on `example-route`. +- Set the authentication method with Principals in the `example-directory` Directory. + +## Validate + +By default, the Key Auth plugin reads the key from the `apikey` header. + +First, run the following to verify that requests without a valid key are rejected: + + +{% validation unauthorized-check %} +url: /anything +{% endvalidation %} + + +Then, run the following command to test Principal authentication using the API key stored in `$KEY_SECRET`: + +{% validation request-check %} +url: '/anything' +display_headers: true +headers: + - 'apikey: $KEY_SECRET' +status_code: 200 +{% endvalidation %} \ No newline at end of file From 0d76a0f7f75ec92bd882ddcacf558765efa4112d Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 22 Jun 2026 22:03:57 +0200 Subject: [PATCH 2/7] feat(identity): test and validate guide --- .../authenticate-principals-with-key-auth.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/app/_how-tos/gateway/authenticate-principals-with-key-auth.md b/app/_how-tos/gateway/authenticate-principals-with-key-auth.md index 9ffdb3505e..a72612e389 100644 --- a/app/_how-tos/gateway/authenticate-principals-with-key-auth.md +++ b/app/_how-tos/gateway/authenticate-principals-with-key-auth.md @@ -83,8 +83,6 @@ The following example: - Sets a system-generated key (`v1`) - Stores the key secret as `$KEY_SECRET` -VERIFY THE NAME OF THE KEY OUTPUT BY THE CLI - {% konnect_api_request %} url: /v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/api-keys @@ -98,15 +96,13 @@ capture: {% endkonnect_api_request %} +## Get the directory name +To configure the Key Auth plugin, you'll need the name of the directory you created. Store it as `DECK_DIRECTORY-NAME` with this script: -## Configure the Key Auth plugin via decK - -Save the `directory_id` as a decK variable: +{% include /how-tos/steps/get-directory-name.md %} -```sh -export DECK_DIRECTORY_ID=$DIRECTORY_ID -``` +## Configure the Key Auth plugin via decK Enable the [Key Auth](/plugins/key-auth/) plugin to allow clients to authenticate with a key when they make a request: @@ -122,7 +118,7 @@ entities: directory: ${directory_id} variables: directory_id: - value: $DIRECTORY_ID + value: $DIRECTORY_NAME formats: - deck {% endentity_examples %} From 2d356c1b8efd40998208a0f5eeaf9ace5cadf847 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 22 Jun 2026 19:37:34 +0200 Subject: [PATCH 3/7] feat(identity): add directory name template --- app/_includes/how-tos/steps/get-directory-name.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 app/_includes/how-tos/steps/get-directory-name.md diff --git a/app/_includes/how-tos/steps/get-directory-name.md b/app/_includes/how-tos/steps/get-directory-name.md new file mode 100644 index 0000000000..b115e91ca0 --- /dev/null +++ b/app/_includes/how-tos/steps/get-directory-name.md @@ -0,0 +1,11 @@ + + +{% konnect_api_request %} +url: /v2/directories +status_code: 200 +method: GET +capture: + - variable: DECK_DIRECTORY_NAME + jq: ".data[0].name" +{% endkonnect_api_request %} + From e1cdefa7810dcdd7307e7cadf1970bcab10240b6 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 22 Jun 2026 19:53:30 +0200 Subject: [PATCH 4/7] fix(identity): export directory name to decK --- app/_includes/how-tos/steps/get-directory-name.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/app/_includes/how-tos/steps/get-directory-name.md b/app/_includes/how-tos/steps/get-directory-name.md index b115e91ca0..c44c60315d 100644 --- a/app/_includes/how-tos/steps/get-directory-name.md +++ b/app/_includes/how-tos/steps/get-directory-name.md @@ -9,3 +9,9 @@ capture: jq: ".data[0].name" {% endkonnect_api_request %} + +Export the directory name so decK can read it during sync: + +```bash +export DECK_DIRECTORY_NAME=$DECK_DIRECTORY_NAME +``` \ No newline at end of file From afc6d32a0f0f4855099928acf53358c058fa5e84 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 22 Jun 2026 22:06:20 +0200 Subject: [PATCH 5/7] fix(identity): variable export --- app/_includes/how-tos/steps/get-directory-name.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_includes/how-tos/steps/get-directory-name.md b/app/_includes/how-tos/steps/get-directory-name.md index c44c60315d..cf8f244498 100644 --- a/app/_includes/how-tos/steps/get-directory-name.md +++ b/app/_includes/how-tos/steps/get-directory-name.md @@ -13,5 +13,5 @@ capture: Export the directory name so decK can read it during sync: ```bash -export DECK_DIRECTORY_NAME=$DECK_DIRECTORY_NAME +export DECK_DIRECTORY_NAME ``` \ No newline at end of file From d62a3d72fad07d67a67dd0518ec923b72847550d Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 22 Jun 2026 19:37:34 +0200 Subject: [PATCH 6/7] chore(deps): update docs from repo source (#5490) Signed-off-by: kumahq[bot] <110050114+kumahq[bot]@users.noreply.github.com> Co-authored-by: kumahq[bot] <110050114+kumahq[bot]@users.noreply.github.com> --- app/_includes/how-tos/steps/get-directory-name.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_includes/how-tos/steps/get-directory-name.md b/app/_includes/how-tos/steps/get-directory-name.md index cf8f244498..5a677e9dbc 100644 --- a/app/_includes/how-tos/steps/get-directory-name.md +++ b/app/_includes/how-tos/steps/get-directory-name.md @@ -14,4 +14,4 @@ Export the directory name so decK can read it during sync: ```bash export DECK_DIRECTORY_NAME -``` \ No newline at end of file +``` From c9aa277c5a2c1a8cfa2094cfe103c288a5c7df7f Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 22 Jun 2026 22:58:03 +0200 Subject: [PATCH 7/7] typo :( --- app/_how-tos/gateway/authenticate-principals-with-key-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_how-tos/gateway/authenticate-principals-with-key-auth.md b/app/_how-tos/gateway/authenticate-principals-with-key-auth.md index a72612e389..27e09ae108 100644 --- a/app/_how-tos/gateway/authenticate-principals-with-key-auth.md +++ b/app/_how-tos/gateway/authenticate-principals-with-key-auth.md @@ -125,7 +125,7 @@ formats: This configuration: -- Enables the pluging on `example-route`. +- Enables the plugin on `example-route`. - Set the authentication method with Principals in the `example-directory` Directory. ## Validate