Аутентификация и безопасность в 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 или обычной аутентификации, как описано ниже.

Unresolved include directive in modules/automation/pages/ovirt-api/auth.adoc - include::partial$oauth.adoc[]

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

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

Базовая аутентификация не поддерживается в среде zVirt с Keycloak.

Каждый запрос использует базовую аутентификацию 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.

Таблица 1. Кодирование учетных данных для доступа к 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.2. Сеансы аутентификации

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