Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 135 additions & 0 deletions alb/authentication/api-keys.mdx
Original file line number Diff line number Diff line change
@@ -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"}]'
```

<Warning>
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.
</Warning>

## 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`. |
178 changes: 178 additions & 0 deletions alb/authentication/authorization.mdx
Original file line number Diff line number Diff line change
@@ -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`. |
Loading
Loading