| title | Authorization |
|---|---|
| linkTitle | Authorization |
| weight | 4 |
| description | How ate-api-server checks every call against an OpenFGA model, and how to manage roles and access. |
Warning
Do not keep ate-client as the bootstrap owner outside development.
ate-setup makes the shared ate-client ServiceAccount the default
bootstrap owner so the demos, benchmarks and e2e tests work. Anyone who can
mint a token for it, including every kubectl ate user who doesn't pass
--token-file, is then a global owner. For a shared or production install,
set bootstrap owners to your operators' own principals.
ate-api-server checks every API call against an
OpenFGA model before running it. OpenFGA is embedded in
ate-api-server and stores its data in the same PostgreSQL database. For how
callers authenticate, see authentication.md.
- Authentication turns the credential into a principal ID, or rejects it
with
Unauthenticated. - Authorization allows the call if the principal is a bootstrap owner,
holds a role from an access policy that permits it, or is a Substrate
component with the system role it needs. Otherwise, or if the RPC has no
rule, it returns
PermissionDenied.
Authorization is always enforced. ate-setup reads the setting below and
passes it to ate-api-server as the --authz-bootstrap-owners flag on its
container; an install that doesn't use ate-setup sets that flag in its
manifest. ate-api-server won't start without a bootstrap owner. A change
rolls ate-api-server.
| Setting | Environment variable | Example |
|---|---|---|
ateapi.authz.bootstrapOwners |
ATE_API_AUTHZ_BOOTSTRAP_OWNERS |
alice@example.com,bob@example.com |
If you don't set ateapi.authz.bootstrapOwners, ate-setup uses the shared
ate-client ServiceAccount (system:serviceaccount:<namespace>:ate-client),
so the demos, benchmarks and e2e tests work. See the warning at the top of
this page.
A principal is the ID authentication produces. Access policies name it as
user:<id>; bootstrap owners list the bare <id>.
| Caller | <id> |
|---|---|
| Kubernetes ServiceAccount token | system:serviceaccount:<namespace>:<name> |
| Other JWT provider, such as Google | The token's sub (for Google, a numeric account ID, not the email) |
| Pod certificate (mTLS) | Its SPIFFE ID, e.g. spiffe://cluster.local/ns/benchmarking/sa/default |
A denied call names the principal in the error with : percent-encoded
(user:system%3Aserviceaccount%3A...); decode it before using it.
Bootstrap owners always hold owner on the global scope, whatever the access
policies say. They write an install's first access policies and recover access
if those break.
- They come from configuration, not the API.
ate-api-serverreads them at startup and exits if the list is empty. Restarting it with a new list takes effect immediately. - Any principal
ate-api-servercan authenticate can be one. ate-setupwarns wheneverate-clientis one.- Keep the list short. Grant day-to-day admins
ownerin the global access policy instead, where it can be revoked through the API.
For example, with a JWT provider whose tokens carry the user's email as sub:
ATE_API_AUTHZ_BOOTSTRAP_OWNERS=alice@example.com,bob@example.com go run ./cmd/ate-setup deploy ate-systemTo make your Google account a bootstrap owner, use its numeric sub:
gcloud auth print-identity-token | cut -d. -f2 | base64 -d 2>/dev/null | jq -r .sub # your sub
ATE_API_AUTHZ_BOOTSTRAP_OWNERS=<sub>,system:serviceaccount:ate-system:ate-client \
go run ./cmd/ate-setup deploy ate-system # keep ate-client for demos and benchmarksThen add the Google provider to the ate-api-authentication ConfigMap and
restart ate-api-server
(authentication.md), and act as
yourself:
gcloud auth print-identity-token > me.token
kubectl ate --token-file me.token get atespaceskubectl ate sends the token from --token-file. Without one, it mints a
token for ate-client (or ATE_CLIENT_SERVICE_ACCOUNT); see
authentication.md.
ate-setup calls the API only to deploy and delete demos and benchmarks, as
ate-client. If you leave ate-client out of the bootstrap owners, grant it
access in a policy or those steps are denied.
Roles are granted on the global scope, which covers every atespace, or on one atespace.
| Permission | Global owner | Global viewer | Atespace owner | Atespace editor | Atespace viewer |
|---|---|---|---|---|---|
| Create atespaces; list all atespaces | ✅ | list only | |||
| Get the atespace | ✅ | ✅ | ✅ | ✅ | ✅ |
| Delete the atespace | ✅ | ✅ | |||
| Get access policies | ✅ | ✅ | ✅ (its own) | ✅ (its own) | ✅ (its own) |
| Create, update, delete access policies | ✅ | ✅ (its own) | |||
| Get and list actors, actor templates, tags, egress policies | ✅ | ✅ | ✅ | ✅ | ✅ |
| Create, update, delete actors and actor templates | ✅ | ✅ | ✅ | ||
| Resume, suspend, revert actors | ✅ | ✅ | ✅ | ||
| Create, update, delete egress policies | ✅ | ✅ | ✅ | ||
| Create, publish, delete tags | ✅ | ✅ | ✅ | ||
Create an actor from a tag (sourceTag) |
✅ | ✅ | ✅ | ||
| Workers: get, list, list assignments | ✅ | ✅ | |||
| Workers: create, update, delete, drain | ✅ |
Substrate's components hold roles that access policies cannot grant, and only
through their pod certificates. ate-api-server's --controller-spiffe-id,
--egress-gateway-spiffe-id, --ingress-router-spiffe-id and
--api-server-sidecar-spiffe-id flags bind them, defaulting to the install's;
atelet's comes from --atelet-service-account.
| Role | Held by | Allows |
|---|---|---|
controller |
ate-controller |
Create, get, list, update, delete and drain workers |
egress_gateway |
atenet-egress, and any other SPIFFE IDs passed with --egress-gateway-spiffe-id, which ate-setup sets from ATE_EGRESS_GATEWAY_EXTRA_SPIFFE_IDS |
Get actors and their egress policies; list actors across all atespaces; mint actor JWTs |
ingress_router |
atenet-router |
Resume actors; list actors across all atespaces |
atelet |
atelet |
Get actors' egress policies, for the worker that enforces them |
api_server_sidecar |
the ate-api-server pod identity, which its sidecars share, today the objectstore control plugin |
Get actors, to derive the snapshot prefixes a per-actor storage credential may cover |
Only egress_gateway can mint actor credentials: not even a global owner can,
since a credential lets its holder act as the actor.
A gRPC interceptor makes every check before the handler runs
(registry.go,
model.fga). When an RPC lists
several checks, all must pass.
Roles inherit: an owner is also an editor and a viewer, an editor is also a viewer, and a global role holds the same role in every atespace. So "atespace editor" below also means atespace owner, global owner, and so on.
| RPC | Permission, on | Allowed for |
|---|---|---|
CreateAtespace |
can_create_atespace, global |
Global owner |
ListAtespaces |
can_list_atespaces, global |
Global viewer |
GetAtespace |
can_get, the atespace |
Atespace viewer |
DeleteAtespace |
can_delete, the atespace |
Atespace owner |
GetGlobalAccessPolicy |
can_get_access_policy, global |
Global viewer |
CreateGlobalAccessPolicy, UpdateGlobalAccessPolicy |
can_create_access_policy / can_update_access_policy, global |
Global owner |
GetAtespaceAccessPolicy |
can_get_access_policy, the atespace |
Atespace viewer |
CreateAtespaceAccessPolicy, UpdateAtespaceAccessPolicy, DeleteAtespaceAccessPolicy |
can_create_access_policy / can_update_access_policy / can_delete_access_policy, the atespace |
Atespace owner |
| RPC | Permission, on | Allowed for |
|---|---|---|
CreateActorTemplate |
can_create_actor_template, metadata.atespace |
Atespace editor |
GetActorTemplate |
can_get, the template |
Viewer of its atespace |
DeleteActorTemplate |
can_delete, the template |
Editor of its atespace |
ListActorTemplates |
can_list_actor_templates, the atespace, or global if none is given |
Atespace viewer; global viewer for all atespaces |
CreateActor |
1. can_create_actor, the actor's atespace2. can_use_template, the actor template3. can_use_tag, the sourceTag, if one is given |
1. Atespace editor 2. Viewer of the template's atespace, which may be another one 3. Editor of the tag's atespace. When sourceTag is omitted, the handler resolves the template's golden tag without checking can_use_tag. |
UpdateActor |
1. can_update, the actor2. can_use_template, the template in the request |
1. Editor of its atespace 2. Viewer of the template's atespace, so an actor can't be switched to a template its editor can't use |
GetActor |
can_get, the actor |
Viewer of its atespace; atenet-egress; the objectstore control plugin |
DeleteActor |
can_delete, the actor |
Editor of its atespace |
ListActors |
can_list_actors, the atespace, or global if none is given |
Atespace viewer; for all atespaces, global viewer, atenet-router or atenet-egress |
SuspendActor, RevertActor |
can_suspend / can_revert, the actor |
Editor of its atespace |
ResumeActor |
can_resume, the actor |
Editor of its atespace; atenet-router |
GetActorEgressPolicy |
can_get_egress_policy, the actor |
Viewer of its atespace; atenet-egress; atelet |
CreateActorEgressPolicy, UpdateActorEgressPolicy, DeleteActorEgressPolicy |
can_create_egress_policy / can_update_egress_policy / can_delete_egress_policy, the actor |
Editor of its atespace |
MintActorJwt |
can_mint_actor_jwt, the actor |
atenet-egress only |
| RPC | Permission, on | Allowed for |
|---|---|---|
CreateTag |
can_create_tag, the source actor's atespace, where the tag is stored |
Atespace editor |
GetTag |
can_get, the tag |
Viewer of its atespace |
UpdateTag (including publishing) |
can_update, the tag |
Editor of its atespace |
DeleteTag |
can_delete, the tag |
Editor of its atespace |
ListTags |
can_list_tags, the atespace, or global if none is given |
Atespace viewer; global viewer for all atespaces |
Workers have no atespace; their permissions come from the global scope.
| RPC | Permission, on | Allowed for |
|---|---|---|
CreateWorker |
can_create_worker, global |
Global owner; ate-controller |
ListWorkers |
can_list_workers, global |
Global viewer; ate-controller |
GetWorker |
can_get, the worker |
Global viewer; ate-controller |
UpdateWorker, MarkWorkerAvailable, MarkWorkerUnavailable |
can_update, the worker |
Global owner; ate-controller |
DeleteWorker |
can_delete, the worker |
Global owner; ate-controller |
DrainWorker |
can_drain, the worker |
Global owner; ate-controller |
ListWorkerActorAssignments |
can_list_actor_assignments, the worker |
Global viewer |
The interceptor skips these; each handler requires atelet's pod
certificate.
| RPC | The caller must be |
|---|---|
AcquireWorkerEpoch |
atelet on the worker's node |
RegisterWorker |
atelet on the worker's node |
SetWorkerSandboxRuntimes |
atelet on the worker's node |
ReportActorCrashed |
atelet on the node of the worker hosting the actor |
RequestActorSuspend |
atelet on the node of the worker hosting the actor |
MintWorkerActorJwt |
atelet on the node hosting the actor |
MintWorkerActorCertificate |
atelet on the node of the worker the actor is assigned to |
ReportActorSnapshotState |
atelet on the node the actor is placed on |
- An RPC with no rule is denied, and a test fails the build if a served RPC has none.
- gRPC reflection is open to any authenticated caller, like Kubernetes API
discovery, since it returns only the API schema, which is public in
api/ateapi/v1/ateapi.proto. Any other streaming RPC is denied. - An unauthenticated caller gets
Unauthenticatedbefore its request is read. - A missing or invalid resource name returns
InvalidArgument; no check is skipped.
Each scope has one access policy, named default, managed with kubectl ate
using --global or -a <atespace>:
# policy.yaml
metadata:
name: default
bindings:
- role: editor
members:
- user:system:serviceaccount:ate-users:alice
- role: viewer
members:
- user:system:serviceaccount:ate-users:bobkubectl ate --token-file me.token create access-policy -a team-a -f policy.yaml
kubectl ate --token-file me.token get access-policy -a team-a -o yaml > current.yaml
kubectl ate --token-file me.token update access-policy -a team-a -f current.yaml
kubectl ate --token-file me.token delete access-policy -a team-a- Global policies accept
ownerandviewer; atespace policies also accepteditor. updatereplaces the whole policy and needs theuidandversionfromget -o yaml. It fails if the policy changed, or was deleted and recreated, since.- The global policy can't be deleted; update it with no bindings instead.
- Deleting an atespace deletes its policy, so a recreated atespace starts with none. A request authorized against the old atespace and still in flight across the delete and recreate can apply to the new one. See Known limitations.
- Changes take effect on the next call.
If no principal anyone can authenticate as holds owner (for example, a
Google account listed by email instead of its numeric sub), anyone who can
redeploy ate-api-server can recover: redeploy with a bootstrap owner they
can use, fix the policies, then redeploy with the intended owners.
ATE_API_AUTHZ_BOOTSTRAP_OWNERS=alice@example.com go run ./cmd/ate-setup deploy ate-systemFor a shared cluster, beyond replacing the default bootstrap owner:
-
Give people their own identities in access policies, and have them pass
--token-filewith a token from a trusted JWT provider or their own ServiceAccount (authentication.md). -
Limit who can act as a ServiceAccount bootstrap owner. Anyone who can create
serviceaccounts/tokenor pods in its namespace, or change RBAC there, can get its token. Check who can, and alert on the audit events:kubectl auth can-i create serviceaccounts/ate-client --subresource=token -n ate-system --as alice@example.com
- Groups. Policy members are individual principals.
- Signing in. See authentication.md.
- Atespace names must not be reused. Grants are keyed by atespace name, and calls are authorized before the write runs. If an atespace is deleted and recreated under the same name, a request authorized against the old atespace and still in flight across the delete and recreate can land on the new one, including granting access to it or deleting it. Nothing enforces unique names. Once an atespace is deleted, don't create another one under that name; use a fresh name instead.
- Tags can copy an actor's data. A tag is a durable copy of an actor's memory and disk, including secrets, and outlives the actor. Any atespace editor can tag, publish and clone any actor in the atespace.
- Principals are not qualified by issuer. If
ate-api-servertrusts more than one JWT provider, any of them that can issue a token whosesubis another principal's ID, a bootstrap owner's included, acts as that principal. System roles are unaffected: they need the component's pod certificate. - The atespace is the only boundary. There are no per-actor or per-template grants.
- Any atelet can read any actor's egress policy. Every node's atelet
shares one identity, so the
ateletrole isn't limited to actors on its node (#1564).