Files

T

inecs f8d3cbdd59 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

3.5 KiB

Raw Blame History

Language / Язык: English | Русский

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.

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):

POST /rest/com/vmware/cis/session
Authorization: Basic base64(user:password)

Calling APIs

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 for the privilege model and Seed profiles 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`

<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.

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.

3.5 KiB Raw Blame History