Zum Inhalt springen
Produkte

// 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 every control.…, 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's updated_at from GET /api/roles as expected_updated_at, and an edit made after someone else saved the role is refused with 409 STALE instead of undoing theirs. Without it (or with null) the edit applies regardless.

  • Assignment — the roles graph edge from a user to a role. It carries a location field:

    • 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 location meta or a reserved pseudo-location (_core, _iac, _ingestion, any case); anything else, "*" and "" included, is a 400. 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 with 400, and answers 503, assigning nothing, when inventory-svc cannot say. For a global assignment omit location or send null. An assignment with any key other than role and location is 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 with POST /api/users/{name}/unassign. GET /api/users lists every assignment with effective: false for such an assignment, true otherwise.

    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, 409 while it exists) and names the removed user:role pairs in the location.delete audit 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 own NOT_FOUND), journalled as system; 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.delete there) 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:

  1. their direct permissions, plus
  2. the permissions of every role assigned globally, plus
  3. 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's extra_filters exclude meta.
  • The hub's own logs need hub_logs.view, held globally, on top of resource.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 a local_collector location, not meta. ingestion-svc stamps those hub="true": a stream the core agent sent on its own logs._core.<location> subject, for a location ingestion-svc admits as local_collector, whose namespace is one of the hub's ([logs] hub_namespaces of ingestion-svc, plus FLEEGER_HUB_NAMESPACE; the Helm chart renders the release namespace plus logs.hubNamespaces, the raw manifests ingestion-svc's own). A location's own agent's streams are never stamped, and a _core stream is written only once its location is known to be local_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. hub is a reserved label: an agent's own hub is dropped before the stamp, so no agent can mark or unmark a stream. Not stamped, so visible to every resource.view holder 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-agent narrows it). Third-party containers among them (NATS, SurrealDB, VictoriaMetrics) can log secrets Fleeger never would, so a global viewer or operator does not read them. For a caller without it the gateway ANDs location!="meta" and hub!="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 that fix-perms core-agent) carry no hub label: 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's query and query_range are proxied: its tail, label and series endpoints answer 404, so no stream is listed or followed past the exclusion. admin holds 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 both hub_logs.view and resource.view held globally: a user with resource.view at some locations only is pinned to those, which leaves the services' meta streams out.
  • NATS storage (GET /api/nats/jetstream, the JetStream account and ingest streams) is the hub's own data path: resource.view held globally. Draining a stream (POST /api/nats/jetstream/streams/{stream}/drain) deletes buffered telemetry for every location, so it is iam.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/permissions to auth-svc's /internal/* IAM handlers.
  • CLI — auth-svc still ships the user/role subcommands used to bootstrap the first administrator before any UI exists.

// Zusammenarbeit

Bereit, Ihre digitale Infrastruktur zu bauen?

Ob individuelle Automatisierung für Ihr Unternehmen oder ein durchgeplantes Netzwerk für Ihr Zuhause — lassen Sie uns über das Projekt sprechen.