> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```yaml theme={null}
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)

```powershell theme={null}
$project   = "your-project-id"
$namespace = "default"
$route     = "your-route-name"
$username  = "demo"
$password  = "ChangeMe123!"
```

#### macOS / Linux

```bash theme={null}
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)

```powershell theme={null}
$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

```bash theme={null}
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)

```powershell theme={null}
@"
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

```bash theme={null}
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)

```powershell theme={null}
@"
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
curl -I -u demo:ChangeMe123! https://your-app.example.com
```

Expected response:

```
HTTP/1.1 200 OK
```

***

## Cleanup / disable Basic Auth

### Windows (PowerShell)

```powershell theme={null}
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

```bash theme={null}
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

```bash theme={null}
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