Аутентификация и безопасность в REST API

1. TLS/SSL-сертификация

API zVirt требует защищенного протокола передачи гипертекста (HTTPS) для безопасного взаимодействия с клиентским программным обеспечением, таким как компоненты SDK и CLI. Это включает в себя получение сертификата ЦС, используемого сервером, и его импорт в хранилище сертификатов вашего клиента.

1.1. Получение CA сертификата

Вы можете получить CA сертификат от Менеджера управления zVirt и передать его на клиентскую машину одним из следующих способов:

1.1.1. Способ 1

Предпочтительный метод получения CA сертификата — использовать инструмент командной строки openssl s_client для выполнения реального рукопожатия TLS с сервером, а затем извлечь сертификаты, которые он представляет. Запустите команду следующим образом:

$ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null

Эта команда подключится к серверу и отобразит вывод, подобный следующему:

CONNECTED(00000003)
depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
verify error:num=19:self signed certificate in certificate chain
---
Certificate chain
 0 s:/C=US/O=Example Inc./CN=myengine.example.com
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----END CERTIFICATE-----
 1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----

Текст между маркерами -----BEGIN CERTIFICATE----- и -----END CERTIFICATE----- показывает сертификаты, представленные сервером. Первый — это сертификат самого сервера, а последний — CA сертификат. Скопируйте CA сертификат вместе с метками в файл ca.crt. Результат должен выглядеть так:

Это самый надежный способ получить CA сертификат, используемый сервером. Остальные описанные здесь способы сработают в большинстве случаев, но они не дадут правильный CA сертификат, если он был вручную заменен администратором сервера.

1.1.2. Способ 2

Если вы не можете использовать описанный выше метод openssl s_client, вы можете вместо этого использовать инструмент командной строки для загрузки CA сертификата из Менеджера управления zVirt.

Примеры инструментов командной строки включают curl и wget, оба из которых доступны на нескольких платформах.

При использовании curl:

$ curl \
--output ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

При использовании wget:

$ wget \
--output-document ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

1.1.3. Способ 3

С помощью веб-браузера перейдите к сертификату, расположенному по адресу:

https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA

В зависимости от выбранного браузера сертификат загружается или импортируется в хранилище ключей браузера.

Если браузер загружает сертификат: сохраните файл как ca.crt.
Если браузер импортирует сертификат: экспортируйте его из параметров сертификации браузера и сохраните как ca.crt.

1.1.4. Способ 4

Войдите в Менеджер управления, экспортируйте сертификат из хранилища доверенных сертификатов и скопируйте его на свой клиентский компьютер.

Войдите на машину с Менеджером управления как root.
Экспортируйте сертификат из хранилища доверенных сертификатов с помощью утилиты keytool:
keytool \ -keystore /etc/pki/ovirt-engine/.truststore \ -storepass mypass \ -exportcert \ -alias cacert \ -rfc \ -file ca.crt
Это создает файл сертификата с именем ca.crt.
Скопируйте сертификат на клиентскую машину с помощью команды scp:
```
$ scp ca.crt myuser@myclient.example.com:/home/myuser/.
```

Каждый из этих методов приводит к созданию файла сертификата с именем ca.crt на клиентском компьютере. Затем вы должны импортировать этот файл в хранилище сертификатов клиента.

1.2. Импорт сертификата в клиент

Импорт сертификата клиенту зависит от того, как клиент хранит и интерпретирует сертификаты. Дополнительную информацию об импорте сертификата см. в документации вашего клиента.

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

Любой пользователь с учетной записью Менеджера управления имеет доступ к API. Все запросы должны быть аутентифицированы с использованием OAuth или обычной аутентификации, как описано ниже.

2.1. OAuth-аутентификация

Предпочтительным механизмом аутентификации является OAuth 2.0, как описано в RFC 6749.

OAuth — это сложный протокол с несколькими механизмами получения токенов авторизации и доступа. Для использования с API поддерживается только предоставление учетных данных владельца ресурса, как описано в разделе 4.3 RFC 6749.

Сначала необходимо получить токен, отправив имя пользователя и пароль в службу единого входа Менеджера управления:

POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

Тело запроса должно содержать параметры grant_type, scope, username и password:

Таблица 1. Параметры запроса токена OAuth
Имя	Значение
grant_type	password
scope	ovirt-app-api
username	api-user@internalsso
password	mypassword

Эти параметры должны быть представлены в URL кодировке. Например, символ @ в имени пользователя должен быть закодирован как %40. Результирующее тело запроса будет примерно таким:

grant_type=password&scope=ovirt-app-api&username=admin%40zvirt%40internalsso&password=mypassword

Для работы с сервисами REST API настоятельно рекомендуем создать отдельного пользователя с правами, достаточными для выполнения необходимых операций.

Здесь и далее в качестве username используется api-user@internalsso.

Параметр scope описан как необязательный в OAuth RFC, но при использовании его с API он является обязательным, и его значение должно быть ovirt-app-api.

Если имя пользователя и пароль верны, служба единого входа Менеджера управления ответит документом JSON, подобным этому:

{
  "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
  "token_type": "bearer",
  "scope": "...",
  ...
}

Для целей аутентификации API единственной подходящей парой имя/значение является access_token. Ни в коем случае не манипулируйте этим; используйте его точно так, как это предусмотрено службой единого входа.

После получения токена его можно использовать для выполнения запросов к API, включив его в заголовок HTTP Authorization и используя схему Bearer. Например, чтобы получить список виртуальных машин, отправьте такой запрос:

GET /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=

Токен можно использовать несколько раз для нескольких запросов, но в конечном итоге срок его действия истечет. По истечении этого срока сервер отклонит запрос с кодом ответа HTTP 401:

HTTP/1.1 401 Unauthorized

В этом случае требуется новый токен, так как служба единого входа Менеджера управления в настоящее время не поддерживает обновление токенов. Новый токен можно запросить тем же способом, который описан выше.

2.2. Базовая аутентификация

Базовая аутентификация поддерживается только для обратной совместимости; она устарела и будет удалена в будущем.

Каждый запрос использует базовую аутентификацию HTTP для кодирования учетных данных. Если запрос не включает соответствующий заголовок Authorization, сервер отправляет ответ 401 Authorization Required:

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com

HTTP/1.1 401 Authorization Required

Запрос выдается с заголовком Authorization для указанной области. Закодируйте соответствующий домен и имя пользователя в предоставленных учетных данных с помощью соглашения username@domain:password.

В следующей таблице показан процесс кодирования учетных данных в Base64.

Таблица 2. Кодирование учетных данных для доступа к API
Элемент	Значение
Имя пользователя	admin@zvirt
Домен	internalsso
Пароль	mypassword
Незакодированные учетные данные	api-user@internalsso:mypassword
Учетные данные в кодировке Base64	YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

Укажите учетные данные в кодировке Base64, как показано ниже:

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK

Базовая аутентификация включает потенциально конфиденциальную информацию, такую как пароли, отправляемые в виде обычного текста. Для API требуется безопасный протокол передачи гипертекста (HTTPS) для шифрования на транспортном уровне простых текстовых запросов.

Некоторые библиотеки Base64 разбивают результат на несколько строк и заканчивают каждую строку символом новой строки. Это ломает заголовок и вызывает ошибочный запрос. Для заголовка Authorization требуются закодированные учетные данные в одной строке заголовка.

2.3. Сеансы аутентификации

API также обеспечивает поддержку сеанса аутентификации. Отправьте первоначальный запрос с данными аутентификации, а затем отправьте все последующие запросы, используя файл cookie сеанса для аутентификации.

Запрос аутентифицированного сеанса

Отправьте запрос с заголовками Authorization и Prefer: persistent-auth:
HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA== Prefer: persistent-auth HTTP/1.1 200 OK ...
Он возвращает ответ со следующим заголовком:
Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure
Обратите внимание на значение JSESSIONID=. В этом примере значение равно 5dQja5ubr4yvI2MM2z+LZxrK.
Отправляйте все последующие запросы с заголовками Prefer: persistent-auth и Cookie с соответствующим значением JSESSIONID=. Заголовок Authorization больше не нужен при использовании аутентифицированного сеанса.
```
HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Prefer: persistent-auth
Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK

HTTP/1.1 200 OK
...
```
Когда сеанс больше не требуется, выполните запрос к серверу без заголовка Prefer: persistent-auth.
```
HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK
...
```