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

# Авторизация

Gate роль → privilege для мутирующих REST-эндпоинтов (и decorator-style hook
для SOAP): [`app/vsphere/security/authz.py`](../../../app/vsphere/security/authz.py),
[`platform_rest.py`](../../../app/vsphere/rest/platform_rest.py).

## Эндпоинты

| Метод | Путь | Заметки |
|---|---|---|
| GET | `/api/vcenter/privilege` | Каталог привилегий |
| GET | `/api/vcenter/authorization/roles` | Role → набор privilege |
| GET/POST/DELETE | `/api/vcenter/authorization/permissions[/{permission_id}]` | Привязки principal ↔ role ↔ entity |
| GET/POST/PATCH/DELETE | `/api/vcenter/identity/providers[/{provider}]` | Stand-in'ы identity-provider LocalOS + OIDC + SAML |

## Роли (seed)

| Роль | Область |
|---|---|
| `Administrator` | Каждая привилегия в каталоге |
| `ReadOnly` | `System.Anonymous`, `System.Read`, `System.View`, `Datastore.Browse` |
| `VirtualMachinePowerUser` | Read + взаимодействия power/snapshot/clone |
| `VirtualMachineAdministrator` | Набор power-user + привилегии create/delete/reconfigure/tag/content-library |

`ROLE_PRIVILEGES` в `authz.py` задаёт точные наборы привилегий; неполный
пример gated-привилегий: `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`.

## Как работает gating

- `require_privilege(*needed)` — фабрика зависимостей FastAPI: резолвит
  сессию, загружает роли (из сессии или `vsphere_credentials`, если нет),
  и поднимает HTTP 403 (`unauthorized`), если отсутствует любая из
  перечисленных привилегий.
- `require_read` — сокращение для `require_privilege("System.Read")`.
- Permissions также могут ограничить роль конкретным entity MOID
  (`PermissionSpec(principal, role, entity_moid, propagate)`); seed
  ограничивает `readonly@vsphere.local` datacenter'ом, а двух VM-admin
  принципалов — папкой VM.

## Seeded-принципалы

Четыре принципала `@vsphere.local` и их роли — в
[Аутентификация](../authentication.md); как permissions скоупятся по
профилю — в [Профили seed](../seed-profiles.md).