**Language / Язык:** [English](authz.md) | [Русский](../ru/domains/authz.md)

# Authorization

Role → privilege gate for REST mutate endpoints (and a decorator-style hook
for SOAP): [`app/vsphere/security/authz.py`](../../app/vsphere/security/authz.py),
[`platform_rest.py`](../../app/vsphere/rest/platform_rest.py).

## Endpoints

| Method | Path | Notes |
|---|---|---|
| GET | `/api/vcenter/privilege` | Privilege catalog |
| GET | `/api/vcenter/authorization/roles` | Role → privilege set |
| GET/POST/DELETE | `/api/vcenter/authorization/permissions[/{permission_id}]` | Principal ↔ role ↔ entity bindings |
| GET/POST/PATCH/DELETE | `/api/vcenter/identity/providers[/{provider}]` | LocalOS + OIDC + SAML identity-provider stand-ins |

## Roles (seed)

| Role | Scope |
|---|---|
| `Administrator` | Every privilege in the catalog |
| `ReadOnly` | `System.Anonymous`, `System.Read`, `System.View`, `Datastore.Browse` |
| `VirtualMachinePowerUser` | Read + power/snapshot/clone interactions |
| `VirtualMachineAdministrator` | Power-user set + create/delete/reconfigure/tag/content-library privileges |

`ROLE_PRIVILEGES` in `authz.py` defines the exact privilege sets; a
non-exhaustive sample of gated privileges: `VirtualMachine.Inventory.Create`,
`VirtualMachine.Inventory.Delete`, `VirtualMachine.Interact.PowerOn`,
`VirtualMachine.Config.CPUCount`, `VirtualMachine.Provisioning.Clone`,
`Datastore.FileManagement`, `Network.Assign`,
`InventoryService.Tagging.CreateTag`, `ContentLibrary.AddLibraryItem`,
`Authorization.ModifyPermissions`.

## How gating works

- `require_privilege(*needed)` is a FastAPI dependency factory: it resolves
  the session, loads roles (from the session or `vsphere_credentials` if
  absent), and raises HTTP 403 (`unauthorized`) if any listed privilege is
  missing.
- `require_read` is shorthand for `require_privilege("System.Read")`.
- Permissions can also scope a role to a specific entity MOID
  (`PermissionSpec(principal, role, entity_moid, propagate)`); the seed
  scopes `readonly@vsphere.local` to the datacenter and the two VM-admin
  principals to the VM folder.

## Seeded principals

See [Authentication](../authentication.md) for the four
`@vsphere.local` principals and their roles, and
[Seed profiles](../seed-profiles.md) for how permissions are scoped per
profile.