diff --git a/alb/authentication/api-keys.mdx b/alb/authentication/api-keys.mdx
new file mode 100644
index 0000000..9333f59
--- /dev/null
+++ b/alb/authentication/api-keys.mdx
@@ -0,0 +1,135 @@
+---
+title: "API keys"
+sidebarTitle: "API keys"
+description: "Give each script, CI job, or partner its own API key, checked at the edge, and pass the client's name to your origin."
+---
+
+API key authentication accepts a request only if it carries one of the keys you issued. [Envoy](/platform/envoy) checks the key at the edge, so requests without a valid key never reach your origin.
+
+Each key has a name, such as `ci-pipeline` or `partner-acme`, and Envoy can pass that name to your origin. That gives each machine client its own identity, which you can revoke on its own, without the shared password of [Basic Auth](/alb/authentication/basic-auth) or the identity provider that [JWT](/alb/authentication/jwt) needs.
+
+## Set up API keys
+
+Keys live in a Secret. Each entry's **name** is the client's name, and its **value** is the key. Generate long random keys, such as with `openssl rand -hex 32`.
+
+Save this as `api-keys.yaml`, with your own keys:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+ name: ALB_NAME-api-keys
+ labels:
+ networking.datumapis.com/gateway-sync: "true"
+type: Opaque
+stringData:
+ ci-pipeline: "REPLACE_WITH_A_RANDOM_KEY"
+ partner-acme: "REPLACE_WITH_ANOTHER_RANDOM_KEY"
+---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+ name: ALB_NAME-api-keys
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ apiKeyAuth:
+ credentialRefs:
+ - name: ALB_NAME-api-keys
+ extractFrom:
+ - headers:
+ - x-api-key
+ forwardClientIDHeader: X-Client-Id
+ sanitize: true
+```
+
+```bash
+datumctl apply -f api-keys.yaml
+```
+
+Then call the load balancer with a key:
+
+```bash
+curl -H "x-api-key: $KEY" https://HOSTNAME/
+```
+
+A request with no key or a wrong key gets `401`. A request with a valid key reaches your origin with `X-Client-Id: ci-pipeline`, or whichever name the key has.
+
+| Field | What it does |
+| --- | --- |
+| `credentialRefs` | One or more Secrets holding keys. Split keys across Secrets by team or partner if you like. |
+| `extractFrom` | Where to look for the key: `headers`, `params` (query parameters), or `cookies` |
+| `forwardClientIDHeader` | Sends the key's name to your origin in this header. Envoy overwrites any value the client sent, so it can't be faked. |
+| `sanitize` | Removes the key from the request before it reaches your origin. Without it, your origin receives the key too. |
+
+## Add, rotate, and revoke keys
+
+Envoy picks up changes to the Secret within seconds, with no change to the policy.
+
+- **Add a key:** add an entry to the Secret, or a new Secret to `credentialRefs`.
+- **Rotate a key:** add the new key under a new name, such as `ci-pipeline-2`, move the client over, then revoke the old one.
+- **Revoke a key:** remove its entry from the Secret's `data`:
+
+ ```bash
+ datumctl patch secret ALB_NAME-api-keys --type=json \
+ -p '[{"op":"remove","path":"/data/partner-acme"}]'
+ ```
+
+
+ Re-applying a manifest that leaves a key out of `stringData` does **not** remove the key. The stored value stays in the Secret's `data`, and the key keeps working. Remove it from `data` with `datumctl patch`, or delete and recreate the Secret.
+
+
+## Limit each client's request rate
+
+Because Envoy sets `X-Client-Id` from the key, you can give each client its own rate limit with a `BackendTrafficPolicy` on the same route:
+
+```yaml
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+ name: ALB_NAME-api-limits
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ rateLimit:
+ type: Local
+ local:
+ rules:
+ - clientSelectors:
+ - headers:
+ - name: X-Client-Id
+ type: Distinct
+ limit:
+ requests: 600
+ unit: Minute
+```
+
+Each client gets its own count, and requests over the limit get `429`. Limits are counted separately by each Envoy instance, so treat them as approximate: a client can sometimes get slightly more than the limit.
+
+## Give clients different access
+
+A key identifies a client but grants nothing by itself: every valid key reaches every path the policy protects. To give clients different access:
+
+- Put each group of paths on its own route, with its own policy and keys. See [Different authentication per path](/alb/authentication/per-path).
+- Or check `X-Client-Id` in your origin.
+
+## Things to know
+
+- **Keys are stored as plain text** in the Secret. Anyone who can read Secrets in your project can read the keys. Limit who has that access.
+- **Keys don't expire.** Rotate them yourself.
+- **A key in a query parameter** ends up in browser history and server logs. Prefer a header.
+- **Combining with JWT:** a policy with both `apiKeyAuth` and `jwt` requires both a key and a token.
+- **No per-key metrics.** Access logs show response codes, but not which key was used.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `500` on every request | A Secret in `credentialRefs` is missing the `gateway-sync` label or doesn't exist. | Add the label, and check the names. |
+| `401` with a valid key | The key is sent in a different header, parameter, or cookie than `extractFrom` lists. | Match `extractFrom` to how clients send the key. |
+| A revoked key still works | The key was removed from `stringData` in a manifest but is still in `data`. | Remove it with `datumctl patch`, as above. |
+| The origin receives the key | `sanitize` isn't set. | Set `sanitize: true`. |
diff --git a/alb/authentication/authorization.mdx b/alb/authentication/authorization.mdx
new file mode 100644
index 0000000..a502636
--- /dev/null
+++ b/alb/authentication/authorization.mdx
@@ -0,0 +1,178 @@
+---
+title: "Authorization rules"
+sidebarTitle: "Authorization rules"
+description: "Decide who is allowed through a Datum load balancer by token claims, such as email, domain, or role, or by request headers, HTTP methods, and client IP ranges."
+---
+
+Authentication proves who is calling. Authorization decides whether they're allowed in. An `authorization` block in a `SecurityPolicy` checks each request against a list of rules at the edge, and returns `403 Forbidden` to callers who aren't allowed, so your origin never sees them.
+
+Use it to:
+
+- Let in only some of the people who can sign in with [OIDC](/alb/authentication/oidc), such as one Google Workspace domain or a list of email addresses.
+- Allow only tokens with a given role or scope on a [JWT](/alb/authentication/jwt) API.
+- Allow or block client IP ranges, with or without any other authentication.
+- Leave reads open and protect writes.
+
+## How rules work
+
+```yaml
+ authorization:
+ defaultAction: Deny
+ rules:
+ - name: admins
+ action: Allow
+ principal:
+ jwt:
+ provider: corp
+ claims:
+ - name: roles
+ valueType: StringArray
+ values: ["admin"]
+```
+
+- **Rules run in order, and the first match wins.** Put specific `Deny` rules before broader `Allow` rules.
+- **`defaultAction`** applies when no rule matches. It defaults to `Deny`.
+- **A rule matches** when all of its conditions match: every part of `principal`, and `operation` if set. Within one condition, any of the listed values matches.
+- **Denied requests get `403`.**
+
+The `authorization` block goes in the same `SecurityPolicy` as the authentication it relies on. A rule on JWT claims needs a `jwt` block in that policy, and names its provider.
+
+## What a rule can match
+
+| Condition | Matches | Example |
+| --- | --- | --- |
+| `principal.jwt.claims` | A claim in a token checked by the policy's `jwt` block | `email` is `alice@example.com` |
+| `principal.jwt.scopes` | Scopes in the token's `scope` claim | `orders:write` |
+| `principal.headers` | A request header's exact value | `x-team: payments` |
+| `principal.clientCIDRs` | The client's IP address range | `203.0.113.0/24` |
+| `operation.methods` | The HTTP method | `POST`, `DELETE` |
+
+### Claims
+
+```yaml
+ jwt:
+ provider: corp
+ claims:
+ - name: email
+ values: ["alice@example.com", "bob@example.com"]
+ - name: realm_access.roles
+ valueType: StringArray
+ values: ["admin"]
+```
+
+- Values match **exactly**. There are no wildcards: `*@example.com` matches nothing.
+- For a claim that holds a list, such as roles or groups, set `valueType: StringArray`. The rule matches if the list contains any of the values.
+- For a nested claim, join the path with dots, as in `realm_access.roles`.
+- Only text claims can be matched. A true or false claim, such as `email_verified`, can't.
+- Several claims in one rule must all match.
+
+### Headers
+
+Header rules match the header's exact value. Clients can set most headers themselves, so only trust a header that Envoy sets, such as `X-Client-Id` from [API keys](/alb/authentication/api-keys), or one that a trusted client adds.
+
+### Client IP ranges
+
+```yaml
+ rules:
+ - name: office
+ action: Allow
+ principal:
+ clientCIDRs:
+ - 203.0.113.0/24
+ - 2001:db8:1234::/48
+```
+
+A policy can have only an `authorization` block, with no authentication, to make a simple IP allow list. Many clients, such as mobile users, cloud browsers, and CI runners, change address often, so IP rules work best combined with another method.
+
+## Examples
+
+### Allow one Google Workspace domain
+
+Google signs in anyone with a Google account. Google's ID token carries an `hd` claim with the Workspace domain, and only Workspace accounts have it. With [OIDC set up for Google](/alb/authentication/oidc-google) and a `jwt` block that reads the ID token, allow only your domain:
+
+```yaml
+ authorization:
+ defaultAction: Deny
+ rules:
+ - name: workspace-domain
+ action: Allow
+ principal:
+ jwt:
+ provider: google
+ claims:
+ - name: hd
+ values: ["example.com"]
+```
+
+See [Restrict who can sign in](/alb/authentication/oidc-google#restrict-who-can-sign-in) for the full policy.
+
+### Allow listed people
+
+```yaml
+ - name: listed-people
+ action: Allow
+ principal:
+ jwt:
+ provider: idp
+ claims:
+ - name: email
+ values: ["alice@example.com", "bob@example.com"]
+```
+
+Email addresses can change. Where the provider offers a stable ID, such as `sub`, prefer it.
+
+### Read for everyone, write for editors
+
+With `jwt.optional: true`, requests without a token still reach the rules:
+
+```yaml
+ jwt:
+ optional: true
+ providers:
+ - name: corp
+ # ...
+ authorization:
+ defaultAction: Deny
+ rules:
+ - name: reads
+ action: Allow
+ operation:
+ methods: ["GET", "HEAD", "OPTIONS"]
+ principal:
+ clientCIDRs: ["0.0.0.0/0", "::/0"]
+ - name: editors-write
+ action: Allow
+ principal:
+ jwt:
+ provider: corp
+ claims:
+ - name: groups
+ valueType: StringArray
+ values: ["editors"]
+```
+
+### Block one caller at once
+
+Tokens stay valid until they expire. To cut off one caller now, put a `Deny` rule first:
+
+```yaml
+ rules:
+ - name: revoked
+ action: Deny
+ principal:
+ jwt:
+ provider: corp
+ claims:
+ - name: sub
+ values: ["7d1c0e2a-revoked-user"]
+ # ...your Allow rules
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `403` for everyone | The claim isn't in the token, a list claim lacks `valueType: StringArray`, or the claim name is wrong. | Decode a token and check the claim's exact name and type. Ask your provider to include it, such as by requesting the right scope. |
+| `403` for some people who should get in | Values match exactly, including case. | Use the exact value from the token. |
+| A rule seems ignored | An earlier rule matched first. | Reorder the rules. |
+| The rule is never checked | The policy wasn't accepted. | Run `datumctl describe securitypolicy` and look for `Conflicted`. |
diff --git a/alb/authentication/basic-auth.mdx b/alb/authentication/basic-auth.mdx
index 073df3f..8ff7cfd 100644
--- a/alb/authentication/basic-auth.mdx
+++ b/alb/authentication/basic-auth.mdx
@@ -1,15 +1,15 @@
---
title: "Basic authentication"
sidebarTitle: "Basic Auth"
-description: "Require a username and password before requests reach your origin, with datumctl alb auth or an Envoy Gateway SecurityPolicy."
+description: "Require a username and password before requests reach your origin, with datumctl alb auth or an Envoy Gateway SecurityPolicy, including per-user passwords."
---
-HTTP basic authentication protects a load balancer with a username and password. [Envoy](/platform/envoy) checks the credentials on every request, at the edge, before the request reaches your origin. Requests without valid credentials get `401 Unauthorized`.
+HTTP Basic Auth protects a load balancer with a username and password. [Envoy](/platform/envoy) checks the credentials on every request, at the edge, before the request reaches your origin. Requests without valid credentials get `401 Unauthorized`, and browsers show a sign-in prompt.
There are two ways to set it up:
-- **`datumctl alb auth`** is the quickest. One command sets the users, creates the Secret, and attaches the policy.
-- **A `SecurityPolicy` manifest** gives you full control, for example to keep the configuration in Git or to protect a single route.
+- **`datumctl alb auth`** is the quickest. One command sets the users, creates the Secret, and attaches the policy. Every user gets the same password.
+- **A `SecurityPolicy` manifest** gives you full control: a different password for each user, the username passed to your origin, configuration kept in Git, or protection for a single path.
## Set up Basic Auth with datumctl alb
@@ -34,7 +34,13 @@ To protect a load balancer, pass one or more users, and give their password on s
-To admit several users with the same password, repeat `--user`, as in `--user admin --user editor`. To check a change without applying it, add `--dry-run`.
+To admit several users, repeat `--user`, as in `--user admin --user editor`. They all share the one password. Each `alb auth set` replaces the whole user list, so pass every user each time. To check a change without applying it, add `--dry-run`.
+
+`alb auth set` creates a Secret named `ALB_NAME-basic-auth` and a `SecurityPolicy` named `ALB_NAME` that targets the load balancer's **Gateway**, so it covers every route.
+
+
+ A `SecurityPolicy` that targets one of the load balancer's **routes** replaces the Gateway's policy for that route. If you add any route-level policy, even one with only CORS, Basic Auth from `alb auth set` stops applying to that route, and `datumctl alb describe` still shows it as enabled. To combine Basic Auth with anything else, use a [manifest](#set-up-basic-auth-with-a-securitypolicy) and put every setting in one route-level policy.
+
To see which usernames are allowed, run the following command:
@@ -55,322 +61,146 @@ curl -s -o /dev/null -w '%{http_code}\n' https://HOSTNAME/ # 401
curl -s -o /dev/null -w '%{http_code}\n' -u admin https://HOSTNAME/ # prompts for the password, then 200
```
-## Set up Basic Auth with a SecurityPolicy
-
-The rest of this page shows how to configure the same thing with [Envoy Gateway](https://gateway.envoyproxy.io/) resources, using `datumctl apply`.
-
----
-
-### How it works
-
-At a high level, this setup:
+### Give each user their own password
-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:
+`alb auth set` gives every user the same password. To give each user their own, replace the `.htpasswd` lines in the Secret it created:
```bash
-datumctl get gateway
-datumctl get httproute
+entry() { printf '%s:{SHA}%s\n' "$1" "$(printf '%s' "$2" | openssl dgst -sha1 -binary | base64)"; }
+htpasswd=$( { entry admin 'first-long-random-password'; entry editor 'second-long-random-password'; } | base64 | tr -d '\n')
+datumctl patch secret ALB_NAME-basic-auth --type=merge \
+ -p "{\"data\":{\".htpasswd\":\"$htpasswd\"}}"
```
----
-
-## 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
-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
-
-
-
-
- ```bash
- project="your-project-id"
- namespace="default"
- route="your-route-name"
- username="demo"
- password="ChangeMe123!"
- ```
-
-
-
-
- ```powershell
- $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, such as bcrypt and APR1, are **not supported** and cause failures.
-
-
-
-
- ```bash
- 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)
- ```
-
-
-
-
- ```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)
- )
- ```
+Envoy picks up the change within seconds, and `alb auth list` and `alb describe` still show the users. Running `alb auth set` again replaces them with one shared password.
-
-
+## Set up Basic Auth with a SecurityPolicy
----
+A manifest takes two resources: a Secret holding an `htpasswd` list, and a `SecurityPolicy` that points at it and at the load balancer's route. The route has the same name as the load balancer. See [Where a SecurityPolicy attaches](/alb/authentication/overview#where-a-securitypolicy-attaches).
-### Step 3: Create the secret
+Use a manifest when you want Basic Auth together with other settings, such as CORS, in one policy, or on a single path. `datumctl alb auth list` and `datumctl alb describe` don't show Basic Auth set up this way, so don't also run `alb auth set` on the same load balancer.
-The Secret must:
+### Step 1: Generate an htpasswd entry for each user
-- Use the key `.htpasswd`
-- Exist in the same namespace as the `SecurityPolicy`
-- Include the **gateway-sync** label
+Envoy accepts **SHA entries only** (`{SHA}`). Other formats, such as bcrypt and APR1, aren't supported. SHA is a fast, unsalted hash, so use long random passwords.
```bash
- cat <
```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 -
+ function Entry($user, $password) {
+ $sha1 = [System.Security.Cryptography.SHA1]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($password))
+ "${user}:{SHA}$([Convert]::ToBase64String($sha1))"
+ }
+ Entry alice 'first-long-random-password'
+ Entry bob 'second-long-random-password'
```
----
+Each line looks like `alice:{SHA}fAYATt6GBC1fG3rV/+TsArfpfqs=`.
-### Step 4: Attach Basic Auth with a SecurityPolicy
+### Step 2: Create the Secret and the policy
-Attach the policy to the **HTTPRoute**. This is the most reliable attachment point.
-
-
-
-
- ```bash
- cat <
-
-
- ```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 -
- ```
-
-
-
+The Secret must use the key `.htpasswd`, have one line per user, and carry the `gateway-sync` label. Save this as `basic-auth.yaml`, with your own entries:
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+ name: ALB_NAME-htpasswd
+ labels:
+ networking.datumapis.com/gateway-sync: "true"
+type: Opaque
+stringData:
+ .htpasswd: |
+ alice:{SHA}fAYATt6GBC1fG3rV/+TsArfpfqs=
+ bob:{SHA}7zQr7w5Y9jpYtGS5eu5Mwj1Qxz4=
---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+ name: ALB_NAME-basic-auth
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ basicAuth:
+ users:
+ name: ALB_NAME-htpasswd
+ forwardUsernameHeader: X-Username
+```
-## Verification
-
-### Unauthenticated request
+Apply it:
```bash
-curl -I https://your-app.example.com
+datumctl apply -f basic-auth.yaml
```
-Expected response:
+`forwardUsernameHeader` is optional. With it, your origin receives the signed-in user's name, such as `X-Username: bob`. Envoy sets the header itself, so a client can't fake it.
-```
-HTTP/1.1 401 Unauthorized
-WWW-Authenticate: Basic
-```
-
-Browsers display a login prompt.
+
+ Envoy also forwards the client's `Authorization` header to your origin, and that header carries the password, only base64-encoded. Trust your origin with it, or have the origin ignore it.
+
----
-
-### Authenticated request
+### Step 3: Check it
```bash
-curl -I -u demo:ChangeMe123! https://your-app.example.com
-```
-
-Expected response:
-
+curl -s -o /dev/null -w '%{http_code}\n' https://HOSTNAME/ # 401
+curl -s -o /dev/null -w '%{http_code}\n' -u alice:first-long-random-password https://HOSTNAME/ # 200
```
-HTTP/1.1 200 OK
-```
-
----
-## Clean up or disable Basic Auth
+A new or changed policy takes up to a minute to reach every location.
-
-
-
- ```bash
- datumctl delete securitypolicy ${route}-basic-auth \
- --project $project --namespace $namespace --ignore-not-found
+## Change or remove users
- datumctl delete secret ${route}-basic-auth \
- --project $project --namespace $namespace --ignore-not-found
- ```
-
-
-
+To add, remove, or change a user, edit the `.htpasswd` lines and apply the Secret again. Envoy picks up the change within seconds, with no change to the policy.
- ```powershell
- datumctl delete securitypolicy ${route}-basic-auth `
- --project $project --namespace $namespace --ignore-not-found
+To remove Basic Auth set up with a manifest, delete the policy and the Secret while the load balancer still exists:
- datumctl delete secret ${route}-basic-auth `
- --project $project --namespace $namespace --ignore-not-found
- ```
+```bash
+datumctl delete securitypolicy ALB_NAME-basic-auth
+datumctl delete secret ALB_NAME-htpasswd
+```
-
-
+To remove Basic Auth set up with `datumctl alb auth set`, run `datumctl alb auth unset ALB_NAME`.
----
+
+ **Known issue:** `datumctl alb auth unset` and `datumctl alb delete` leave the Secret `ALB_NAME-basic-auth` behind, and deleting it can leave it in `Terminating` indefinitely, held by the finalizer `gateway.networking.datumapis.com/gateway-resource-replicator`. The Secret no longer protects anything. Don't remove the finalizer yourself. Contact support if you need it gone.
+
## 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 |
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `500` on every request | The Secret is missing the `gateway-sync` label, or the policy names the wrong Secret. | Add the label, or fix `users.name` in the policy. |
+| `401` with the right password | The entry isn't `{SHA}`, or the hash was made from a password with a trailing newline. | Regenerate the entry with `printf '%s'`, not `echo`. |
+| No sign-in prompt | The policy isn't attached, or another policy already targets the route. | Check `targetRefs`, and run `datumctl describe securitypolicy` to look for `Conflicted`. |
+| No password needed after you add CORS, JWT, or another policy | A route-level policy replaced the Gateway-level Basic Auth from `alb auth set`. | Put `basicAuth` in the route's policy, and run `alb auth unset`. |
+| `alb auth list` doesn't show your users | Basic Auth was set up with a manifest. | Read the Secret, or use `alb auth set`. |
-### Useful debug commands
+Useful commands:
```bash
-datumctl get secret --project $project --namespace $namespace
-datumctl get securitypolicy --project $project --namespace $namespace
-datumctl get httproute --project $project --namespace $namespace
+datumctl get securitypolicies
+datumctl get secrets
+datumctl get httproutes
```
----
-
-## 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
-
----
+## When to use something else
-## Summary
+Basic Auth is a shared-secret check. There's no sign-out, no expiry, and every request carries the password. For production:
-- You configure HTTP Basic Auth with an **Envoy Gateway `SecurityPolicy`**
-- Secrets **must be explicitly synced** to edge clusters using the `gateway-sync` label
-- `{SHA}` htpasswd format is required. Other formats, such as bcrypt and APR1, are not supported
-- Attaching policies to `HTTPRoute` is the most reliable approach
+- Use [OIDC](/alb/authentication/oidc) for people, so they sign in with your identity provider and leaving the company removes their access.
+- Use [API keys](/alb/authentication/api-keys) or [JWT](/alb/authentication/jwt) for machines, so each client has its own credential that you can revoke without changing the others.
diff --git a/alb/authentication/cors.mdx b/alb/authentication/cors.mdx
new file mode 100644
index 0000000..1443a02
--- /dev/null
+++ b/alb/authentication/cors.mdx
@@ -0,0 +1,80 @@
+---
+title: "CORS"
+sidebarTitle: "CORS"
+description: "Let browser apps on other origins call your load balancer, with cross-origin resource sharing (CORS) handled at the edge."
+---
+
+Browsers block a web page from reading responses from another origin unless that origin allows it with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) headers. A `cors` block in a `SecurityPolicy` lets [Envoy](/platform/envoy) answer for your origin: it replies to preflight requests at the edge and adds the CORS headers to responses, so your app doesn't have to.
+
+## Set up CORS
+
+Save this as `cors.yaml`, with the origins of the sites that call your API:
+
+```yaml
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+ name: ALB_NAME-cors
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ cors:
+ allowOrigins:
+ - "https://app.example.com"
+ - "https://*.example.com"
+ allowMethods: ["GET", "POST", "PUT", "DELETE"]
+ allowHeaders: ["authorization", "content-type"]
+ exposeHeaders: ["x-request-id"]
+ allowCredentials: true
+ maxAge: "10m"
+```
+
+```bash
+datumctl apply -f cors.yaml
+```
+
+| Field | What it does |
+| --- | --- |
+| `allowOrigins` | Origins allowed to call, as `scheme://host[:port]`. A `*` matches any one part of a hostname, and `"*"` alone allows every origin. |
+| `allowMethods` | Methods allowed in cross-origin requests |
+| `allowHeaders` | Request headers the page may send, such as `authorization` |
+| `exposeHeaders` | Response headers the page may read |
+| `allowCredentials` | Allows cookies and `Authorization` headers on cross-origin requests. Can't be combined with `"*"` in `allowOrigins`. |
+| `maxAge` | How long the browser may cache a preflight answer |
+
+## CORS with authentication
+
+A route takes one `SecurityPolicy`, so put `cors` in the same policy as your authentication, such as `jwt` or `apiKeyAuth`:
+
+```yaml
+spec:
+ cors:
+ allowOrigins: ["https://app.example.com"]
+ allowMethods: ["GET", "POST"]
+ allowHeaders: ["authorization", "content-type"]
+ jwt:
+ providers:
+ - name: corp
+ # ...
+```
+
+Envoy answers preflight (`OPTIONS`) requests before authentication runs, so browsers can check CORS without a token. Error responses such as `401` and `403` also carry the CORS headers, so your page can read them and send the person to sign in.
+
+## Check it
+
+Send a preflight request the way a browser would:
+
+```bash
+curl -s -o /dev/null -D - -X OPTIONS \
+ -H 'Origin: https://app.example.com' \
+ -H 'Access-Control-Request-Method: POST' \
+ https://HOSTNAME/api | grep -i '^access-control'
+```
+
+An allowed origin gets `access-control-allow-origin: https://app.example.com`. Any other origin gets no `access-control-allow-origin` header, and the browser blocks the response.
+
+
+ CORS only tells browsers what to allow. It doesn't stop scripts, servers, or `curl` from calling your API. Use [authentication](/alb/authentication/overview) for that.
+
diff --git a/alb/authentication/jwt.mdx b/alb/authentication/jwt.mdx
new file mode 100644
index 0000000..c32dd96
--- /dev/null
+++ b/alb/authentication/jwt.mdx
@@ -0,0 +1,160 @@
+---
+title: "JWT authentication"
+sidebarTitle: "JWT"
+description: "Accept only requests that carry a valid JSON Web Token from your own issuer, and pass the caller's claims to your origin."
+---
+
+JWT authentication accepts a request only if it carries a valid [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) from an issuer you trust. [Envoy](/platform/envoy) checks the token's signature, issuer, audience, and expiry at the edge, so your origin never sees a request with a missing, expired, or forged token.
+
+It suits APIs and machine clients that already get tokens from an identity provider, for example with the OAuth 2.0 client credentials grant. Datum stores no users or keys: the issuer signs tokens, and Envoy checks them against the issuer's public keys.
+
+For people signing in with a browser, use [OIDC](/alb/authentication/oidc) instead. OIDC runs the sign-in flow and can then check the resulting token with the same `jwt` block.
+
+## Set up JWT authentication
+
+Save this as `jwt.yaml`, with your own issuer, audience, and key URL:
+
+```yaml
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+ name: ALB_NAME-jwt
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ jwt:
+ providers:
+ - name: corp
+ issuer: https://idp.example.com/realms/corp
+ audiences:
+ - orders-api
+ remoteJWKS:
+ uri: https://idp.example.com/realms/corp/protocol/openid-connect/certs
+ claimToHeaders:
+ - claim: sub
+ header: X-User
+ - claim: email
+ header: X-Email
+```
+
+```bash
+datumctl apply -f jwt.yaml
+```
+
+No Secret is needed. Then call the load balancer with a token:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" https://HOSTNAME/
+```
+
+| Request | Response |
+| --- | --- |
+| No token | `401` |
+| A forged, altered, or `alg: none` token | `401` |
+| An expired token | `401`, once it is more than 60 seconds past `exp` |
+| A token for an audience not in `audiences` | `403` |
+| A valid token | Forwarded to your origin |
+
+## Provider fields
+
+| Field | What it does |
+| --- | --- |
+| `name` | A name for the provider. Authorization rules refer to it. |
+| `issuer` | Must equal the token's `iss` claim exactly, including any trailing slash. Leave it out to accept any issuer whose keys verify the token. |
+| `audiences` | Accept only tokens whose `aud` claim contains one of these values. Leave it out to skip the audience check. |
+| `remoteJWKS.uri` | Your issuer's public keys (its `jwks_uri`). Envoy fetches and caches them, so key rotation at the issuer needs no change here. |
+| `localJWKS` | The public keys written into the policy instead of fetched. See [Keys in the policy](#keys-in-the-policy). |
+| `claimToHeaders` | Copies claims into request headers for your origin |
+| `extractFrom` | Where to find the token, if not in `Authorization: Bearer`. See [Token location](#token-location). |
+| `recomputeRoute` | Re-matches the route after `claimToHeaders` sets headers, so routes can match on a claim. Needs `claimToHeaders`. |
+
+Field names follow [Envoy Gateway's JWT reference](https://gateway.envoyproxy.io/docs/api/extension_types/#jwtprovider).
+
+### Keys in the policy
+
+If your issuer has no public JWKS URL, or you sign tokens yourself, put the public keys in the policy:
+
+```yaml
+ - name: internal
+ issuer: https://issuer.example.com
+ localJWKS:
+ type: Inline
+ inline: |
+ {"keys":[{"kty":"RSA","kid":"key-1","use":"sig","alg":"RS256","n":"uTfRz4Tc...","e":"AQAB"}]}
+```
+
+To rotate a key, add the new public key to `keys`, switch the signer, then remove the old key.
+
+### Token location
+
+By default, Envoy reads the token from `Authorization: Bearer`. To read it from somewhere else, set `extractFrom`. Once it is set, Envoy reads only the locations you list:
+
+```yaml
+ extractFrom:
+ headers:
+ - name: X-Api-Token
+ valuePrefix: "Bearer "
+ cookies:
+ - session-token
+ params:
+ - access_token
+```
+
+### Several issuers
+
+List several providers to accept tokens from any of them, such as a staging and a production issuer. A request passes if its token is valid for one provider.
+
+### Optional tokens
+
+`optional: true` under `jwt` lets requests without a token through. Requests with an invalid token are still rejected, and requests with a valid one still get their claim headers. Use it with [authorization rules](/alb/authentication/authorization) to protect some methods and leave others open.
+
+```yaml
+ jwt:
+ optional: true
+ providers:
+ - name: corp
+ # ...
+```
+
+## Decide who is allowed
+
+A valid token proves who the caller is, not what they may do. To allow only some callers, such as tokens with an `admin` role or a given client ID, add an `authorization` block to the same policy:
+
+```yaml
+ authorization:
+ defaultAction: Deny
+ rules:
+ - name: admins
+ action: Allow
+ principal:
+ jwt:
+ provider: corp
+ claims:
+ - name: roles
+ valueType: StringArray
+ values: ["admin"]
+```
+
+A valid token that doesn't match gets `403`. See [Authorization rules](/alb/authentication/authorization).
+
+## Revoking access
+
+Envoy doesn't call the issuer on each request, so a token stays valid until it expires, even after you disable the account or client at the issuer. Envoy also allows 60 seconds of clock skew past `exp`, which you can't change.
+
+Keep token lifetimes short, such as 5 to 15 minutes, so that disabling an account at the issuer takes effect quickly. To cut off a caller at once, block it with an [authorization rule](/alb/authentication/authorization), such as a `Deny` rule on its `sub` or client ID.
+
+## Combine with other methods
+
+- **API keys:** a policy with both `apiKeyAuth` and `jwt` requires both, such as a key for the calling app and a token for the user.
+- **OIDC:** a policy with both `oidc` and `jwt` can check claims on people who signed in. See [Restrict who can sign in](/alb/authentication/oidc#restrict-who-can-sign-in).
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `401` with a token that looks valid | `issuer` doesn't match `iss` exactly, the token is signed with a key not in the JWKS, or the token isn't where `extractFrom` looks. | Decode the token and compare `iss` and `kid` with the policy. |
+| `403` with a valid token | `aud` isn't in `audiences`, or an authorization rule doesn't match. | Compare `aud` and the rule's claims with the token. |
+| `403` for everyone | The claim the rule checks isn't in the tokens, or a list claim is matched without `valueType: StringArray`. | Configure the issuer to add the claim, and set `valueType`. |
+| Claim headers are missing at the origin | The claim isn't in the token, or `claimToHeaders` names it differently. | Claim names are case-sensitive. Use the exact name from the token. |
diff --git a/alb/authentication/oidc-auth0.mdx b/alb/authentication/oidc-auth0.mdx
index 9e383b9..9124133 100644
--- a/alb/authentication/oidc-auth0.mdx
+++ b/alb/authentication/oidc-auth0.mdx
@@ -1,11 +1,15 @@
---
title: "Per-user access with Auth0"
sidebarTitle: "Auth0 (per-user)"
-description: "Configure per-user authentication and email-based authorization using Auth0 and Google social login for applications behind a Datum gateway."
+description: "Let only the people on an Auth0 allow-list reach your app, with Auth0 handling Google sign-in and an Envoy Gateway SecurityPolicy at the edge."
---
This page shows how to let only the people on your allow-list reach your app. Auth0 handles Google sign-in and checks each person's email against the list before it issues a token, so people who aren't allowed never reach Envoy. The configuration uses an [Envoy Gateway](https://gateway.envoyproxy.io/) `SecurityPolicy` and `datumctl`.
+
+ You don't need Auth0 to limit who gets in. With any OIDC provider, including Google directly, an [authorization rule](/alb/authentication/authorization) at the load balancer can allow only certain email addresses, domains, or roles. See [Restrict who can sign in](/alb/authentication/oidc#restrict-who-can-sign-in). Use Auth0 when you want it to manage users, or to combine several sign-in sources.
+
+
---
## How it works
@@ -42,11 +46,11 @@ sequenceDiagram
- `datumctl` installed and authenticated
- A valid Datum **Project**
-- An existing **HTTPProxy** in the Datum UI (this provides the Gateway and HTTPRoute automatically)
+- An existing load balancer, created in the portal or with `datumctl alb create`. It provides the Gateway and HTTPRoute automatically.
- An **Auth0 account** (free tier is sufficient)
- A **Google Cloud** project for the social connection
-> **Note:** The HTTPProxy name is the name of the auto-generated HTTPRoute that the SecurityPolicy will target. Find it with:
+> **Note:** The load balancer's name is the name of the auto-generated HTTPRoute that the SecurityPolicy will target. Find it with:
> ```bash
> datumctl get httproute --project your-project-id --namespace default
> ```
@@ -219,7 +223,7 @@ The Secret must include the `gateway-sync` label or the edge proxy will not rece
This attaches OIDC authentication to the existing HTTPProxy route.
-> **Warning:** Use only the `oidc` block — do not add a `jwt` block, as it conflicts with the OIDC filter and causes HTTP 500.
+> **Note:** To check claims on top of Auth0's allow-list, a `jwt` block in the same policy can read the ID token from its cookie. See [Restrict who can sign in](/alb/authentication/oidc#restrict-who-can-sign-in). Point it at the ID token, not the access token: unless you request an API audience, Auth0's access token isn't a JWT.
@@ -328,6 +332,8 @@ All access control is managed in the Auth0 dashboard — no gateway config chang
2. Select **Deploy**
3. Optionally revoke any active sessions: **User Management** → find user → **Invalidate Sessions**
+A person who is already signed in keeps their session at the load balancer until the access token expires and Envoy can't renew it. Keep Auth0's access-token lifetime short if removals must take effect quickly.
+
---
## Cleanup
@@ -364,8 +370,9 @@ All access control is managed in the Auth0 dashboard — no gateway config chang
| Symptom | Root cause | Resolution |
|---------|------------|------------|
| HTTP 200 instead of redirect | SecurityPolicy not yet propagated | Wait 60 seconds; verify with `datumctl get securitypolicy` |
-| HTTP 500 on all requests (immediate) | `jwt` block present in SecurityPolicy | Remove `jwt` block — use `oidc` block only |
-| HTTP 500 on all requests (immediate) | WAF (`TrafficProtectionPolicy`) blocking OIDC | Remove the `TrafficProtectionPolicy` targeting the Gateway |
+| HTTP 500 on all requests (immediate) | Auth0 was unreachable, or the issuer URL was wrong, when the policy arrived | Check `https:///.well-known/openid-configuration`, then delete and reapply the policy |
+| HTTP 403 on the callback | The web application firewall blocked the callback request | Check firewall events in the [access logs](/alb/observability), and add a rule exclusion. See [Web application firewall](/alb/configuration/waf). Don't remove the firewall. |
+| HTTP 403 for everyone after sign-in | A `jwt` block reads the access token, or `audiences` isn't the client ID | Read the ID token cookie, and set `audiences` to the Auth0 client ID |
| HTTP 500 on all requests | Secret missing `gateway-sync` label | Verify label is present; re-apply Secret if needed |
| Auth0 error: `callback URL mismatch` | App hostname not in Auth0 Allowed Callback URLs | Add `https:///oauth2/callback` in Auth0 Application Settings |
| Google error 400: `redirect_uri_mismatch` | Auth0 callback not in Google OAuth client | Add `https:///login/callback` to Google Cloud Console Authorized redirect URIs |
diff --git a/alb/authentication/oidc-google.mdx b/alb/authentication/oidc-google.mdx
index a234fc2..fb044a2 100644
--- a/alb/authentication/oidc-google.mdx
+++ b/alb/authentication/oidc-google.mdx
@@ -1,337 +1,181 @@
---
title: "Sign in with Google (OIDC)"
sidebarTitle: "Google (OIDC)"
-description: "Configure OIDC authentication using Google OAuth 2.0 for applications behind a Datum gateway using datumctl and Envoy Gateway SecurityPolicy."
+description: "Require people to sign in with Google before requests reach your app, and limit access to your Google Workspace domain or a list of people."
---
-This page shows how to require people to sign in with their Google account before requests reach your app, using an [Envoy Gateway](https://gateway.envoyproxy.io/) `SecurityPolicy` and `datumctl`.
+This page shows how to require people to sign in with Google before requests reach your app, and how to limit access to your Workspace domain or to a list of people. It uses an [Envoy Gateway](https://gateway.envoyproxy.io/) `SecurityPolicy`. For how OIDC sign-in works with any provider, see [Sign in with OIDC](/alb/authentication/oidc).
----
+
+ On its own, Google sign-in lets in **anyone with a Google account**. To limit who gets in, follow [Restrict who can sign in](#restrict-who-can-sign-in) too.
+
-## Overview
+## Before you start
-OIDC authentication protects an application by requiring users to sign in with their Google account before requests are forwarded to the origin. Envoy Gateway handles the OAuth 2.0 flow transparently — users are redirected to Google, authenticate, and are redirected back without any changes to your application.
+- A load balancer, ideally with a [custom hostname](/alb/operations/custom-domains). The redirect URL you register with Google has to match exactly, so use a hostname that won't change.
+- A Google Cloud project where you can create OAuth credentials.
-At a high level, this setup:
+## Step 1: Create a Google OAuth client
-1. Creates a **Google OAuth 2.0 Client** in Google Cloud Console
-2. Stores the client secret in a **Kubernetes Secret**
-3. Labels the Secret so it is synced to edge clusters
-4. Attaches a **SecurityPolicy** with OIDC config to an `HTTPRoute`
-5. Verifies authentication behavior
+1. In the [Google Cloud console](https://console.cloud.google.com), go to **APIs & Services** → **Credentials**.
+2. Select **Create Credentials** → **OAuth client ID**. If asked, configure the consent screen first.
+3. Set **Application type** to **Web application**.
+4. Under **Authorized redirect URIs**, add `https://HOSTNAME/oauth2/callback`, with your load balancer's hostname.
+5. Select **Create**, and copy the **Client ID** and **Client secret**.
----
+If your organization uses Google Workspace, you can set the consent screen's **User type** to **Internal**. Google then signs in only accounts in your Workspace organization.
-## Prerequisites
+## Step 2: Store the client secret
-- `datumctl` installed and authenticated
-- A valid **Project**
-- A **Google Cloud** account with a project
-- Existing:
- - `Gateway`
- - `HTTPRoute`
-- Permission to create:
- - `Secret`
- - `SecurityPolicy`
+Save this as `google-secret.yaml`, with your client secret:
-Verify access:
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+ name: ALB_NAME-oidc
+ labels:
+ networking.datumapis.com/gateway-sync: "true"
+type: Opaque
+stringData:
+ client-secret: YOUR_CLIENT_SECRET
+```
```bash
-datumctl get gateway
-datumctl get httproute
+datumctl apply -f google-secret.yaml
```
----
-
-## Critical requirement: secret syncing
+The Secret must use the key `client-secret` and carry the `gateway-sync` label. Without the label, every request returns `500`.
-Secrets and ConfigMaps referenced by gateway configurations are **not automatically synced** to edge clusters.
+## Step 3: Apply the SecurityPolicy
-To make a Secret available to edge gateways, it **must** include the following label:
+Save this as `google-oidc.yaml`, with your client ID and hostname:
```yaml
-networking.datumapis.com/gateway-sync: "true"
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+ name: ALB_NAME-oidc
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ oidc:
+ provider:
+ issuer: https://accounts.google.com
+ clientID: 1234567890-abc123.apps.googleusercontent.com
+ clientSecret:
+ name: ALB_NAME-oidc
+ redirectURL: https://app.example.com/oauth2/callback
+ logoutPath: /logout
+ scopes:
+ - openid
+ - email
+ - profile
```
-### Why this matters
-
-- Without this label, the gateway receives the policy but **not the Secret**
-- [Envoy](/platform/envoy) fails to load the OAuth client credentials
-- All requests return **HTTP 500** instead of redirecting to Google
-
-This requirement exists to prevent accidental replication of unrelated secrets.
-
----
-
-## Configuration steps
-
-### Step 1: Create Google OAuth 2.0 credentials
-
-1. Go to [Google Cloud Console](https://console.cloud.google.com) → **APIs & Services** → **Credentials**
-2. Select **Create Credentials** → **OAuth 2.0 Client ID**
-3. Set **Application type** to **Web application**
-4. Under **Authorized redirect URIs**, add:
- ```
- https:///oauth2/callback
- ```
- Replace `` with the public hostname of your `HTTPRoute`.
-5. Select **Create** and copy the **Client ID** and **Client Secret**
-
-> **Note:** The redirect URI must exactly match the value you will configure in the `SecurityPolicy`. Any mismatch causes Google to reject the OAuth flow.
-
----
-
-### Step 2: Set variables
-
-
-
-
- ```bash
- project="your-project-id"
- namespace="default"
- route="your-route-name"
- hostname="your-app.example.com"
- clientID="your-client-id.apps.googleusercontent.com"
- clientSecret="your-client-secret"
- ```
-
-
-
-
- ```powershell
- $project = "your-project-id"
- $namespace = "default"
- $route = "your-route-name"
- $hostname = "your-app.example.com"
- $clientID = "your-client-id.apps.googleusercontent.com"
- $clientSecret = "your-client-secret"
- ```
-
-
-
-
----
-
-### Step 3: Create the client secret
-
-The Secret must:
-
-- Use the key `client-secret`
-- Exist in the same namespace as the `SecurityPolicy`
-- Include the **gateway-sync** label
-
-
-
-
- ```bash
- b64Secret=$(printf "%s" "$clientSecret" | base64)
-
- cat <
-
-
- ```powershell
- $b64Secret = [Convert]::ToBase64String(
- [Text.Encoding]::UTF8.GetBytes($clientSecret)
- )
-
- @"
- apiVersion: v1
- kind: Secret
- metadata:
- name: ${route}-oidc-secret
- labels:
- networking.datumapis.com/gateway-sync: "true"
- type: Opaque
- data:
- client-secret: $b64Secret
- "@ | datumctl apply --project $project --namespace $namespace -f -
- ```
-
-
-
-
----
-
-### Step 4: Attach OIDC authentication using a SecurityPolicy
-
-Attach the policy to the **HTTPRoute**. This is the most reliable attachment point.
-
-
-
-
- ```bash
- cat <
-
-
- ```powershell
- @"
- apiVersion: gateway.envoyproxy.io/v1alpha1
- kind: SecurityPolicy
- metadata:
- name: ${route}-oidc
- spec:
- targetRefs:
- - group: gateway.networking.k8s.io
- kind: HTTPRoute
- name: $route
- oidc:
- provider:
- issuer: "https://accounts.google.com"
- clientID: "$clientID"
- clientSecret:
- name: ${route}-oidc-secret
- redirectURL: "https://${hostname}/oauth2/callback"
- scopes:
- - openid
- - email
- - profile
- "@ | datumctl apply --project $project --namespace $namespace -f -
- ```
-
-
-
-
----
-
-## Verification
-
-### Unauthenticated request
-
```bash
-curl -I https://your-app.example.com
-```
-
-Expected response:
-
-```
-HTTP/1.1 302 Found
-Location: https://accounts.google.com/o/oauth2/v2/auth?...
+datumctl apply -f google-oidc.yaml
```
-Browsers will redirect automatically to the Google sign-in page.
+Allow up to a minute for the policy to reach every location.
----
-
-### Authenticated session
-
-After completing the Google sign-in flow, subsequent requests will be forwarded to your origin with a session cookie managed by Envoy.
+## Step 4: Check it
```bash
-curl -I https://your-app.example.com
+curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' https://app.example.com/
```
-Expected response after authentication:
-
-```
-HTTP/1.1 200 OK
-```
-
----
+An anonymous request returns `302` to `https://accounts.google.com/o/oauth2/v2/auth?...`. In a browser, sign in with Google, and you land on your app.
-## Cleanup / disable OIDC authentication
+## Restrict who can sign in
-
-
+To decide who gets in at the load balancer, add a `jwt` block that checks the ID token Google returned, and an `authorization` rule on its claims. Replace the policy from Step 3 with this one:
- ```bash
- datumctl delete securitypolicy ${route}-oidc \
- --project $project --namespace $namespace --ignore-not-found
-
- datumctl delete secret ${route}-oidc-secret \
- --project $project --namespace $namespace --ignore-not-found
- ```
-
-
-
-
- ```powershell
- datumctl delete securitypolicy ${route}-oidc `
- --project $project --namespace $namespace --ignore-not-found
-
- datumctl delete secret ${route}-oidc-secret `
- --project $project --namespace $namespace --ignore-not-found
- ```
+```yaml
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+ name: ALB_NAME-oidc
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ oidc:
+ provider:
+ issuer: https://accounts.google.com
+ clientID: 1234567890-abc123.apps.googleusercontent.com
+ clientSecret:
+ name: ALB_NAME-oidc
+ redirectURL: https://app.example.com/oauth2/callback
+ logoutPath: /logout
+ scopes: [openid, email, profile]
+ cookieNames:
+ idToken: id-token # a fixed name, so the jwt block can find it
+ jwt:
+ providers:
+ - name: google
+ issuer: https://accounts.google.com
+ audiences:
+ - 1234567890-abc123.apps.googleusercontent.com # your client ID
+ remoteJWKS:
+ uri: https://www.googleapis.com/oauth2/v3/certs
+ extractFrom:
+ cookies: [id-token]
+ claimToHeaders:
+ - claim: email
+ header: X-User-Email
+ authorization:
+ defaultAction: Deny
+ rules:
+ - name: our-workspace
+ action: Allow
+ principal:
+ jwt:
+ provider: google
+ claims:
+ - name: hd
+ values: ["example.com"]
+```
-
-
+People outside the rule can still sign in with Google, but they get `403` from the load balancer. Your origin receives each allowed person's address in `X-User-Email`.
----
+Choose the claim to match:
-## Troubleshooting
+| To allow | Claim | Values |
+| --- | --- | --- |
+| Everyone in a Google Workspace domain | `hd` | `["example.com"]`. Only Workspace accounts carry `hd`, so personal Gmail accounts are refused. |
+| Specific people | `email` | `["alice@example.com", "bob@example.com"]` |
+| Specific people, by an ID that never changes | `sub` | Google's numeric account IDs |
-### Common failure modes
+Values match exactly, with no wildcards, so `*@example.com` matches no one. To allow several domains, list them all in `values`. For more rules, see [Authorization rules](/alb/authentication/authorization).
-| Symptom | Root cause | Resolution |
-|---------|------------|------------|
-| HTTP 500 on all requests | Secret not synced to edge | Add `gateway-sync` label |
-| Redirect loop | Redirect URI mismatch | Ensure `redirectURL` matches Google Console exactly |
-| `redirect_uri_mismatch` from Google | URI not registered | Add URI to Google Cloud Credentials |
-| HTTP 401 after login | Scopes insufficient | Verify `openid` scope is included |
-| Works after deleting policy | Invalid Secret reference | Fix Secret name and `gateway-sync` label |
+Google's access token isn't a JWT, so the `jwt` block reads the **ID token** cookie, as above, not the `Authorization` header.
----
+## Remove Google sign-in
-### Useful debug commands
+Delete the policy and the Secret while the load balancer still exists:
```bash
-datumctl get secret --project $project --namespace $namespace
-datumctl get securitypolicy --project $project --namespace $namespace
-datumctl get httproute --project $project --namespace $namespace
+datumctl delete securitypolicy ALB_NAME-oidc
+datumctl delete secret ALB_NAME-oidc
```
----
-
-## Best practices
-
-- Register **separate OAuth clients** for each environment (dev, staging, prod)
-- Restrict **authorized redirect URIs** to known hostnames only
-- Limit **OAuth scopes** to the minimum required (`openid`, `email`)
-- Rotate the **client secret** periodically and re-apply the Secret
-- Use OIDC for production — Basic Auth is suited for development and demos
+## Troubleshooting
----
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `500` on every request | The Secret is missing the `gateway-sync` label, or its name doesn't match `clientSecret.name`. | Add the label, and check the name. |
+| `Error 400: redirect_uri_mismatch` from Google | The redirect URL isn't registered. | Add `redirectURL` exactly to **Authorized redirect URIs**. |
+| A redirect loop after signing in | `redirectURL` uses a different hostname than the one in the browser. | Use one hostname, and set `redirectURL` to it. |
+| `403` after signing in, for everyone | The ID token cookie name doesn't match `extractFrom`, or `audiences` isn't your client ID. | Set `cookieNames.idToken` and `extractFrom.cookies` to the same name. Check `audiences`. |
+| `403` for a personal Gmail account | The `hd` rule is working. Gmail accounts have no `hd` claim. | Allow them by `email` instead, if they should get in. |
+| `401` after signing in | The `openid` scope is missing, or the client secret is wrong. | Include `openid`, and re-create the Secret. |
-## Summary
+## Good practice
-- Google OAuth is configured using **Envoy Gateway `SecurityPolicy`** with an `oidc` block
-- The client secret is stored as a Kubernetes Secret with key **`client-secret`**
-- Secrets **must be explicitly synced** to edge clusters using the `networking.datumapis.com/gateway-sync: "true"` label
-- The **`redirectURL`** in the policy must exactly match the URI registered in Google Cloud Console
-- Attaching policies to `HTTPRoute` is the most reliable approach
+- Register a separate OAuth client for each environment, such as staging and production.
+- Register only the redirect URIs you use.
+- Rotate the client secret from time to time, then apply the Secret again.
diff --git a/alb/authentication/oidc.mdx b/alb/authentication/oidc.mdx
new file mode 100644
index 0000000..254b357
--- /dev/null
+++ b/alb/authentication/oidc.mdx
@@ -0,0 +1,200 @@
+---
+title: "Sign in with OIDC"
+sidebarTitle: "OIDC (any provider)"
+description: "Require people to sign in with any OpenID Connect provider, such as Okta, Microsoft Entra ID, Keycloak, Google, or Auth0, before requests reach your origin."
+---
+
+OIDC sign-in sends people without a session to your identity provider, then lets them through once they sign in. [Envoy](/platform/envoy) runs the whole OAuth 2.0 flow at the edge and keeps the session in an encrypted cookie, so your app needs no changes.
+
+Any provider that follows [OpenID Connect](https://openid.net/connect/) works, including Okta, Microsoft Entra ID, Keycloak, Authentik, Dex, Google, and Auth0. The Datum side is the same for all of them. Only the issuer URL and the client you register change. For provider-specific steps, see [Google](/alb/authentication/oidc-google) and [Auth0](/alb/authentication/oidc-auth0).
+
+## How it works
+
+```mermaid
+sequenceDiagram
+ autonumber
+ participant B as Browser
+ participant E as Envoy (your ALB)
+ participant I as Identity provider
+ participant App as Your app
+ B->>E: GET /app
+ E-->>B: No session: 302 to the provider
+ B->>I: Sign in
+ I-->>B: 302 to /oauth2/callback with a code
+ B->>E: GET /oauth2/callback
+ E->>I: Exchange the code for tokens
+ Note over E: Validate the ID token:
signature, issuer, audience, expiry
+ E-->>B: Session cookies, 302 to /app
+ B->>E: GET /app
+ E->>App: Forward the request
+ App-->>B: 200 OK
+```
+
+Envoy fetches the provider's settings from `ISSUER/.well-known/openid-configuration`, so it has to reach the issuer over the public internet.
+
+## Before you start
+
+- **A stable hostname.** The redirect URL is registered with your provider and must match exactly. Use a [custom hostname](/alb/operations/custom-domains) rather than the generated `*.datumproxy.net` name, so you don't have to re-register it if the load balancer changes.
+- **An identity provider reachable from the internet over HTTPS**, with its discovery document at `ISSUER/.well-known/openid-configuration`.
+
+## Step 1: Register a client with your provider
+
+In your provider, create a **confidential** web application client (sometimes called a regular web application) that uses the authorization code flow, and:
+
+1. Add the redirect URL `https://HOSTNAME/oauth2/callback`.
+2. Note the **issuer URL**, the **client ID**, and the **client secret**.
+
+| Provider | Issuer URL |
+| --- | --- |
+| Google | `https://accounts.google.com` |
+| Auth0 | `https://YOUR_TENANT.auth0.com` |
+| Okta | `https://YOUR_DOMAIN.okta.com/oauth2/default`, or your custom authorization server |
+| Microsoft Entra ID | `https://login.microsoftonline.com/TENANT_ID/v2.0` |
+| Keycloak | `https://KEYCLOAK_HOST/realms/REALM` |
+
+Use the issuer exactly as the provider's discovery document lists it. When a `jwt` block checks tokens from the same provider, its `issuer` must match the tokens' `iss` claim character for character, including any trailing slash.
+
+## Step 2: Store the client secret
+
+The Secret must use the key `client-secret` and carry the `gateway-sync` label. Save this as `oidc-secret.yaml`:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+ name: ALB_NAME-oidc
+ labels:
+ networking.datumapis.com/gateway-sync: "true"
+type: Opaque
+stringData:
+ client-secret: YOUR_CLIENT_SECRET
+```
+
+```bash
+datumctl apply -f oidc-secret.yaml
+```
+
+Keep the file out of Git, or generate it in CI from your secret manager.
+
+## Step 3: Apply the SecurityPolicy
+
+Save this as `oidc.yaml`, with your own issuer, client ID, and hostname:
+
+```yaml
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+ name: ALB_NAME-oidc
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+ oidc:
+ provider:
+ issuer: https://idp.example.com/realms/corp
+ clientID: alb-app
+ clientSecret:
+ name: ALB_NAME-oidc
+ redirectURL: https://app.example.com/oauth2/callback
+ logoutPath: /logout
+ scopes:
+ - openid
+ - email
+ - profile
+ forwardAccessToken: true
+```
+
+```bash
+datumctl apply -f oidc.yaml
+```
+
+Make sure your provider is up before you apply the policy. If Envoy can't load the discovery document when the policy arrives, every request returns `500` until you delete and reapply the policy.
+
+| Field | What it does |
+| --- | --- |
+| `provider.issuer` | Your provider's issuer URL |
+| `clientID`, `clientSecret` | The client from Step 1. `clientSecret` names the Secret from Step 2. |
+| `redirectURL` | Where the provider sends people back. Must match the URL registered in Step 1. Defaults to `/oauth2/callback` on the requested host. |
+| `logoutPath` | A path that clears the session cookies and redirects to `/`, such as `/logout` |
+| `scopes` | Scopes to request. `openid` is always added. Add `email` and `profile` to get those claims. |
+| `forwardAccessToken` | Sends the provider's access token to your origin as `Authorization: Bearer` |
+| `refreshToken` | Uses the refresh token to renew the session when the access token expires, instead of sending the person to sign in again |
+| `cookieNames.idToken` | Fixes the ID token cookie's name, so a `jwt` block can read it. See [Restrict who can sign in](#restrict-who-can-sign-in). |
+| `passThroughAuthHeader` | Lets requests that already carry a valid `Authorization: Bearer` token skip the sign-in redirect, so scripts and services can call the same hostname as people. Needs a `jwt` block that accepts those tokens. A request with an invalid token gets `401`, not a redirect. |
+| `denyRedirect` | Returns `401` instead of a redirect for requests without a session that match given headers, such as `Accept: application/json` from a single-page app's API calls |
+
+Field names follow [Envoy Gateway's OIDC reference](https://gateway.envoyproxy.io/docs/api/extension_types/#oidc).
+
+## Step 4: Check it
+
+```bash
+curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' https://app.example.com/
+```
+
+An anonymous request returns `302` to your provider's sign-in page. Open the URL in a browser, sign in, and you land on your app.
+
+## Restrict who can sign in
+
+The `oidc` block alone lets in **anyone your provider will sign in**. With Google, that's anyone with a Google account. To decide who is allowed in at the load balancer, add a `jwt` block that reads the ID token from its cookie, and an `authorization` rule on its claims, in the same policy:
+
+```yaml
+spec:
+ oidc:
+ # ...as above, plus a fixed name for the ID token cookie:
+ cookieNames:
+ idToken: id-token
+ jwt:
+ providers:
+ - name: idp
+ issuer: https://idp.example.com/realms/corp
+ audiences: ["alb-app"] # your client ID
+ remoteJWKS:
+ uri: https://idp.example.com/realms/corp/protocol/openid-connect/certs
+ extractFrom:
+ cookies: ["id-token"]
+ claimToHeaders:
+ - claim: email
+ header: X-User-Email
+ authorization:
+ defaultAction: Deny
+ rules:
+ - name: allowed-people
+ action: Allow
+ principal:
+ jwt:
+ provider: idp
+ claims:
+ - name: email
+ values: ["alice@example.com", "bob@example.com"]
+```
+
+Find `remoteJWKS.uri` as `jwks_uri` in your provider's discovery document. People who sign in but don't match a rule get `403`. You can allow by email, by group or role, or by a Google Workspace domain. See [Authorization rules](/alb/authentication/authorization) for what a rule can match.
+
+## Sessions and signing out
+
+- **The session lasts as long as the provider's tokens.** When the access token expires, Envoy refreshes it if `refreshToken` is on, or sends the person to sign in again.
+- **Disabling someone at the provider ends their session** at the next refresh or sign-in, so within one access-token lifetime. Short access-token lifetimes, such as 5 to 15 minutes, make removal faster.
+- **Signing out** with `logoutPath` clears the cookies at the load balancer. It doesn't sign the person out of the provider, so they may sign straight back in.
+
+## Several sign-in policies on one hostname
+
+If two routes on the same hostname each have their own OIDC policy, give each a **different** `redirectURL` path, such as `/oauth2/callback` and `/admin/oauth2/callback`, and register both with your provider. If they share a callback path, the callback can land on the other route's policy and fail with `401 OAuth flow failed`.
+
+## Running your own identity provider
+
+You can run an identity provider such as Keycloak yourself. Two things to know:
+
+- **Host it outside Datum for now.** When the issuer is itself served through a Datum load balancer, some token exchanges from the edge fail, and sign-in returns `401 OAuth flow failed` after about 10 seconds. An issuer hosted elsewhere doesn't have this problem.
+- **Behind a reverse proxy**, make the provider use the public hostname in its URLs. For Keycloak, set `KC_HOSTNAME` to the public URL and `KC_PROXY_HEADERS=xforwarded`. If the `issuer` in its discovery document doesn't match the policy, sign-in fails.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `500` on every request | The Secret is missing the `gateway-sync` label, or the provider was unreachable when the policy arrived. | Fix the label. Check the discovery URL, then delete and reapply the policy. |
+| `redirect_uri_mismatch` or a similar provider error | The redirect URL isn't registered with the provider. | Register `redirectURL` exactly. |
+| A redirect loop after signing in | `redirectURL` points at a different hostname than the one the person used. | Use one hostname, and set `redirectURL` to it. |
+| `401 OAuth flow failed` after signing in | The code exchange failed: a wrong client secret, a callback shared with another policy, or an issuer served through a Datum load balancer. | Check the secret, give each policy its own callback path, or host the issuer outside Datum. |
+| `403` after signing in | An authorization rule doesn't match, or the claim it checks isn't in the ID token. | Decode the ID token and compare its claims with the rule. Request the scopes that add the claim. |
+| `200` without signing in | The policy isn't attached, or another policy already targets the route. | Check `targetRefs`, and run `datumctl describe securitypolicy` to look for `Conflicted`. |
diff --git a/alb/authentication/overview.mdx b/alb/authentication/overview.mdx
index 48519fd..1159dfd 100644
--- a/alb/authentication/overview.mdx
+++ b/alb/authentication/overview.mdx
@@ -1,40 +1,47 @@
---
title: "Authentication"
sidebarTitle: "Overview"
-description: "Require people to sign in before requests reach your origin, with basic authentication, Google sign-in, or per-user access through Auth0."
+description: "Check who is calling before requests reach your origin: Basic Auth, API keys, JWT, or sign-in with any OIDC provider, plus rules that decide who is allowed in."
---
-A load balancer can require people to prove who they are before a request ever reaches your origin. [Envoy](/platform/envoy) checks every request at the edge, in every Datum location, so your app doesn't need to change and unauthenticated traffic never reaches it.
+A load balancer can check who is calling before a request ever reaches your origin. [Envoy](/platform/envoy) checks every request at the edge, in every Datum location, so your app doesn't need to change and unauthenticated traffic never reaches it.
## Choose a method
-| Method | Who can get in | Best for | Guide |
+| Method | Who it identifies | Best for | Guide |
| --- | --- | --- | --- |
-| Basic authentication | Anyone with a username and password you set | Staging sites, internal tools, and quick protection for anything | [Basic authentication](/alb/authentication/basic-auth) |
-| Sign in with Google (OIDC) | Anyone who signs in with a Google account | Requiring a real identity, such as for a team that uses Google Workspace | [Sign in with Google](/alb/authentication/oidc-google) |
-| Per-user access with Auth0 | Only the people on your allow-list | Controlling exactly which people get in, by email address | [Per-user access with Auth0](/alb/authentication/oidc-auth0) |
+| Basic Auth | A username from a list you keep | Staging sites, internal tools, and quick protection for anything | [Basic Auth](/alb/authentication/basic-auth) |
+| API keys | A named client, such as `ci-pipeline` or `partner-acme` | Scripts, CI jobs, partners, and other machine clients | [API keys](/alb/authentication/api-keys) |
+| JWT | Any user or service your token issuer signs for | APIs called with a bearer token from your own identity provider | [JWT](/alb/authentication/jwt) |
+| Sign-in with OIDC | A person who signs in with your identity provider in a browser | Web apps and internal tools used by people | [Sign in with OIDC](/alb/authentication/oidc) |
-The quickest way to start is basic authentication with `datumctl alb`:
+OIDC works with any OpenID Connect provider, such as Google, Auth0, Okta, Microsoft Entra ID, or Keycloak. There are step-by-step guides for [Google](/alb/authentication/oidc-google) and [Auth0](/alb/authentication/oidc-auth0).
+
+On top of any method, you can decide **who is allowed in**, with [authorization rules](/alb/authentication/authorization) on token claims (such as an email address, a Google Workspace domain, or a role), request headers, HTTP methods, or client IP ranges. A browser app on another origin can call your API once you allow it with [CORS](/alb/authentication/cors).
+
+The quickest way to start is Basic Auth with `datumctl alb`:
```bash
printf '%s' "$password" | datumctl alb auth set ALB_NAME --user admin --password-stdin
```
+Basic Auth is the only method `datumctl alb` sets up. Every other method is a `SecurityPolicy` manifest that you apply with `datumctl apply`.
+
## How it works
-Authentication is configured with an [Envoy Gateway](https://gateway.envoyproxy.io/) `SecurityPolicy`. The policy names what it protects, such as a load balancer's route, and how people sign in. Datum sends the policy to Envoy in every location, and Envoy enforces it on every request:
+Authentication is configured with an [Envoy Gateway](https://gateway.envoyproxy.io/) `SecurityPolicy`. The policy names what it protects, a load balancer's route, and how callers prove who they are. Datum sends the policy to Envoy in every location, and Envoy enforces it on every request:
```mermaid
flowchart LR
B["Browser or client"]
E["Envoy · your ALB
checks the SecurityPolicy"]
- I["Identity provider
Google or Auth0"]
+ I["Identity provider
OIDC sign-in, or token keys"]
O["Your origin"]
B -->|"request"| E
E -.->|"no session: sign in"| I
I -.->|"token"| E
- E -->|"signed in: forward"| O
+ E -->|"allowed: forward"| O
classDef box fill:#E6E6E6,stroke:#8A8E99,color:#222
class B,E,I,O box
@@ -42,14 +49,60 @@ flowchart LR
linkStyle 1,2 stroke:#B5605E,stroke-width:1.4px,stroke-dasharray:5 4
```
-- **Basic authentication** checks a username and password against an `htpasswd` list stored in a Secret. A request without valid credentials gets `401 Unauthorized`.
-- **OIDC** redirects people without a session to an identity provider, such as Google or Auth0. Envoy validates the token the provider returns, then sets a session cookie so later requests go straight through.
+- **Basic Auth** checks a username and password against an `htpasswd` list stored in a Secret.
+- **API keys** checks a key in a header, query parameter, or cookie against keys stored in a Secret. The key's name in the Secret identifies the client.
+- **JWT** checks the signature, issuer, audience, and expiry of a bearer token against your issuer's public keys. Datum never sees your users.
+- **OIDC** redirects people without a session to your identity provider. Envoy validates the token the provider returns, then sets a session cookie so later requests go straight through.
+
+### Where a SecurityPolicy attaches
+
+When you create a load balancer, Datum creates a Gateway and an `HTTPRoute` with the same name as the load balancer. A `SecurityPolicy` targets that route:
+
+```yaml
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME
+```
+
+A route takes **one** `SecurityPolicy`. To combine methods, such as OIDC sign-in with a claim rule and CORS, put them all in the same policy. A second policy on the same route is rejected with the condition `Conflicted`, and the first one stays in force.
+
+A policy can also target the load balancer's Gateway, which also has the load balancer's name. `datumctl alb auth set` does this. A Gateway policy covers every route that has no policy of its own. A route's own policy **replaces** the Gateway's policy for that route. The two aren't merged.
+
+
+ If you protect a load balancer with `datumctl alb auth set` and then add any route-level policy, even one with only CORS, Basic Auth stops applying to that route. `datumctl alb describe` still shows Basic Auth as enabled. Put `basicAuth` in the route's policy instead. See [Basic Auth](/alb/authentication/basic-auth).
+
+
+The policy covers every path on the route. To protect paths differently, such as `/api` with API keys and the rest with OIDC, add a route for that path and give it its own policy. See [Different authentication per path](/alb/authentication/per-path).
-Authentication runs alongside the [web application firewall](/alb/configuration/waf). A request has to pass both before it reaches your origin.
+### What the origin receives
+
+Once a request is allowed, Envoy can pass the caller's identity to your origin in a header, so your app knows who is calling without checking credentials itself:
+
+| Method | Identity at the origin |
+| --- | --- |
+| Basic Auth | The username in a header you name (`forwardUsernameHeader`). The `Authorization` header, with the password, is also forwarded. |
+| API keys | The client's name in a header you name (`forwardClientIDHeader`). Set `sanitize: true` to strip the key itself. |
+| JWT | Any claims you choose, each in its own header (`claimToHeaders`), plus the original `Authorization` header |
+| OIDC | The provider's access token as `Authorization: Bearer` (`forwardAccessToken: true`), and claims from the ID token with a `jwt` block |
+
+Envoy sets these headers itself and overwrites any value the client sent, so a client can't spoof them.
+
+### Order of checks
+
+The [web application firewall](/alb/configuration/waf) runs first. A request it blocks gets `403` before authentication runs. A request then has to pass authentication and any authorization rules before it reaches your origin.
+
+| Response | Meaning |
+| --- | --- |
+| `302` | No OIDC session. The browser is sent to sign in. |
+| `401` | Missing or invalid credentials: no password, a wrong key, or an expired or forged token |
+| `403` | Valid credentials that aren't allowed in, because of an authorization rule or a token for a different audience. Also returned by the firewall. |
+| `500` | The policy can't load what it needs, such as an unlabeled Secret or an identity provider that was unreachable when the policy was applied |
## Secrets must be labeled to reach the edge
-Each method stores a credential in a Secret: an `htpasswd` list for basic authentication, or a client secret for OIDC. Datum doesn't send Secrets to the edge unless you ask it to, so that unrelated Secrets in your project are never copied. To make a Secret available to your load balancer, give it this label:
+Basic Auth, API keys, and OIDC each store a credential in a Secret: an `htpasswd` list, a set of keys, or an OIDC client secret. Datum doesn't send Secrets to the edge unless you ask it to, so that unrelated Secrets in your project are never copied. To make a Secret available to your load balancer, give it this label:
```yaml
metadata:
@@ -58,12 +111,21 @@ metadata:
```
- Without this label, Envoy receives the policy but not the Secret, and every request to the load balancer returns `500` instead of asking people to sign in. `datumctl alb auth set` adds the label for you.
+ Without this label, Envoy receives the policy but not the Secret, and every request to the load balancer returns `500` instead of asking for credentials. `datumctl alb auth set` adds the label for you.
+JWT doesn't need a Secret: Envoy fetches your issuer's public keys, or reads them from the policy.
+
## Check authentication
-To see whether a load balancer has basic authentication, run `datumctl alb describe ALB_NAME`. To see every `SecurityPolicy` in your project, run `datumctl get securitypolicies`.
+`datumctl alb describe ALB_NAME` shows only Basic Auth set up by `datumctl alb auth`, and keeps showing it even when a route-level policy has replaced it. It doesn't show a `SecurityPolicy` you applied yourself, or routes you added. To see every policy in your project and whether it was accepted, run:
+
+```bash
+datumctl get securitypolicies
+datumctl describe securitypolicy POLICY_NAME
+```
+
+`Accepted=False` with the reason `Conflicted` means another policy already targets the same route.
To confirm that a protected load balancer rejects anonymous requests, request it without credentials:
@@ -71,12 +133,24 @@ To confirm that a protected load balancer rejects anonymous requests, request it
curl -s -o /dev/null -w '%{http_code}\n' https://HOSTNAME/
```
-Basic authentication returns `401`. OIDC returns `302`, a redirect to the sign-in page.
+Basic Auth, API keys, and JWT return `401`. OIDC returns `302`, a redirect to the sign-in page.
+
+Authentication outcomes show up in [access logs](/alb/observability) only as response codes. There are no metrics or log fields for who signed in, which key was used, or why a token was rejected.
| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Every request returns `500` | The Secret isn't labeled to reach the edge, or its name is wrong. | Add the `gateway-sync` label, and check the Secret name in the policy. |
-| Requests reach the origin without signing in | The policy targets a different route or load balancer. | Check `targetRefs` in the policy. |
+| Every request returns `500` with OIDC | The identity provider was unreachable when the policy was applied. | Make sure the provider's discovery URL answers, then delete and reapply the policy. |
+| Requests reach the origin without credentials | The policy targets a different route, it was rejected as `Conflicted`, or a route-level policy replaced Basic Auth from `alb auth set`. | Check `targetRefs`, and run `datumctl describe securitypolicy`. Put every setting for a route in one policy. |
| A redirect loop after signing in | The redirect URL doesn't match the one registered with the provider. | Make the two match exactly. |
+| A valid token gets `403` | An authorization rule doesn't match, or the token's audience isn't in `audiences`. | Decode the token and compare its claims with the policy. |
For more, see the troubleshooting section of each guide.
+
+## What isn't available
+
+- **Client certificates (mutual TLS).** A load balancer can't ask clients for a certificate. `ClientTrafficPolicy` isn't available, and the Gateway's TLS settings can't be changed.
+- **Your own authorization service (`extAuth`).** A policy can't call out to an external service to decide on each request. The API rejects it with `extAuth is not permitted`.
+- **Retries to the identity provider.** If your issuer is briefly unreachable, Envoy doesn't retry. The API rejects retry settings.
+- **Location-based rules.** Authorization rules can match client IP ranges but not countries.
+- **Datum platform credentials.** The tokens that `datumctl` and [service accounts](/projects/service-accounts) use to call the Datum API are for the platform, not for your apps. Use your own identity provider to protect your workloads.
diff --git a/alb/authentication/per-path.mdx b/alb/authentication/per-path.mdx
new file mode 100644
index 0000000..a82f9e3
--- /dev/null
+++ b/alb/authentication/per-path.mdx
@@ -0,0 +1,110 @@
+---
+title: "Different authentication per path"
+sidebarTitle: "Per-path authentication"
+description: "Protect different paths of one Datum load balancer with different methods, such as OIDC for people and API keys or JWT for machines."
+---
+
+A `SecurityPolicy` protects a whole route. A load balancer starts with one route, named after the load balancer, that serves every path. To protect a path differently, add a second route for that path and give it its own policy. The most specific path wins, so requests to that path use the new route and its policy, and everything else stays on the original route.
+
+A common setup:
+
+| Path | Route | Policy |
+| --- | --- | --- |
+| `/` | `ALB_NAME`, created with the load balancer | [OIDC](/alb/authentication/oidc) for people using the web app |
+| `/api` | `ALB_NAME-api`, added by you | [API keys](/alb/authentication/api-keys) or [JWT](/alb/authentication/jwt) for machines |
+| `/healthz` | `ALB_NAME-health`, added by you | No policy, so it's open to uptime monitors |
+
+## Step 1: Copy the backend from the load balancer's route
+
+The new route sends traffic to the same origin, so copy its `backendRefs` and `filters` from the load balancer's route:
+
+```bash
+datumctl get httproute ALB_NAME -o yaml
+```
+
+Look for the rule with `backendRefs`. It looks like this:
+
+```yaml
+ - backendRefs:
+ - group: discovery.k8s.io
+ kind: EndpointSlice
+ name: ALB_NAME-1-0
+ port: 443
+ weight: 1
+ filters:
+ - type: URLRewrite
+ urlRewrite:
+ hostname: origin.example.com
+ matches:
+ - path:
+ type: PathPrefix
+ value: /
+```
+
+## Step 2: Add a route for the path
+
+Save this as `api-route.yaml`, with the `backendRefs` and `filters` you copied:
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ name: ALB_NAME-api
+spec:
+ parentRefs:
+ - group: gateway.networking.k8s.io
+ kind: Gateway
+ name: ALB_NAME
+ rules:
+ - matches:
+ - path:
+ type: PathPrefix
+ value: /api
+ filters:
+ - type: URLRewrite
+ urlRewrite:
+ hostname: origin.example.com
+ backendRefs:
+ - group: discovery.k8s.io
+ kind: EndpointSlice
+ name: ALB_NAME-1-0
+ port: 443
+```
+
+```bash
+datumctl apply -f api-route.yaml
+```
+
+The route attaches to the load balancer's Gateway, which has the same name as the load balancer, and serves all of its hostnames.
+
+## Step 3: Attach a policy to the new route
+
+Point a policy's `targetRefs` at the new route, for example the API key policy from [API keys](/alb/authentication/api-keys):
+
+```yaml
+spec:
+ targetRefs:
+ - group: gateway.networking.k8s.io
+ kind: HTTPRoute
+ name: ALB_NAME-api
+ apiKeyAuth:
+ # ...
+```
+
+To leave a path open, add a route for it and attach no policy. A route without its own policy is still covered by a policy on the Gateway, such as the one `datumctl alb auth set` creates. To keep a path open in that case, attach a policy to its route that has only a `cors` block.
+
+## Check it
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' https://HOSTNAME/ # 302: OIDC sign-in
+curl -s -o /dev/null -w '%{http_code}\n' https://HOSTNAME/api # 401: no API key
+curl -s -o /dev/null -w '%{http_code}\n' -H "x-api-key: $KEY" https://HOSTNAME/api # 200
+```
+
+## Things to know
+
+- **`datumctl alb` and the portal don't show routes you add yourself.** `datumctl alb describe` lists only the load balancer's own routes. List all routes with `datumctl get httproutes`.
+- **Origin changes don't reach your route.** If you change the load balancer's origin with `datumctl alb` or the portal, the backend name in your route may change. Copy it again.
+- **The path isn't removed.** A request to `/api/orders` reaches your origin as `/api/orders`.
+- **Each OIDC policy needs its own callback path** when two routes on one hostname both use OIDC. See [Several sign-in policies on one hostname](/alb/authentication/oidc#several-sign-in-policies-on-one-hostname).
+- **Delete your routes, policies, and Secrets before the load balancer.** `datumctl alb delete` doesn't remove resources you created. Routes you add are left behind with no Gateway.
diff --git a/alb/configuration/overview.mdx b/alb/configuration/overview.mdx
index 2eb55f7..b138c0d 100644
--- a/alb/configuration/overview.mdx
+++ b/alb/configuration/overview.mdx
@@ -20,5 +20,5 @@ In the [Cloud Portal](https://cloud.datum.net), a load balancer's **Configuratio
| A custom domain with `datumctl` | [Serve traffic on your own domain](/alb/operations/custom-domains) |
| Several origins and path routes with `datumctl` | [Send paths to different origins](/alb/operations/routes) |
| Origin weights, the load balancing algorithm, and passive health checks | [Load balancing and health checks](/alb/configuration/load-balancing) |
-| Basic or OIDC authentication | [Authentication](/alb/authentication/overview) |
+| Basic Auth, API keys, JWT, OIDC sign-in, authorization rules, and CORS | [Authentication](/alb/authentication/overview) |
| Failover between a primary and a fallback origin | [Failover](/alb/configuration/failover) |
diff --git a/alb/limitations-and-roadmap.mdx b/alb/limitations-and-roadmap.mdx
index f219230..ff01a10 100644
--- a/alb/limitations-and-roadmap.mdx
+++ b/alb/limitations-and-roadmap.mdx
@@ -17,6 +17,12 @@ The Application Load Balancer is still being built. This page lists known limita
- Status shows when a change is published, not when every location serves it, and there is no per-location status. See [When a load balancer is not serving](/alb/troubleshooting).
- A response must finish within 15 seconds by default, including a streaming response such as Server-Sent Events (SSE) or a long MCP response. `HTTPProxy` has no timeout field. A `BackendTrafficPolicy` raises the limit to at most 1 hour. See [How long a response can stay open](/alb/request-handling#how-long-a-response-can-stay-open).
- `ClientTrafficPolicy` isn't available in projects, so client-side TLS versions, HTTP versions, and connection limits can't be changed.
+- `datumctl alb auth` and the portal set up Basic Auth only. API keys, JWT, OIDC, authorization rules, and CORS need a `SecurityPolicy` manifest, and `datumctl alb describe` doesn't show them. See [Authentication](/alb/authentication/overview).
+- A load balancer can't require client certificates (mutual TLS), and a `SecurityPolicy` can't call your own authorization service (`extAuth`) or retry requests to an identity provider.
+- There are no metrics or log fields for authentication. Access logs show only the response code, such as `401` or `403`.
+- An OIDC identity provider served through a Datum load balancer can fail some sign-ins with `401 OAuth flow failed`. Host the identity provider outside Datum for now. See [Running your own identity provider](/alb/authentication/oidc#running-your-own-identity-provider).
+- `datumctl alb auth unset` and `datumctl alb delete` leave the Basic Auth Secret behind, and deleting it can leave it in `Terminating` indefinitely.
+- `datumctl alb auth set` attaches Basic Auth to the Gateway. Any `SecurityPolicy` on one of the load balancer's routes replaces it for that route, and `datumctl alb describe` doesn't show that.
- For limits on load balancers attached to Compute workloads, see [Compute and ALB](/compute/compute-and-alb#limitations).
## Roadmap
diff --git a/alb/overview.mdx b/alb/overview.mdx
index 4ed53c6..50d076f 100644
--- a/alb/overview.mdx
+++ b/alb/overview.mdx
@@ -63,7 +63,7 @@ Application Load Balancer (product)
│ DNSRecordSet(s), and TLS certificates (ACME)
├── TrafficProtectionPolicy (created with the proxy, same name) — Coraza/OWASP WAF
│ └── targetRefs → Gateway
-└── [optional] SecurityPolicy + Secret *-basic-auth — basic authentication
+└── [optional] SecurityPolicy (+ Secret) — Basic Auth, API keys, JWT, OIDC, CORS
```
| Piece | Role |
@@ -72,7 +72,7 @@ Application Load Balancer (product)
| **`TrafficProtectionPolicy`** | WAF policy (Observe / Enforce / Disabled) attached 1:1 to the proxy's Gateway |
| **Gateway** (operator) | Provisioned from the HTTPProxy; WAF and auth policies target it |
| **DNS + TLS** (operator) | Canonical hostname, DNSRecordSets, and ACME certificates from proxy status |
-| **SecurityPolicy** (optional) | Basic Auth via [Envoy Gateway](https://gateway.envoyproxy.io/), backed by a Secret |
+| **SecurityPolicy** (optional) | Authentication and authorization via [Envoy Gateway](https://gateway.envoyproxy.io/): Basic Auth, API keys, JWT, OIDC sign-in, authorization rules, and CORS. Credentials live in a Secret. |
Portal create always POSTs an `HTTPProxy`, then attempts a matching `TrafficProtectionPolicy` (best-effort today if WAF attach fails). There's no composite ALB API yet. With `datumctl`, `datumctl alb create` creates the `HTTPProxy` and its `TrafficProtectionPolicy` for you (see [Create a load balancer](/alb/operations/overview#create-a-load-balancer)), or you can apply the resources yourself.
@@ -84,7 +84,7 @@ Each Application Load Balancer deploys with a default hostname and enforces HTTP
- **Protection** - The [**OWASP Coraza Web Application Firewall (WAF)**](https://www.coraza.io/) provides built-in protection with the [OWASP Core Rule Set](https://coreruleset.org/), running inside Envoy before requests reach your origin. A load balancer created with `datumctl alb create` starts in `Enforce` mode at sensitivity 1. A `TrafficProtectionPolicy` that doesn't set a mode runs in `Observe` mode. See [Roll out traffic protection safely](/alb/operations/traffic-protection).
- **Custom Hostnames** – Verify domains (or use already verified domain resources) to use custom hostnames with an Application Load Balancer.
-- **Basic Authentication** - Add a username and password to restrict access to an Application Load Balancer.
+- **Authentication** - Check who is calling before requests reach your origin, with Basic Auth, API keys, JWT, or sign-in with any OIDC provider, and allow only the people or clients you choose. See [Authentication](/alb/authentication/overview).
- **Load Balancing** - Split traffic across several origins by weight, choose the load balancing algorithm, and turn on passive health checks. See [Load balancing and health checks](/alb/configuration/load-balancing).
To monitor the health of your Application Load Balancers, you can use:
diff --git a/docs.json b/docs.json
index e402332..8cb26da 100644
--- a/docs.json
+++ b/docs.json
@@ -173,8 +173,14 @@
"root": "alb/authentication/overview",
"pages": [
"alb/authentication/basic-auth",
+ "alb/authentication/api-keys",
+ "alb/authentication/jwt",
+ "alb/authentication/oidc",
"alb/authentication/oidc-google",
- "alb/authentication/oidc-auth0"
+ "alb/authentication/oidc-auth0",
+ "alb/authentication/authorization",
+ "alb/authentication/cors",
+ "alb/authentication/per-path"
]
},
{
diff --git a/platform/envoy.mdx b/platform/envoy.mdx
index 208f6b4..613978e 100644
--- a/platform/envoy.mdx
+++ b/platform/envoy.mdx
@@ -95,7 +95,7 @@ Some advanced features use Envoy Gateway resources (`gateway.envoyproxy.io/v1alp
| Resource | Used for | Guide |
| --- | --- | --- |
-| `SecurityPolicy` | Basic authentication and OIDC sign-in | [Basic Auth](/alb/authentication/basic-auth), [OIDC with Google](/alb/authentication/oidc-google), [Auth0](/alb/authentication/oidc-auth0) |
+| `SecurityPolicy` | Basic Auth, API keys, JWT, OIDC sign-in, authorization rules, and CORS | [Authentication](/alb/authentication/overview) |
| `Backend` and `BackendTrafficPolicy` | Failover between a primary and a fallback origin | [Load balancer failover](/alb/configuration/failover) |
Because these are standard Envoy Gateway and Gateway API resources, the upstream [Envoy Gateway documentation](https://gateway.envoyproxy.io/docs/) is a useful reference. Not every upstream feature is available on Datum, so start from the Datum guides.