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