Product SiteDocumentation Site

⁠44.2. Аутентификация

Есть два способа доступа к API PVE:
  • использование временно сгенерированного токена (билета);
  • использование API-токена.
Все API-запросы должны включать в себя билет в заголовке Cookie или отправлять API-токен через заголовок Authorization.

⁠44.2.1. Аутентификация с использованием билета

Билет аутентификации (ticket) — это подписанное значение, связанное с учётной записью пользователя и временем выдачи. Билет подписывается общекластерным ключом аутентификации, который обновляется один раз в день.
Для аутентификации с использованием билета его передают в cookie PVEAuthCookie. Для запросов, изменяющих состояние системы (POST, PUT, DELETE), дополнительно требуется заголовок CSRFPreventionToken. Это предотвращает выполнение нежелательных запросов в рамках CSRF-атак (межсайтовой подделки запросов).
Пример получения нового билета и CSRF-токена:
$ curl -k -d 'username=root@pam' --data-urlencode 'password=xxxxxxxxx' \
https://192.168.0.186:8006/api2/json/access/ticket

Примечание

Пароль, передаваемый в командной строке, может быть доступен другим пользователям системы через средства просмотра процессов. Поэтому не следует передавать пароль таким способом на недоверенных узлах
Пример получения нового билета и CSRF-токена с паролем, сохранённым в файле, доступном для чтения только владельцу:
$ curl -k -d 'username=root@pam' --data-urlencode "password@$HOME/.pve-pass-file" \
https://192.168.0.186:8006/api2/json/access/ticket

Примечание

Файл .pve-pass-file должен содержать пароль без завершающего символа перевода строки. Доступ к файлу необходимо ограничить, например, разрешив чтение только его владельцу:
$ echo -n "пароль" > ./.pve-pass-file
$ chmod 600 "$HOME/.pve-pass-file"

Примечание

Для форматирования JSON-ответа можно использовать команду jq (должен быть установлен пакет jq):
$ curl -k -d 'username=root@pam' --data-urlencode "password@$HOME/.pve-pass-file" \
https://192.168.0.186:8006/api2/json/access/ticket | jq
Пример ответа:
{
  "data": {
    "ticket":"PVE:root@pam:66AA52D6::d85E+IIFAuG731…",
    "CSRFPreventionToken":"66AA52D6:Y2zvIXjRVpxx4ZG74F14Ab0EHn8NRoso/WmVqZEnAuM",
    "username":"root@pam"
  }
}

Примечание

Билет действителен в течение двух часов. По истечении срока действия билета необходимо получить новый билет. До истечения этого срока можно получить новый билет, передав старый билет в качестве пароля методу /access/ticket до истечения срока его действия.
Полученный билет необходимо передавать с Cookie при любом запросе, например:
$ curl -k -b "PVEAuthCookie=PVE:root@pam:66AA52D6::d85E+IIFAuG731…" \
https://192.168.0.186:8006/api2/json/
Ответ:
{
  "data": [
    { "subdir": "version" },
    { "subdir": "cluster" },
    { "subdir": "nodes" },
    { "subdir": "storage" },
    { "subdir": "access" },
    { "subdir": "pools" }
  ]
}

Примечание

Для передачи данных в заголовке Cookie используется параметр --cookie (-b).
Любой запрос на запись (POST, PUT, DELETE), кроме билета, должен включать заголовок CSRFPreventionToken, например:
$ curl -k -X 'DELETE' \
'https://pve01:8006/api2/json/access/users/testuser@pve' \
-b "PVEAuthCookie=PVE:root@pam:66AA52D6::d85E+IIFAuG731…" \
-H "CSRFPreventionToken: 66AA52D6:Y2zvIXjRVpxx4ZG74F14Ab0EHn8NRoso/WmVqZEnAuM"