OAuth2 / OIDC JWT¶
The service authenticates with a short-lived OAuth2 access token obtained with the
client_credentials grant. The server validates the token against the issuer's signing keys, requires
its azp to equal the service name, and takes the rights from that service's ACL entry. No long-lived
secret crosses the wire.
Any OAuth2/OIDC provider works: Keycloak, Entra ID, Okta, Auth0, Authentik, Dex, Zitadel. The server
itself makes no provider-specific call — it reads iss, aud, exp, nbf, iat and azp from the
token and fetches the signing keys from the JWKS endpoint.
On the provider side¶
- One confidential client per service, using client credentials only — no browser flow, no direct access grants.
- The client id is the service name: the server compares the token's
azptoRegister.service_nameand to the ACL[[service]]entry. - Optionally add an audience mapper and set
SNODRA_SERVER_JWT_AUDIENCEto the same value; the server does not require it. - Do not give a user-facing client a
[[service]]ACL entry: only services that register handlers need one.
If your provider is Keycloak
Create the client as a confidential client with service accounts enabled and nothing
else. Its client id is the service name. The JWKS endpoint is
<issuer>/protocol/openid-connect/certs and the token endpoint is
<issuer>/protocol/openid-connect/token, which is what the client settings below expect.
Server¶
SNODRA_SERVER_AUTH_MODE=permissive
SNODRA_SERVER_ACL_FILE=/etc/snodra/snodra.acl.toml
SNODRA_SERVER_JWT_ISSUER=https://auth.example.com/realms/snodra
SNODRA_SERVER_JWT_AUDIENCE=snodra-server
# SNODRA_SERVER_JWT_JWKS_URI defaults to <issuer>/protocol/openid-connect/certs
[[service]]
name = "billing-service"
handle = ["billing.*"]
send = ["orders.*"]
| Setting | Default | Meaning |
|---|---|---|
SNODRA_SERVER_JWT_ISSUER |
none | Exact iss; unset means JWT credentials are off |
SNODRA_SERVER_JWT_JWKS_URI |
<issuer>/protocol/openid-connect/certs |
Where signing keys are fetched; may be an internal address while the issuer is public. Set it for a provider with a different JWKS path |
SNODRA_SERVER_JWT_AUDIENCE |
none | When set, the token must contain this aud |
SNODRA_SERVER_JWT_LEEWAY |
30s |
Clock skew on exp, nbf, iat |
SNODRA_SERVER_JWT_EXPIRY_GRACE |
30s |
How long a session survives after exp without a refresh |
SNODRA_SERVER_JWKS_REFRESH |
5m |
Key refresh period; an unknown kid triggers at most one extra fetch per 30 s |
SNODRA_SERVER_JWT_JWKS_CA |
platform roots | Extra CA for the key fetch |
Kotlin client¶
snodra:
messaging:
service-name: billing-service
hub:
oauth2:
token-uri: https://auth.example.com/realms/snodra/protocol/openid-connect/token
client-secret-file: /run/secrets/billing-client-secret
# client-id defaults to snodra.messaging.service-name
Environment forms: SNODRA_SERVER_OAUTH2_TOKEN_URI, _CLIENT_ID, _CLIENT_SECRET,
_CLIENT_SECRET_FILE, _SCOPE, _CA. A token URI together with a static token, or without any
secret, fails startup.
Rust client¶
SNODRA_SERVER_OAUTH2_TOKEN_URI=https://auth.example.com/realms/snodra/protocol/openid-connect/token
SNODRA_SERVER_OAUTH2_CLIENT_SECRET_FILE=/run/secrets/billing-client-secret
# client id defaults to SNODRA_SERVICE_NAME
Roles¶
A forwarded token's roles become ROLE_<role> in the service. Which claim they come from is
configuration, because providers disagree:
| Provider | security.roles-claim |
|---|---|
| Generic, Entra ID, Auth0 (custom claim) | roles |
| Keycloak | realm_access.roles |
| Okta, Authentik, Dex (groups) | groups |
| OAuth2 scopes | scope |
snodra:
messaging:
security:
roles-claim: realm_access.roles # the default is roles
The value is a dotted path into the claims; scope is read as the space-separated scopes, with an
optional prefix (SCOPE_).
How the token behaves¶
- One token per process, shared by every hub connection, fetched single-flight.
- Renewed in the background while more than its margin remains: 20 % of its lifetime, at least 5 s,
at most half. The new token is pushed to every live stream as
ClientMessage.credentials, so a session outlives its token. - A stream closed with
UNAUTHENTICATEDretires the cached token, so the reconnect fetches a new one.PERMISSION_DENIED(wrongazp, no ACL entry) does not: a new token would not help. - If the endpoint cannot issue a token, no stream is opened; the client reports
no access token for <service>: <error>and retries with the normal backoff.
Verify¶
curl -s -H "Authorization: Bearer $DASHBOARD_TOKEN" localhost:7001/api/v1/topology \
| jq '.services[].instances[] | {serviceName, authKind, authenticatedService, expiresAt}'
authKind reads jwt. expiresAt is the current token's expiry in epoch milliseconds.