Zum Inhalt springen
Produkte

// Benutzung · Grundlagen

Credentials

Fleeger stores the secrets it needs to reach infrastructure — Proxmox API tokens, iDRAC logins, kubeconfigs. This is the reference for how those credentials are modelled, secured, shared, and cleaned up.

For how a credential's secret is encrypted at rest (AES-256-GCM with a service-held master key), see the security model. This document is about the credential entity and its lifecycle.

First-class, per-location, shareable

A credential is a standalone entity, not a property owned 1:1 by one resource:

  • Named — a human label ("Proxmox homelab token") shown in the manager.
  • Per-location — a credential belongs to a location and may only attach to resources in that same location. This preserves Fleeger's location-isolation boundary: a homelab credential can never be used against a datacenter box. Attaching one from another location, by credential_id on resource create or on PUT /resources/{id}/credential, gets the same 404 and message as an id that does not exist, so a caller scoped to one location cannot probe for credential ids elsewhere.
  • Shareable — one credential can be attached to many resources at once (resource.credential_ref → the credential). Rotate the secret once and every resource using it is updated.
  • Independently-lifecycled — a credential survives the deletion of a resource that used it, becoming an orphan rather than being destroyed.
  • Bound to where it is used — sharing stays at the addresses a credential is used at now. See below.

Bound to the addresses it is used at

Attaching an existing credential sends its secret to the resource's address, so a credential is attached by id (credential_id on resource create, or PUT /resources/{id}/credential) only where a resource using it now already points: the same endpoint, meaning

  • for a URL, the same scheme, host and port, the scheme's default port filled in: https://pve:8006/api2 and https://PVE:8006 are one endpoint, https://pve and https://pve:443 too, while http://pve:8006 is another (the token must not be downgraded to cleartext) and so is https://pve:8007;
  • for the bare host[:port] of the non-URL kinds (e.g. a TCP check), that host and port as written; no scheme and no default port are assumed, so db:5432 and db differ. A URL and a bare address never match, and an address with no readable host matches nothing.

Anywhere else needs resource.edit on all locations (a global grant), and so does attaching a credential no resource uses (one saved in the manager, or one left over after its resources were detached or deleted): it is attached at no endpoint now. Everyone else enters the secret again on the resource, which saves a new credential. A refusal is 403, and nothing is written. Nothing is remembered about where a credential was used before: an address it has left is like any other.

The editing rule is the same comparison: the address of a resource holding a credential cannot be changed to another endpoint (a 400; detach first), and a checkpoint rollback that would do so is refused. Detaching, re-pointing and attaching again does not get round it either: once detached, no resource uses the credential at the new address.

The attach is checked against a resource using the credential at that endpoint, and its transaction commits only while that resource still uses it at the address it was checked with; if it was detached or re-pointed meanwhile, the attach is checked again.

Whether the caller holds resource.edit globally is the gateway's answer: on these two routes it sets X-Fleeger-Credential-Any-Host: 1 for such a caller, after dropping any copy the client sent, and inventory-svc reads a missing header as "no". The manager listing shows each credential's endpoints (those of the resources using it); the resource form and the manager's "Attach" picker grey out a credential that cannot be attached at the chosen address, and say why.

A stored credential and certificate checks off (allow_invalid_certs) go together only for a user holding resource.allow_invalid_certs at the resource's location (see RBAC & per-location access): with the checks off the agent accepts any certificate, so a man in the middle at the site would read the secret. Turning the flag on for a resource that carries a credential, attaching an existing credential where it is on, and a rollback that would turn it on for a resource keeping its credential need it. A secret the user enters itself may go with the checks off: on an existing resource, detach the credential (on the credentials page), turn the checks off, then enter the secret again. Without the permission the resource form does not offer the combination: the checkbox stays off for a resource with a credential, and a saved credential cannot be picked while it is ticked, each saying why; the credentials page's Attach does not offer resources with the checks off.

Orphans

Because a credential outlives its attachments, a credential that no resource references is an orphan. Orphans are surfaced distinctly in the manager as cleanup candidates — an otherwise-invisible dangling secret becomes a visible, one-click-deletable thing. When a credential becomes orphaned (its last attachment is removed or deleted), it's stamped with last_attached_to — a breadcrumb of what it was on, so you can still recognise it.

Orphan detection is a reverse query, not a stored counter: "which resources reference this credential" (resource_by_credential index). Zero rows → orphan.

Lifecycle

stateDiagram-v2
    [*] --> Orphaned: created standalone
    [*] --> Attached: created inline with a resource
    Orphaned --> Attached: attach to a resource
    Attached --> Attached: attach to / detach from another (still used)
    Attached --> Orphaned: last attachment removed (stamps last_attached_to)
    Orphaned --> [*]: deleted (allowed only when orphaned)
  • Create — standalone in the manager, or inline when creating a resource.
  • Attach — from the resource form ("use existing"), or from the manager's "Attach" picker. Attaching points a resource at the credential, where a resource using it already points (see above).
  • Detach / replace — removes one resource's use of it; the credential survives (it may be shared). Replacing a resource's credential detaches the old one the same way.
  • Delete — refused while any resource still uses it (409 Conflict); detach everywhere first. Deleting a location removes all of its credentials (they're location-scoped and can't be used elsewhere).

Relationship to rollback

Config rollback (see Config revisions, checkpoints & rollback) never touches credential attachments or secrets — snapshots don't contain secrets, and a rollback restores config fields only. A resource recreated by a rollback comes back without a credential, and a rollback that would move the address of a resource holding one to another host is refused, as the edit is. So a rollback never sends a credential somewhere new. The credential manager is the place to fix up attachments after a rollback if needed.

// 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.