HTTP Basic Authentication with Datum

Configure HTTP Basic Authentication for applications behind a Datum gateway using datumctl and Envoy Gateway SecurityPolicy.

This guide describes how to configure HTTP Basic Authentication for applications running behind a Datum gateway using datumctl. The configuration uses Envoy Gateway SecurityPolicy resources and applies to Windows, macOS, and Linux.

---

Overview

HTTP Basic Authentication protects an application by requiring a username and password before requests are forwarded to the origin.

At a high level, this setup:

1. Generates credentials in htpasswd (SHA) format
2. Stores credentials in a Kubernetes Secret
3. Labels the Secret so it is synced to edge clusters
4. Attaches a SecurityPolicy to an HTTPRoute
5. Verifies authentication behavior

---

Prerequisites

• datumctl installed and authenticated
• A valid Project
• Existing:
  • Gateway
  • HTTPRoute
• Permission to create:
  • Secret
  • SecurityPolicy

Verify access:

datumctl get gateway
datumctl get httproute

---

Critical Requirement: Secret Syncing

Secrets and ConfigMaps referenced by gateway configurations are not automatically synced to edge clusters.

To make a Secret available to edge gateways, it must include the following label:

networking.datumapis.com/gateway-sync: "true"

Why This Matters

• Without this label, the gateway receives the policy but not the Secret
• Envoy fails to load the Basic Auth credentials
• All requests return HTTP 500 instead of a login prompt

This requirement exists to prevent accidental replication of unrelated secrets.

---

Configuration Steps

Step 1: Set Variables

Windows (PowerShell)

$project   = "your-project-id"
$namespace = "default"
$route     = "your-route-name"
$username  = "demo"
$password  = "ChangeMe123!"

macOS / Linux

project="your-project-id"
namespace="default"
route="your-route-name"
username="demo"
password="ChangeMe123!"

---

Step 2: Generate htpasswd Entry (SHA)

Envoy Gateway currently supports SHA-based htpasswd entries only.

Other formats (bcrypt, APR1) are not supported and will cause failures.

Windows (PowerShell)

$bytes = [Text.Encoding]::UTF8.GetBytes($password)
$sha1  = [System.Security.Cryptography.SHA1]::Create().ComputeHash($bytes)
$hash  = [Convert]::ToBase64String($sha1)

$htpasswd = "${username}:{SHA}${hash}`n"
$b64 = [Convert]::ToBase64String(
  [Text.Encoding]::UTF8.GetBytes($htpasswd)
)

macOS / Linux

hash=$(printf "%s" "$password" | shasum | awk '{print $1}' | xxd -r -p | base64)
htpasswd="${username}:{SHA}${hash}\n"
b64=$(printf "%s" "$htpasswd" | base64)

---

Step 3: Create the Secret

The Secret must:

• Use the key .htpasswd
• Exist in the same namespace as the SecurityPolicy
• Include the gateway-sync label

Windows (PowerShell)

@"
apiVersion: v1
kind: Secret
metadata:
  name: ${route}-basic-auth
  labels:
    networking.datumapis.com/gateway-sync: "true"
type: Opaque
data:
  .htpasswd: $b64
"@ | datumctl apply --project $project --namespace $namespace -f -

macOS / Linux

cat <<EOF | datumctl apply --project $project --namespace $namespace -f -
apiVersion: v1
kind: Secret
metadata:
  name: ${route}-basic-auth
  labels:
    networking.datumapis.com/gateway-sync: "true"
type: Opaque
data:
  .htpasswd: $b64
EOF

---

Step 4: Attach Basic Auth Using a SecurityPolicy

Attach the policy to the HTTPRoute. This is the most reliable attachment point.

Windows (PowerShell)

@"
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: ${route}-basic-auth
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: $route
  basicAuth:
    users:
      kind: Secret
      name: ${route}-basic-auth
"@ | datumctl apply --project $project --namespace $namespace -f -

macOS / Linux

cat <<EOF | datumctl apply --project $project --namespace $namespace -f -
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: ${route}-basic-auth
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: $route
  basicAuth:
    users:
      kind: Secret
      name: ${route}-basic-auth
EOF

---

Verification

Unauthenticated Request

curl -I https://your-app.example.com

Expected response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic

Browsers will display a login prompt.

---

Authenticated Request

curl -I -u demo:ChangeMe123! https://your-app.example.com

Expected response:

HTTP/1.1 200 OK

---

Cleanup / Disable Basic Auth

Windows (PowerShell)

datumctl delete securitypolicy ${route}-basic-auth `
  --project $project --namespace $namespace --ignore-not-found

datumctl delete secret ${route}-basic-auth `
  --project $project --namespace $namespace --ignore-not-found

macOS / Linux

datumctl delete securitypolicy ${route}-basic-auth \
  --project $project --namespace $namespace --ignore-not-found

datumctl delete secret ${route}-basic-auth \
  --project $project --namespace $namespace --ignore-not-found

---

Troubleshooting

Common Failure Modes

Symptom	Root Cause	Resolution
HTTP 500 on all requests	Secret not synced to edge	Add gateway-sync label
500 even with credentials	Secret missing at edge	Re-apply Secret with label
No login prompt	Policy not attached	Verify targetRefs
Works after deleting policy	Invalid Secret reference	Fix Secret and label

Useful Debug Commands

datumctl get secret --project $project --namespace $namespace
datumctl get securitypolicy --project $project --namespace $namespace
datumctl get httproute --project $project --namespace $namespace

---

Best Practices

• Use Basic Auth for development, demos, and staging environments
• Rotate credentials regularly
• Store credentials securely using CI secrets or a secret manager
• Use JWT, OIDC, or SSO for production authentication

---

Summary

• HTTP Basic Auth is configured using Envoy Gateway SecurityPolicy
• Secrets must be explicitly synced to edge clusters using the gateway-sync label
• {SHA} htpasswd format is required — bcrypt and APR1 are not supported
• Attaching policies to HTTPRoute is the most reliable approach