HTTP Basic Authentication with Datum

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:

Generates credentials in htpasswd (SHA) format
Stores credentials in a Kubernetes Secret
Labels the Secret so it is synced to edge clusters
Attaches a SecurityPolicy to an HTTPRoute
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=$(printf "%s:{SHA}%s\n" "$username" "$hash")
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

Documentation

TLDR

Platform

AI Edge

Connectors

Galactic VPC

Domains & DNS

Agents

Tools

HTTP Basic Authentication with Datum

Overview

Prerequisites

Critical requirement: secret syncing

Why this matters

Configuration steps

Step 1: Set variables

Windows (PowerShell)

macOS / Linux

Step 2: Generate htpasswd entry (SHA)

Windows (PowerShell)

macOS / Linux

Step 3: Create the secret

Windows (PowerShell)

macOS / Linux

Step 4: Attach Basic Auth using a SecurityPolicy

Windows (PowerShell)

macOS / Linux

Verification

Unauthenticated request

Authenticated request

Cleanup / disable Basic Auth

Windows (PowerShell)

macOS / Linux

Troubleshooting

Common failure modes

Useful debug commands

Best practices

Summary

​Overview

​Prerequisites

​Critical requirement: secret syncing

​Why this matters

​Configuration steps

​Step 1: Set variables

​Windows (PowerShell)

​macOS / Linux

​Step 2: Generate htpasswd entry (SHA)

​Windows (PowerShell)

​macOS / Linux

​Step 3: Create the secret

​Windows (PowerShell)

​macOS / Linux

​Step 4: Attach Basic Auth using a SecurityPolicy

​Windows (PowerShell)

​macOS / Linux

​Verification

​Unauthenticated request

​Authenticated request

​Cleanup / disable Basic Auth

​Windows (PowerShell)

​macOS / Linux

​Troubleshooting

​Common failure modes

​Useful debug commands

​Best practices

​Summary

Overview

Prerequisites

Critical requirement: secret syncing

Why this matters

Configuration steps

Step 1: Set variables

Windows (PowerShell)

macOS / Linux

Step 2: Generate htpasswd entry (SHA)

Windows (PowerShell)

macOS / Linux

Step 3: Create the secret

Windows (PowerShell)

macOS / Linux

Step 4: Attach Basic Auth using a SecurityPolicy

Windows (PowerShell)

macOS / Linux

Verification

Unauthenticated request

Authenticated request

Cleanup / disable Basic Auth

Windows (PowerShell)

macOS / Linux

Troubleshooting

Common failure modes

Useful debug commands

Best practices

Summary