inecs
f8d3cbdd59
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.
103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
**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.
|