// Benutzung · Zugriff & Rollen
RBAC & per-location access
Fleeger's authorization model is role-based with per-location scoping. This document is the reference for how permissions, roles, and role assignments fit together, where they are enforced, and the deliberate boundary of the current implementation. To do things, see the workflows: Managing users & roles and Delegating a location.
The pieces
Permission — a dotted string naming an action, e.g.
control.execute,location.view,iam.manage. Matching is wildcard-aware:*grants everything,control.*grants everycontrol.…, and an exact string grants just that one.Role — a named bag of permissions (
role:admin=["*"]). Roles are either built-in (admin,operator,viewer— locked, can't be edited or deleted) or custom (anything you create).PUT /api/roles/{name}replaces a custom role's whole permission list; send back the role'supdated_atfromGET /api/rolesasexpected_updated_at, and an edit made after someone else saved the role is refused with 409STALEinstead of undoing theirs. Without it (or withnull) the edit applies regardless.Assignment — the
rolesgraph edge from a user to a role. It carries alocationfield:location = NONE→ the role is granted globally (applies at every location).location = "<id>"→ the role is granted only for that location.
The IAM API accepts as
<id>only a location id ([A-Za-z0-9_-]{1,50}, sent as is, not trimmed) that is not the self-monitoring locationmetaor a reserved pseudo-location (_core,_iac,_ingestion, any case); anything else,"*"and""included, is a400. The location must also exist: auth-svc asks inventory-svc (GET /locations/{id}, with the internal token) and refuses an id it does not know with400, and answers503, assigning nothing, when inventory-svc cannot say. For a global assignment omitlocationor sendnull. An assignment with any key other thanroleandlocationis refused (422), so a misspelled key cannot become a global grant. An assignment stored before these checks at such a location grants nothing and can still be removed withPOST /api/users/{name}/unassign.GET /api/userslists every assignment witheffective:falsefor such an assignment,trueotherwise.Deleting a location removes every user's assignments for it: once inventory-svc has deleted it, the gateway asks auth-svc (
DELETE /internal/locations/{id}/assignments, internal only; auth-svc itself removes only once inventory-svc reports the location gone,409while it exists) and names the removeduser:rolepairs in thelocation.deleteaudit row. That step never fails the delete; what it could not remove (auth-svc unreachable, or an older auth-svc) grants nothing, as its location is gone, and is removed by a repeated delete or at auth-svc's next start. Once per start, after inventory-svc answers, auth-svc removes the assignments of every stored location inventory-svc reports it does not have (its ownNOT_FOUND), journalled assystem; a location it cannot answer for is asked again later, never removed on a guess, and while inventory-svc lists no location at all nothing is removed (an empty inventory is likelier a wrongly connected or half-restored database). Global assignments and inert ones ("*"…) are never touched. A user who may delete one location (location.deletethere) thereby removes every user's assignments for it.Direct permissions — a user's
additional_permissions, granted straight to the user without a role. Always global.
A user's effective permissions for a location L is the union of:
- their direct permissions, plus
- the permissions of every role assigned globally, plus
- the permissions of every role assigned for L.
Roles assigned for a different location contribute nothing to L.
What the client sees
GET /api/auth/me (any valid token) answers the caller and the permissions
they hold globally: direct grants and globally assigned roles. With
?location=L it answers the permissions they hold at L instead: those
same ones plus the permissions of roles assigned for L. The UI uses it to offer
an action at L whose route the gateway checks with permissions at L alone;
the location page's Lift lock button (location.create at L) and
its Roll back button and mode choice (see below) go by it. A L that no role can be assigned at (meta, a reserved
pseudo-location, an invalid id) is asked globally, as the gateway asks it. The
answer is sent Cache-Control: no-store. It is a display aid only: the gateway
still checks every request.
What is scoped and what is global (by design)
Per-location enforcement covers the security-critical write path and
location-scoped administration: control actions, a location's detail/subtree,
and agent offboarding. This is where damage happens, and it is fully scoped —
a homelab-only controller can never act on hetzner.
Reads are filtered to the caller's visible locations. A cross-location read
(the locations list, reachability state, /connz, and metric and log queries) is not
gated on the permission held globally; instead the gateway resolves the set of
locations the caller can view and narrows the response to that set. "All
locations" means the permission is held globally, which the gateway asks
explicitly (fn::auth_user_has_permission_at(perm, NONE)); otherwise the set is
the location ids fn::auth_user_visible_locations returns, keeping only
assignable ones (see Assignment above), so no location string can stand in
for "all locations":
| Read | How it's narrowed |
|---|---|
GET /api/locations |
list filtered to visible location ids |
GET /api/metrics/state/{locations,resources} |
rows filtered by location; for resources, ingestion-svc is asked only for the visible locations (or those named with ?location= that are visible) |
GET /api/agents/connz |
only visible agents' connections (agent-<loc>) |
GET /api/metrics/query[_range] |
a location=~"<visible>" matcher is pinned via VictoriaMetrics extra_filters[] |
GET /api/logs/query[_range] |
the LogQL stream selector is rewritten to AND-in a location=~"<visible>" matcher (see below), and the hub's own streams are left out without hub_logs.view |
GET /api/metrics/stream |
allowed if any location is visible (the tick carries no data) |
A narrowed answer is read under the same 16 MiB cap the gateway relays
metric, log, /connz and state reads under, so a list an admin is answered is
answered, narrowed, to a scoped caller too, and no more of it is read than
that. Answers the gateway passes on unread, such as an admin's location
list, are relayed as they arrive, not buffered, so they have no cap. The body of
a control mutation, read for its location, is bounded by the proxy's own 4 MiB
request limit.
The metric filter is the security-critical one: extra_filters[] is applied by
VictoriaMetrics to every selector in the query, server-side, so it can't be
evaded by the query text (… or up, subqueries, unlabelled selectors). The
visible ids are regex-escaped, and the result is then escaped for the quoted
string (\, " and control characters), so no id can end the string and add
matchers of its own; the log matcher below is built by the same code. If
a caller can view no location, the read is 403.
Loki has no extra_filters[], so a scoped log query is rewritten instead: the
gateway adds location=~"<visible>" to every {…} stream selector in the
LogQL text. LogQL ANDs repeated matchers on the same label, so a query
that names another location matches no streams. Because this works on the
query text, the gateway reads it the way Loki's lexer does and fails closed on
anything it might read differently: a # comment, a '…' literal, a // or
/* sequence outside a string, or an unterminated string, is a 400 and Loki is
not asked. A global caller who holds hub_logs.view has the query passed on
unchanged; one who does not gets the hub's exclusion added the same way (see
below).
A location-scoped viewer therefore sees a real, correct dashboard containing only
their locations — no global viewer pairing required. Two deliberate carve-outs
remain global:
- Self-monitoring metrics (
location="meta", the control plane's own services) are visible only to someone who can view all locations: a scoped user'sextra_filtersexcludemeta. - The hub's own logs need
hub_logs.view, held globally, on top ofresource.view. They are the hub services' streams (location="meta", shipped by Promtail) and the streams of the hub's own pods, which the core agent collects under alocal_collectorlocation, notmeta. ingestion-svc stamps thosehub="true": a stream the core agent sent on its ownlogs._core.<location>subject, for a location ingestion-svc admits aslocal_collector, whosenamespaceis one of the hub's ([logs] hub_namespacesof ingestion-svc, plusFLEEGER_HUB_NAMESPACE; the Helm chart renders the release namespace pluslogs.hubNamespaces, the raw manifests ingestion-svc's own). A location's own agent's streams are never stamped, and a_corestream is written only once its location is known to belocal_collector(held until then, or dropped and counted past the held bound; refused once unflagged), so none is written unstamped for want of a judgement.hubis a reserved label: an agent's ownhubis dropped before the stamp, so no agent can mark or unmark a stream. Not stamped, so visible to everyresource.viewholder at that location: the hub cluster's pods when a regular spoke agent collects that cluster instead of the core agent, and the core agent's streams while it still runs on its older, wider credential (it publishes on the location's own subject until./gen-auth.sh fix-perms core-agentnarrows it). Third-party containers among them (NATS, SurrealDB, VictoriaMetrics) can log secrets Fleeger never would, so a globalvieweroroperatordoes not read them. For a caller without it the gateway ANDslocation!="meta"andhub!="true"into every stream selector, with the same fail-closed reading of the query as above, whether or not the caller is location-scoped. A stream without the label matches the latter, so a spoke's pod in a namespace named like the hub's stays visible. Streams written before the upgrade to this release (or before thatfix-perms core-agent) carry nohublabel: the hub's pod streams among them stay as visible as they were until Loki's retention ages them out; nothing re-labels them. Only Loki'squeryandquery_rangeare proxied: its tail, label and series endpoints answer404, so no stream is listed or followed past the exclusion.adminholds it through*; give it to anyone else with a role that names it. The Services page's per-service log tail is offered only with bothhub_logs.viewandresource.viewheld globally: a user withresource.viewat some locations only is pinned to those, which leaves the services'metastreams out. - NATS storage (
GET /api/nats/jetstream, the JetStream account and ingest streams) is the hub's own data path:resource.viewheld globally. Draining a stream (POST /api/nats/jetstream/streams/{stream}/drain) deletes buffered telemetry for every location, so it isiam.manage, like backup and retention.
Single-resource routes under /api/resources/{id} (detail, edit, delete,
/hardware, /credential) are checked at the resource's own location.
The path names only the id, so the gateway asks inventory-svc where the
resource lives, never a hint in the request, and caches the answer (a resource
cannot change location). A caller holding the permission globally skips the
lookup. An unknown resource, an id that is not a plain record key, and a failed
lookup all fall back to the global check, so a scoped caller gets 403 without
learning whether the resource exists. An edit that keeps a check's stored
check_vantages needs the permission at each of them too, as one naming new
vantages does, because an edited address is probed from every vantage.
/api/credentials/{id} (rename, rotate, delete a saved credential) is checked
the same way at the credential's own location, with the permission it
already needed (resource.edit to rename or rotate, resource.delete to
delete). inventory-svc answers the lookup with the credential's id and location
only, never its name, kind or secret, and the gateway does not proxy that
GET. An unknown credential gets the same 403 as one at another location.
IAM is always global. iam.manage gates /api/users, /api/roles, and
/api/permissions; managing access is never delegated to a per-location role.
The last global admin stays. A user, role or assignment change that would
leave no user holding iam.manage on every location (by role or by direct
grant, wildcards included) is refused with 409: give another user a global
admin role first. An install that has no global admin to begin with is not
locked by this; there, the auth-svc CLI (see Managing it below) creates
the first one.
The permission catalog
GET /api/permissions (admin-only) returns the catalog the role editor renders,
grouped by area. location_scoped: true marks the groups whose permissions are
meaningful to assign for a single location:
| Group | Permissions | Location-scopable |
|---|---|---|
| Locations | location.view/create/edit/delete |
yes |
| Resources | resource.view/create/edit/delete |
yes |
| Control | control.view, control.execute |
yes |
| Alerting | alert.view/create/edit/delete |
no |
| Audit | audit.view: read the hub-wide audit log (GET /api/audit) |
no |
| Hub logs | hub_logs.view: read the hub's own logs through /api/logs (see above) |
no |
| Administration | iam.manage |
no |
| — | * (superuser) |
— |
Creating a resource in a location (POST /api/locations/{id}/resources)
needs resource.create and location.edit at that location, and
resource.create at each extra vantage the new check names.
location.create creates locations; it no longer creates resources.
A checkpoint rollback (POST /api/locations/{id}/rollback) needs the rights
its changes need when made directly, at that location: resource.edit
and location.edit for a safe rollback, and resource.create and
resource.delete on top for a full one. The gateway reads the mode from the
body and fails closed: anything but an explicit "mode": "safe" needs the
full set. Every vantage the rollback adds at another location needs
resource.create there, as for direct creation; the gateway tells
inventory-svc where the caller holds it. Taking a checkpoint (POST /api/locations/{id}/checkpoints) and lifting a rollback's lock (POST /api/locations/{id}/rollback/unlock) stay location.create; reading the lock
is location.view.
Attaching an existing credential by id — credential_id on that create,
or PUT /api/resources/{id}/credential (resource.edit at the resource's
location) — also depends on the address: it is allowed where a resource using
the credential now already points (same scheme, host and port), and anywhere
else, or for a credential nothing uses, only for a caller holding
resource.edit on all locations. The gateway tells inventory-svc so
with the X-Fleeger-Credential-Any-Host header, which it sets itself on those
two routes, on a resource edit (PUT /api/resources/{id}) and on a checkpoint
rollback, and strips from client requests; without it inventory-svc applies
the address rule. A scoped caller enters the secret again instead. See
Credentials.
Combining a stored credential with certificate checks off
(allow_invalid_certs) needs the permission resource.allow_invalid_certs
at the resource's location, or globally: turning the flag on for
a resource that carries a credential, attaching an existing credential to a
resource that has it on (at create or later), or a rollback that would turn it
on for a resource keeping its credential. With the checks off the agent
accepts any certificate at that address, so a man in the middle at the site
would read the secret. It is location-scopable like the other resource
permissions, and resource.* and * include it; resource.edit, even on all
locations, does not. The gateway tells inventory-svc where the caller holds it
with the X-Fleeger-Invalid-Certs-Locations header (* or a list of location
ids) on a resource create or edit, a credential set and a checkpoint rollback,
and strips any client copy; without it, no location. Without the permission a
caller gets 403; a secret it enters itself, as a new credential, may go with
the checks off (on an existing resource: detach first, see
Credentials).
Setting or changing a location's local_collector flag — on a create
(POST /api/locations), an edit (PUT /api/locations/{id}) or a checkpoint
rollback that would restore another value — needs location.edit on all
locations. The flag moves the location's collection onto the hub's
bundled core agent, which probes its targets from inside the hub's network,
so it is hub-wide administration, not a per-location setting. The gateway
tells inventory-svc with the X-Fleeger-Local-Collector-Grant header, which
it sets itself on those three routes and strips from client requests; without
it inventory-svc refuses a write that would change the flag with 403. An
edit or rollback that sends the value the location already has is accepted,
so a scoped editor can still save the location's other settings; a location
an administrator flagged keeps its flag.
At a local_collector location, registering an in-cluster Kubernetes
cluster — a k8s_cluster with no credential, which the core agent reads
with its own ServiceAccount, in the hub's own cluster — needs the same
location.edit on all locations. Without it inventory-svc answers
403 to a resource create (POST /api/locations/{id}/resources) of one, an
edit (PUT /api/resources/{id}) that changes a credential-less resource's
kind to k8s_cluster, a credential detach
(DELETE /api/resources/{id}/credential) from a k8s_cluster, and a
checkpoint rollback that would restore one in place or recreate one (a
recreated resource comes back without its credential). The gateway sets the
same X-Fleeger-Local-Collector-Grant header on those routes. A cluster with a
kubeconfig is not affected, nor is any other edit of an in-cluster cluster an
administrator registered, nor a location that is not local_collector, where
in-cluster is the agent's own cluster and stays open to location users.
Turning local_collector on for a location that already has in-cluster
clusters needs the global grant anyway, so no other check applies there.
Managing it
- UI — the Access page (admin-only nav, gated on
iam.manage): create users, set passwords, assign/unassign roles globally or per-location, and a custom-role editor with permission checkboxes from the catalog. - API — the gateway proxies
/api/users,/api/roles,/api/permissionsto auth-svc's/internal/*IAM handlers. - CLI — auth-svc still ships the
user/rolesubcommands used to bootstrap the first administrator before any UI exists.