Operations

Auth and Tenanting

Auth and Tenanting

Supported auth modes

  • auth disabled for local development only
  • HS256 shared-secret JWT validation
  • JWKS-backed OIDC validation

Core settings

  • ASTRAD_AUTH_ENABLED=true
  • ASTRAD_AUTH_ISSUER=<issuer>
  • ASTRAD_AUTH_JWKS_URL=<jwks-url>
  • ASTRAD_AUTH_AUDIENCE=astra
  • ASTRAD_AUTH_TENANT_CLAIM=tenant_id
  • ASTRAD_TENANT_VIRTUALIZATION_ENABLED=true

Generic Keycloak example

export ASTRAD_AUTH_ENABLED=true
export ASTRAD_AUTH_ISSUER=https://keycloak.example.net/realms/omni
export ASTRAD_AUTH_JWKS_URL=https://keycloak.example.net/realms/omni/protocol/openid-connect/certs
export ASTRAD_AUTH_AUDIENCE=astra
export ASTRAD_AUTH_TENANT_CLAIM=tenant_id
export ASTRAD_TENANT_VIRTUALIZATION_ENABLED=true

Astra currently expects one tenant value per caller token.

That means the safest public pattern is:

  • human users authenticate to the application layer and carry all tenant memberships in groups,
  • Astra receives service-account tokens only,
  • each service-account token carries exactly one tenant_id=<tenant> claim,
  • applications that cannot attach bearer tokens on the etcd path use a local proxy such as astractl oidc-proxy.

Validation checklist

  • a token without tenant_id is rejected
  • tenant A cannot read or write tenant B data
  • wrong issuer or audience is rejected
  • service-account tokens for shared-control-plane apps carry only one tenant value