/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Claims Schema

Keywords on this page
WordMeaningExample
CrateA Rust library other Rust code builds againstclaims-schema
Claims headerx-gateway-claims: the checked token’s claims, base64-encoded, added by the edgeeyJzdWIiOiJ1MSJ9
Base64 alphabetThe 64 characters base64 uses, and whether it pads with =standard uses + /, URL-safe uses - _
ExtractorAxum code that builds a value from a request before the handler runsGatewayClaims
LenientKeeps what it can read instead of failing the whole thinga bad membership is dropped
FixtureA JSON file of example messages every language must agree onschemas/fixtures/standard-claims.json

Rust crate at schemas/claims-schema. It reads the x-gateway-claims header for every Rust service. Go has the same job in Auth Contracts, Python in agent/app/auth.py: one reader per language, never one per service.

Depends only on serde, serde_json, base64. No I/O, no web framework.


Who uses it

ServiceImportsRule its extractor adds
digital-twinClaimsPayload, Membership, CLAIMS_HEADER, decode_claims_headersub required, else 401 Invalid authentication token
telemetrysamesub required
dashboardClaimsPayload::decode, CLAIMS_HEADERsub required, else bare 401
chatClaimsPayload, CLAIMS_HEADER, decode_claims_headersub required, else 401 …missing an account id
notificationsame as digital-twinaccountName required, else 401 …missing an account
socketClaimsPayload::decode, CLAIMS_HEADERsub and accountName required, else the connection is refused

The crate only reads. Deciding which field is required is each service’s job, because the services need different things: notification keys subscriptions by account name, the others key on sub.


Shape

pub const CLAIMS_HEADER: &str = "x-gateway-claims";

pub struct Membership {
    pub domain: String,
    pub role: Option<String>,
    pub external_id: Option<String>,   // "externalId"
}

pub struct ClaimsPayload {
    pub sub: Option<String>,
    pub account_name: Option<String>,  // "accountName"
    pub sid: Option<String>,
    pub memberships: Vec<Membership>,
}

Field for field the same as Go’s StandardClaims. Every field is optional in the type: parsing says what the header says, the service says whether that is enough.


A request end to end

digital-twin’s extractor, adapters/driving/http_api/claims.rs; the others follow the same steps.

sequenceDiagram
    autonumber
    participant E as Edge
    participant X as digital-twin<br/>GatewayClaims extractor
    participant C as claims-schema
    participant A as digital-twin<br/>service/authz.rs
    E->>X: request + x-gateway-claims
    X->>X: headers.get(CLAIMS_HEADER). none? 401 Missing
    X->>X: to_str(). not text? 401 Invalid
    X->>C: decode_claims_header(raw)
    C->>C: try STANDARD, URL_SAFE, STANDARD_NO_PAD, URL_SAFE_NO_PAD
    C-->>X: bytes, or None then 401 Invalid
    X->>C: serde_json::from_slice into ClaimsPayload
    C->>C: lenient_memberships drops bad entries
    C-->>X: ClaimsPayload, or error then 401 Invalid
    X->>C: payload.user_id()
    C-->>X: trimmed sub, or None then 401 Invalid
    X->>A: GatewayClaims with payload and raw header
    A->>C: payload.memberships, roles
    A->>A: Cedar decision, see Auth Policy

Data at each step

Header for {"sub":"u1","accountName":"ada","memberships":[{"domain":"acme","role":"business_admin"},"beta"]}, sent URL-safe without padding.

StepData
1x-gateway-claims: eyJzdWIiOiJ1MSIs… (no = at the end)
5STANDARD fails on the missing padding; URL_SAFE fails too; STANDARD_NO_PAD succeeds
6The JSON bytes above
8"beta" is not an object: dropped. memberships = [{acme, business_admin}]
9ClaimsPayload { sub: Some("u1"), account_name: Some("ada"), sid: None, memberships: [1 entry] }
11Some("u1")
12GatewayClaims with the payload and the raw header, kept so the service can forward it

Two reading choices

Four base64 alphabets

decode_claims_header tries four decoders in order and keeps the first that works:

OrderAlphabetPadding
1STANDARD (+ /)required
2URL_SAFE (- _)required
3STANDARD_NO_PADnone
4URL_SAFE_NO_PADnone

A Rust decoder accepts exactly one form. The edge may write any of them, so trying only one would refuse good headers.

Bad memberships are dropped, not fatal

flowchart TD
    M{"memberships field"} -- "missing or null" --> E["empty list"]
    M -- "not a list, like a string" --> F["whole payload fails"]
    M -- list --> L["for each entry"]
    L --> O{"object with a string domain?"}
    O -- no --> D["drop entry"]
    O -- yes --> K["keep: role and externalId optional"]

Example. ["acme", {"domain":7}, {"role":"admin"}, {"domain":"beta"}] keeps only beta, with no role.

Why: failing the whole header turns “not a member of that domain” (403) into “broken token” (401). The person debugging then looks in the wrong service. A memberships that is not a list at all is still fatal: that is a broken token.


Accessors

MethodGivesExample
decode(header)decode_claims_header then JSON parse; None on either failure
user_id()sub, trimmed; None when missing or blank{"sub":" "} gives None
account()accountName, trimmed, same rule
session_id()sid, same rule{"sid":""} gives None
domains()Every membership’s domain["acme", "unibo"]
role_in(domain)Role of the first membership with that domainrole_in("acme") = Some("business_admin")
belongs_to(domain)true when a membership has that domain; always false for ""belongs_to("") = false
has_role(role)true when any membership has that role, in any domain

A blank string is treated as missing, so " " can never act as an identity.


What stays in each service


Tests

TestChecks
src/lib.rsAll four alphabets decode; not-base64 and not-JSON fail; the full contract round trips; blank fields are None; missing or null memberships give an empty list; bad entries dropped; a non-list fails; roles scoped per domain; a membership with no role still grants the domain
tests/conformance.rsstandard-claims.json parses with sub, accountName, sid, role, externalId; written back it equals the fixture, so no field is silently lost; it matches schemas/json/standard-claims.schema.json; the schema refuses a role off the ladder (emperor)
tests/tenancy_domains_schema.rsFixture-against-schema for tenancy-domains.json, a shape between tenancy and the frontend with no Rust type
tests/chat_conversation_schema.rsSame for chat-conversation.json, which only chat writes and the frontend reads

The same claims fixture is checked by Go (backend/libs/auth-contracts/conformance_test.go) and Python (agent/tests/unit/test_claims_conformance.py). Socket, notification and chat also have an architecture test that the header name is claims_schema::CLAIMS_HEADER, never a literal.

mise exec -- cargo test --manifest-path schemas/claims-schema/Cargo.toml

Building a service that uses it

The dependency is a path, ../../schemas/claims-schema, so each consumer image builds from the repo root (cd_context: "." in .github/services.json). Each Dockerfile copies the crate before cargo chef prepare and before each cargo chef cook; a path missing during cook fails the build half way.


Gaps