Authentication¶
9. Authentication¶
9.1 OIDC (JWT)¶
Modelled on Vault's JWT auth roles. Each trusted issuer is configured with its
issuer URL (discovery) or explicit JWKS URL. Bindings match tokens on
bound_audiences and bound_claims (glob) and map them to roles and teams.
| Issuer | Typical subject | Use |
|---|---|---|
AWS IAM outbound identity federation (sts:GetWebIdentityToken) |
IAM role ARN | Any AWS workload: EKS Pod Identity, Lambda, CI assuming a role. Stable subject, Kubernetes only talks to AWS. |
GitHub Actions (token.actions.githubusercontent.com) |
repo:org/repo:ref:... |
CI on GitHub |
| GitLab CI | project path, ref | CI on GitLab |
| Kubernetes service account (cluster issuer) | system:serviceaccount:ns:sa |
in-cluster workloads (when AWS federation is not used) |
| Entra ID (see 9.2) | tid + oid, app roles |
Azure workloads (Managed Identity, AKS Workload Identity), Azure DevOps pipelines, humans |
Checks: signature, iss, exp/nbf (small leeway), aud must equal the gate's
configured audience (prevents replay of tokens issued for another service), maximum
token lifetime.
A binding normally acts for a fixed team. With team_from it derives the team of
each subject from a claim (anchored regex, one capture group, optional prefix), so
one binding with a subject glob covers many pipelines while ownership keeps them
apart: each pipeline only changes the RRsets its own team created. A subject whose
claim yields no valid team is not bound by that binding (fail closed). Any matching
identity can still create RRsets that do not exist yet within the role, which is the
trade-off of binding by glob (THREAT-MODEL T29).
9.2 Entra ID¶
Azure workloads authenticate with an Entra ID access token issued for the gate's app registration (audience = the gate's application id URI or client id):
| Workload | How it gets the token |
|---|---|
| Azure resource with a Managed Identity | IMDS / DefaultAzureCredential, scope api://<gate-app>/.default |
| AKS pod with Workload Identity | federated credential on a user-assigned identity, then the same scope |
| Azure DevOps pipeline | service connection in workload identity federation mode, then az account get-access-token --scope api://<gate-app>/.default (or the SDK) |
Rules:
- Bindings on app roles (
rolesclaim), defined on the gate's app registration and assigned to the identities. Not on groups: thegroupsclaim is dropped above a size limit (overage) and replaced by a Graph lookup the gate does not perform. - Stable subject =
tid+oid(tenant and object id).subis pairwise per application, andappid/azpidentify the client app, not the identity. - Actor category from
idtyp(app→ pipeline/workload,user→ human). - The issuer must be tenant-specific
(
https://login.microsoftonline.com/<tenant-id>/v2.0, or the v1https://sts.windows.net/<tenant-id>/). Multi-tenant endpoints (/common,/organizations,/consumers) are refused in configuration. - Do not trust the raw Azure DevOps OIDC token. The token ADO issues for a
service connection has a fixed audience,
api://AzureADTokenExchange, meant for the exchange with Entra. Accepting it would let any service receiving such a token replay it against the gate. The gate only accepts the Entra access token obtained after the exchange, whose audience is the gate itself.
9.3 Virtual keys¶
Static keys declared in the policy (virtual_keys, base file or managed layer) for
existing EuroDNS clients that only know X-APP-ID/X-API-KEY: X-APP-ID = key id,
X-API-KEY = high-entropy secret stored hashed. Each key grants roles and teams
directly, has an expiry, and can be bound to source CIDRs. Changing one is a policy
change; API keys (9.5) are issued, rotated and revoked at runtime instead, and work on
the same headers.
9.4 SAML users and gate-issued tokens¶
Humans may sign in to the UI with SAML 2.0 instead of OIDC (ui.saml, e.g. an AWS
IAM Identity Center custom application). The validated assertion becomes a session
exactly like an ID token: sub = NameID, mapped attributes as claims, bound under a
configured issuer name (identity-center), with optional group names looked up in
the Identity Center identity store.
Those users have no bearer token for the API, MCP or Terraform, so the gate can be its
own issuer (issuers[].self): it signs short-lived JWTs (ES256 or EdDSA, JWKS at
/.well-known/jwks.json) carrying the session claims plus gate_iss, and binds them
back as that issuer, so one set of bindings covers the session and its tokens. Tokens
come from POST /api/v1/tokens (session + CSRF) or from the OAuth authorization
server (/oauth/authorize, /oauth/token, PKCE, consent page). For the Claude
Desktop extension (dns-gate-relay, loopback redirects) it is stateless: codes and
refresh tokens are sealed with the session key, nothing is stored. Declared OAuth
clients (9.8) use persisted grants.
SAML response validation (/auth/saml/acs). Validation of the response posted to /auth/saml/acs: XML signature of the response or of the assertion with a certificate of the IdP metadata (unsigned responses refused, encrypted assertions decrypted with the SP key when configured), response Destination and assertion Recipient equal to acs_url, InResponseTo equal to the id of the AuthnRequest kept in the sealed login cookie, RelayState equal to the random state of that cookie, issuer equal to the IdP entity id, every AudienceRestriction equal to entity_id (at least one required), IssueInstant at most 90 s old, NotBefore/NotOnOrAfter with 3 minutes of clock skew, a bearer SubjectConfirmation and a non-empty NameID. The session then follows the OIDC rules: sub = NameID, mapped claims, auth_time = AuthnInstant, amr = the AuthnContextClassRef (and the amr attribute if mapped), lifetime ui.session_ttl capped by SessionNotOnOrAfter.
Replay: the gate keeps no record of the assertions it consumed (it runs stateless, also on Lambda). A response is only accepted with the login cookie of the browser that started that very login, which is cleared on first use, and within 90 s of its issuance. Someone who captured both the cookie and the response within those 90 s could replay them; TLS and the HttpOnly cookie make that a browser or proxy compromise.
9.5 API keys¶
For third parties with no OIDC identity (a hosting provider renewing certificates,
an appliance), the gate issues API keys at runtime (/api/v1/api-keys, guide in
API.md). OIDC stays the first choice; a key is a long-lived secret held
outside the organization.
- Format:
dgk_<id>_<secret>,id16 hex characters (the public key id, also the user name of basic authentication and of acme-dns),secret32 random bytes in base64url. Only the SHA-256 of the whole key is stored; the key is returned once, at creation and at each rotation. - Presentation:
Authorization: Bearer dgk_…, basic authentication (user = key id), orX-Api-Key(withX-App-IdorX-Api-User= key id when sent), so the same key serves the neutral API, the ACME endpoints and EuroDNS-header clients. - Scope: one team (owner of the RRsets it creates) and one role, optional expiry
and source CIDRs. The role may not grant
policy.*orgate.*actions, checked at creation and again at each use: a key whose role disappeared or gained such an action stops working. - Management:
gate.apikey.manage, held by a token or session identity, never by an API key or a virtual key. The key's team must be one of the caller's teams (unless the caller holds the action on*), and the caller must hold the action on every zone of the key's role, plus every action of that role on the same records: a key never exceeds its issuer. - Rotation and revocation: a rotation issues a new secret and keeps the previous
one valid for an overlap (default 24 h, at most 30 days,
0sfor none); a revocation is immediate. Team and role never change. Requests made with a key are audited asapi-key:<id>; refused keys and every management call are audited too, with the key id, never the key. - ACME: a key may carry acme-dns registrations, one per domain, mapping an
acme-dns subdomain to the
_acme-challengeTXT RRset of the managed zone (ACME.md).
9.6 Token exchange¶
Some clients keep a credential for minutes or hours (certbot and acme.sh hooks,
long scripts), longer than the CI or workload token they start with. Instead of an
API key, they exchange that token for a gate token (OAuth 2.0 token exchange,
RFC 8693, POST /api/v1/token-exchange, configuration in
configuration):
- opt-in per issuer (
token_exchange: true), and only with a gate issuer (self: true, 9.4) to sign the result. Gate tokens and API keys are never exchanged; - the subject token is checked exactly as a bearer token of its issuer (signature,
audience, bound claims, bindings); the gate token carries its claims, binds back as
that issuer and records the exchanged
jti(gate_xchg), so bindings and audit see the same identity; - lifetime 15 minutes by default,
expires_in(at least 60 s) to ask for another, capped by the gate issuer'stoken_ttl. Roles are recomputed at every request, so a removed binding takes effect at once; - every exchange, and every refused subject token, is audited
(
gate.token.exchange).
9.7 Delegated clients and scopes¶
A token of a trusted issuer says who the user is, and its azp (Entra v2) or
appid (v1) says which application obtained it. Without more, an assistant such as
a Microsoft 365 Copilot agent holds every right of its user. A delegated client
(issuers[].delegated_clients, configuration)
names an application and caps it:
- Scopes are allowlists of RBAC actions (
dns.read,dns.plan,dns.write,dns.adopt,dns.transfer,policy.read). Effective rights = RBAC of the user ∩ actions of the scopes ∩ zones of the client. The definitions and the intersection live in one package (internal/scope), used by the policy engine for every decision (Allow,AllowRRset,AllowMeta,/api/v1/mepermissions), so no handler can forget it. Policy writes, API key management, zone administration and zone profiles are granted by no scope. - Intents.
dns.plangrants the write actions only on a copy of the subject marked for a plan (plan and adoption preview handlers);dns.transfergrants them only as proof of ownership inside the transfer checks. The subject of the apply is never marked. - Surfaces and endpoints.
Authenticaterefuses delegated tokens (not_delegable); only/api/v1and/mcpcallAuthenticateForwith their surface. The/api/v1router and the MCP tool list carry an explicit table of what each scope opens; a route or tool missing from it is refused to every delegated client (deny by default), before the handler runs, withscope_insufficientandrequired_scopeornot_delegable. The MCP middleware filterstools/list(cache scopeprivate) and refuses hidden tools. - Plans are keyed by the subject and its client: a plan is applied only through the client that made it, and a plan made without client never through one.
- Identity.
identity.Subjectkeeps the user (String()unchanged) and gainsClientandScopes; a transfer approver is recorded with them and rebound from the current client configuration on retries. A delegated subject is not a person for the approver rules (it keeps the step-up of humans), and sees only the transfers of its client zones. - Matching.
client_ids(aliasesazp,appid) are lowercased at load and compared with theazpclaim, elseappid, so one entry covers v1 and v2 tokens. - Audit. Events carry
client_idandactor {type: oauth_client, id, name}from the client of their subject (configuration only), so background retries keep it; the client recorded in the request context only fills events without subject (refusals before binding).auth_methodisoauth-delegated. - Tokens of undeclared clients keep the full rights of the user unless
require_known_clientrefuses them. Gate tokens of declared OAuth clients (9.8) carryclient_idandscopeand reuse the sameSubject.Client,Subject.Scopesand checks.
9.8 Declared OAuth clients¶
Delegated clients need an issuer that knows the application. Declared clients
(oauth.clients, configuration) are
registered at the gate authorization server instead, so any UI login (SAML Identity
Center included) can delegate to a SaaS or to a Copilot agent.
- Grant. One
oauth_grantper (client, subject) in the store (memory, SQLite, PostgreSQL, DynamoDB): session claims snapshot,auth_time, AMR, scopes (union of the consents), creation, consent, last use, absolute expiry, claims age, generation counters, SHA-256 of the current and previous refresh tokens, the sealed answer of the last rotation, revocation. Codes (oauth_code, by SHA-256, taken atomically) and client assertion ids (oauth_jti) sit next to it; DynamoDB items carry thettlattribute. - Refresh tokens are sealed references
{grant, generation, nonce}: the gate recognises any token it issued, so an earlier generation of the current consent is a reuse (the grant is revoked), a generation from before the last consent is just stale. Rotation is an optimistic update on the grant version: a racing second refresh with the previous token within 30 s gets the sealed previous answer back. - Access tokens are gate tokens with
typ: at+jwt,client_id,act,scope,gate_grantand theauth_timeof the consent sign-in.bindGateTokenbinds them as the origin issuer, then requires the client to be declared and enabled, the surface to be one of its surfaces, and the grant to be active for that client and subject (store read cached 30 s per process); the subject getsClient(with the grant andwrite_max_age) and the token scopes intersected with the current ceiling of the client. Everything of 9.7 then applies unchanged. These claims are registered: never copied from a session or an exchanged token. - Claims. A refresh rebinds the subject from the snapshot; with
groups_from_identity_storethe groups are looked up again (assertion groups kept in the session for that), otherwise the snapshot may not be older thanclaims_max_age. - Client authentication happens in
authn(private_key_jwtkeys inline or fromjwks_uri, secrets compared on SHA-256 digests in constant time), failures aggregated like API keys. - Not implemented: dynamic client registration, PAR, DPoP.