feat(identity): authenticate principals with Basic Auth

app/_how-tos/gateway/authenticate-principals-with-basic-authentication.md

@@ -0,0 +1,174 @@
+---
+title: Authenticate Principals with basic authentication
+permalink: /how-to/authenticate-principals-with-basic-authentication/
+content_type: how_to
+related_resources:
+  - text: Authentication
+    url: /gateway/authentication/
+
+description: Use the Basic Authentication plugin to allow Principals to authenticate with a username and password.
+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
+
+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 Directory
+
+[Directories](/identity/principals/) let you assign a list of [Principals](/identity/principals/) to authenticate clients interacting with {{site.base_gateway}} services.
+
+To start using Principals, create a Directory by sending a `POST` request to the [`/v2/directories` endpoint](/api/konnect/kong-identity/v2/#/operations/createDirectory). This creates a Directory named `example-directory`:
+
+
+```bash
+curl -X POST "https://us.api.konghq.com/v2/directories" \
+     --no-progress-meter --fail-with-body  \
+     -H "Authorization: Bearer $KONNECT_TOKEN" \
+     --json '{
+       "name": "example-directory",
+       "description": "Example directory for principals",
+       "allow_all_control_planes": true
+     }'
+```
+
+Save the returned ID as `$DIRECTORY_ID`:
+
+
+```bash
+export DIRECTORY_ID='DIRECTORY_ID'
+```
+
+
+## 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`:
+
+```bash
+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"
+     }'
+```
+
+Save the returned ID as `$PRINCIPAL_ID`:
+
+
+```bash
+export PRINCIPAL_ID='PRINCIPAL_ID'
+```
+
+## Add basic auth credentials
+
+Create basic auth credentials for the Principal:
+
+```bash
+curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/basic-auths" \
+     -H "Authorization: Bearer $KONNECT_TOKEN" \
+     --json '{
+       "username": "example-user",
+       "password": "example-password"
+     }'
+```
+
+This sets the following credentials for the Principal:
+
+- Username: `example-user`
+- Password: `example-password`
+
+## Configure the Basic Auth plugin via decK
+
+Enable the [Basic Authentication plugin](/plugins/basic-auth/) to allow users to authenticate with a username and password when they make a request.
+
+1. Run `echo $DIRECTORY_ID` and copy the output.
+
+2. Paste the value to replace `DIRECTORY_ID`, then run:
+
+{% entity_examples %}
+entities:
+  plugins:
+  - config:
+      hide_credentials: true
+      principals:
+        directory: DIRECTORY_ID
+        enabled: true
+    enabled: true
+    name: basic-auth
+    protocols:
+    - http
+    - https
+    route: example-route
+formats:
+  - deck
+{% endentity_examples %}
+
+This configuration:
+
+- Enables the plugin globally, which means it applies to all {{site.base_gateway}} Services and Routes.
+- Set 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:
+
+<!--vale off-->
+{% validation unauthorized-check %}
+url: /anything
+headers:
+  - 'authorization: Basic wrongpassword'
+{% endvalidation %}
+<!--vale on-->
+
+Then, run the following command to test Principal authentication:
+
+{% validation request-check %}
+url: '/anything'
+display_headers: true
+headers:
+  - 'authorization: Basic ZXhhbXBsZS11c2VyOmV4YW1wbGUtcGFzc3dvcmQ='
+status_code: 200
+{% endvalidation %}

app/_indices/identity.yaml

@@ -11,4 +11,5 @@ sections:
       - path: /how-to/configure-kong-identity-oidc/
       - path: /how-to/configure-kong-identity-oauth-introspection/
       - path: /how-to/configure-kong-identity-upstream-oauth/
-      - path: /how-to/kong-identity-dcr/
+      - path: /how-to/kong-identity-dcr/
+      - path: /how-to/authenticate-principals-with-basic-authentication/