**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 в этом репозитории.