Proxmox VE / Intermediate: data, identity and policy / Lesson 11

Realms, roles and API authorization

Model identity and scoped privileges without exposing credentials or granting administrative access.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish identity realms, authentication and authorization.
Explain path-scoped roles and privilege inheritance.
Review API-token scope and lifecycle separately from user login.

Separate identity from permission

A realm identifies the authentication domain of a user, while roles and access-control entries determine permitted platform actions. A username without its realm can be ambiguous. Successful login establishes authentication within that mechanism, not permission to change every guest or storage object. External directory availability and local platform authorization also fail differently. Keep the identity provider, exact principal and intended task explicit in a diagnostic record. Public examples use synthetic principal names only and never include passwords, token values, recovery codes or exports from a real access-control system.

Scope roles to resources

Proxmox privileges are grouped into roles and assigned along platform resource paths, with propagation affecting descendants where configured. A broad role at a high path can exceed the intended task even if a user currently sees only a few guests. The first record describes an observational duty on a synthetic pool rather than a runnable ACL. Separate viewing status from console access, power operations, backup, storage allocation and permission changes. A role name should be inspected through its actual privileges and scope, not trusted because it sounds like a harmless support role.

text A least-privilege review record

principal: observer@pve (synthetic)
intended duty: view approved guest status in training pool
review scope: resource path and propagation
excluded decisions: console, power, storage allocation, permission changes

The text creates no user, role or ACL and does not assert a particular built-in role meets this duty.

Understand token boundaries

API tokens support automation identity and can have separate privilege and expiration decisions. With privilege separation, effective access is constrained by both the associated user’s permissions and the token’s permissions; inspect the selected release’s rules rather than assuming a token can exceed its user. The second program illustrates a simple set intersection, not the complete Proxmox ACL evaluator. Token secrecy and token authorization are distinct concerns. A narrowly scoped token still needs secure handling and revocation, and a secret value should never be printed to demonstrate that an example is complete.

python Conceptual separated-token intersection

user_permissions = {"view", "power"}
token_permissions = {"view", "backup"}
print(sorted(user_permissions & token_permissions))

Expected output

['view']

Only view survives this toy model. It omits path inheritance, privilege definitions and the real authorization engine.

Diagnose the exact action

When an operation is denied, record the authenticated principal, target path, requested action and applicable role evidence. A task can involve more than one resource, such as guest access plus storage allocation, so granting a broad administrator role is an unjustified shortcut. Confirm whether the failure is authentication, authorization or an external dependency before proposing changes. For a real review, use approved read-only evidence from the access owner. This course performs no login, API request, permission enumeration or credential inspection; it teaches the questions needed to narrow the cause.

Plan identity lifecycle and audit

Access design includes onboarding, least privilege, multi-factor requirements where applicable, token rotation, expiration, revocation and emergency recovery ownership. Removing an employee’s interactive access may not be the entire automation cleanup if tokens or external integrations remain. Audit records should relate actions to exact principals without exposing secrets. Keep administrative duties separated where policy requires it and review changes to high-level inherited rights carefully. The local set model proves a narrow arithmetic relationship only. Actual permissions, realm behavior and audit coverage require release-specific authorized validation and cannot be inferred from a displayed role label.

Common errors and fixes

Login success is interpreted as authority over every guest

Why it happens: Authentication and authorization were conflated.
How to fix it: Review exact actions and resource paths under applicable roles.
Prevent it next time: Keep authentication and permission evidence separate.

An API token is assumed to exceed its user’s separated rights

Why it happens: Token and user scope interaction was not understood.
How to fix it: Review both permission sets and the release-specific token model.
Prevent it next time: Document automation principals and privilege-separation choices.

A high-level broad role fixes one denied action

Why it happens: The requested privilege and target dependencies were not identified.
How to fix it: Determine the minimum scoped privileges needed for the approved duty.
Prevent it next time: Review propagation and resource paths before granting rights.

Check your understanding

1. Why is observer@pve more precise than observer in an access incident?

Show worked solution

The realm disambiguates the authentication domain. Similar usernames can belong to different identity sources and have different lifecycle and permission evidence. Still record the target path and action: a precise principal alone does not explain why a particular operation was denied or allowed.

2. The toy token requests backup but its user lacks backup. What does the model return and omit?