Initial commit: VMware vSphere API simulator scaffold.

Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API contracts, docs, client examples, and the unit/integration/compatibility test suite for local client and tooling labs without a real vCenter.
2026-07-18 04:42:11 +03:00
commit f8d3cbdd59
422 changed files with 361335 additions and 0 deletions
@@ -0,0 +1,101 @@
+**Language / Язык:** [English](../authentication.md) | [Русский](authentication.md)
+
+# Аутентификация
+
+Основная плоскость: **vSphere Automation REST** sessions (`vmware-api-session-id`).
+SOAP `/sdk` использует собственные `Login`/`Logout` на VIM `SessionManager`. Опциональная
+legacy Proxmox stub-плоскость (`ENABLE_PVE_STUB=true`) сохраняет историческое поведение
+`/api2/json/access/ticket` из общей platform lineage — это не default lab path и далее
+не рассматривается.
+
+## Session login (REST)
+
+```http
+POST /api/session
+Authorization: Basic base64(user:password)
+```
+
+Успешный ответ:
+
+- Body: JSON string session id (например, `"a1b2c3…"`)
+- Header: `vmware-api-session-id: <id>`
+- Cookie: `vmware-api-session-id=<id>` (`SameSite=Strict`, TTL 2 часа)
+
+Legacy wrapper (те же credentials, форма `{ "value": "<session-id>" }`):
+
+```http
+POST /rest/com/vmware/cis/session
+Authorization: Basic base64(user:password)
+```
+
+### Вызов API
+
+```bash
+SID=$(curl -sk -u 'administrator@vsphere.local:VMware1!' \
+  -X POST 'https://localhost/api/session' | tr -d '"')
+
+curl -sk -H "vmware-api-session-id: $SID" \
+  'https://localhost/api/vcenter/vm'
+```
+
+Cookie-only клиенты также работают после login (`credentials: include` в
+браузерном Web UI).
+
+### Inspect / logout сессии
+
+| Метод | Путь | Заметки |
+|---|---|---|
+| GET | `/api/session` | HTTP 200 с заголовками `x-vmware-session-user` / `x-vmware-session-roles` |
+| DELETE | `/api/session` | Инвалидирует сессию и очищает cookie |
+| GET / DELETE | `/rest/com/vmware/cis/session` | Legacy эквиваленты `{ "value": … }` |
+
+Сессии хранятся в PostgreSQL (`vsphere_sessions`) с 2-часовым sliding
+expiry — каждый аутентифицированный запрос продлевает `expires_at`. Истёкшие сессии
+возвращают HTTP 401 при следующем lookup и лениво удаляются.
+
+## Засеянные lab principals
+
+Пароль для всех: `VMware1!`
+
+| Principal | Роль |
+|---|---|
+| `administrator@vsphere.local` | Administrator |
+| `readonly@vsphere.local` | ReadOnly |
+| `operator@vsphere.local` | VirtualMachinePowerUser |
+| `vmadmin@vsphere.local` | VirtualMachineAdministrator |
+
+Credentials хранятся в `vsphere_credentials` (scrypt-hashed passwords,
+массив `roles`) и идемпотентно re-insert'ятся при первом вызове `/api/session`
+и каждым seed profile. См. [Authorization](domains/authz.md) для модели
+привилегий и [Профили seed](seed-profiles.md) для соответствия четырёх
+principals inventory-scoped permissions.
+
+Mutating endpoints проверяют привилегии через `require_privilege(...)`; вызов
+mutate path как `readonly@vsphere.local` возвращает **403**.
+
+## SOAP `/sdk`
+
+```xml
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:vim25">
+  <soapenv:Body>
+    <urn:Login>
+      <urn:_this type="SessionManager">SessionManager</urn:_this>
+      <urn:userName>administrator@vsphere.local</urn:userName>
+      <urn:password>VMware1!</urn:password>
+    </urn:Login>
+  </soapenv:Body>
+</soapenv:Envelope>
+```
+
+`Login` выдаёт тот же underlying session id, возвращаемый как
+`vmware-api-session-id` и как cookie `vmware_soap_session`; последующие SOAP
+вызовы (pyvmomi, govmomi, Terraform provider `hashicorp/vsphere`, Pulumi)
+передают этот cookie автоматически. `Logout` удаляет сессию. См.
+[SOAP / VIM](domains/soap.md).
+
+## Опциональная legacy Proxmox stub
+
+Только при `ENABLE_PVE_STUB=true`: ticket login на `/api2/json/access/ticket`
+с `PVEAuthCookie` + CSRF, унаследованный от общей simulator platform, от которой
+этот проект fork'нулся. По умолчанию выключен (`ENABLE_PVE_STUB=false`) и
+не используется vSphere docs, examples или test suites в этом репозитории.