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,102 @@
+**Language / Язык:** [English](authentication.md) | [Русский](ru/authentication.md)
+
+# Authentication
+
+Primary plane: **vSphere Automation REST** sessions (`vmware-api-session-id`).
+SOAP `/sdk` uses its own `Login`/`Logout` on the VIM `SessionManager`. An
+optional legacy Proxmox stub plane (`ENABLE_PVE_STUB=true`) keeps historic
+`/api2/json/access/ticket` behavior from a shared platform lineage — it is not
+the default lab path and is not covered further here.
+
+## Session login (REST)
+
+```http
+POST /api/session
+Authorization: Basic base64(user:password)
+```
+
+Successful response:
+
+- Body: JSON string session id (e.g. `"a1b2c3…"`)
+- Header: `vmware-api-session-id: <id>`
+- Cookie: `vmware-api-session-id=<id>` (`SameSite=Strict`, 2 hour TTL)
+
+Legacy wrapper (same credentials, `{ "value": "<session-id>" }` shape):
+
+```http
+POST /rest/com/vmware/cis/session
+Authorization: Basic base64(user:password)
+```
+
+### Calling APIs
+
+```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 clients also work after login (`credentials: include` in the
+browser Web UI).
+
+### Session inspect / logout
+
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/api/session` | HTTP 200 with `x-vmware-session-user` / `x-vmware-session-roles` headers |
+| DELETE | `/api/session` | Invalidates the session and clears the cookie |
+| GET / DELETE | `/rest/com/vmware/cis/session` | Legacy `{ "value": … }` equivalents |
+
+Sessions live in PostgreSQL (`vsphere_sessions`) with a 2-hour sliding
+expiry — every authenticated request extends `expires_at`. Expired sessions
+return HTTP 401 on the next lookup and are lazily deleted.
+
+## Seeded lab principals
+
+Password for all: `VMware1!`
+
+| Principal | Role |
+|---|---|
+| `administrator@vsphere.local` | Administrator |
+| `readonly@vsphere.local` | ReadOnly |
+| `operator@vsphere.local` | VirtualMachinePowerUser |
+| `vmadmin@vsphere.local` | VirtualMachineAdministrator |
+
+Credentials are stored in `vsphere_credentials` (scrypt-hashed passwords,
+`roles` array) and are re-inserted idempotently on first `/api/session` call
+and by every seed profile. See [Authorization](domains/authz.md) for the
+privilege model and [Seed profiles](seed-profiles.md) for how the four
+principals map to inventory-scoped permissions.
+
+Mutating endpoints check privileges via `require_privilege(...)`; calling a
+mutate path as `readonly@vsphere.local` returns **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` issues the same underlying session id, returned as
+`vmware-api-session-id` and as a `vmware_soap_session` cookie; subsequent SOAP
+calls (pyvmomi, govmomi, the `hashicorp/vsphere` Terraform provider, Pulumi)
+carry that cookie automatically. `Logout` deletes the session. See
+[SOAP / VIM](domains/soap.md).
+
+## Optional legacy Proxmox stub
+
+Only when `ENABLE_PVE_STUB=true`: ticket login at `/api2/json/access/ticket`
+with `PVEAuthCookie` + CSRF, inherited from the shared simulator platform this
+project forked from. It is disabled by default (`ENABLE_PVE_STUB=false`) and
+is not exercised by the vSphere docs, examples, or test suites in this
+repository.