Аутентификация, запросы и ответы

Статья
08/07/2024

Azure Key Vault предоставляет два типа контейнеров для хранения секретов для облачных приложений и управления ими.

Тип контейнера	Поддерживаемые типы объектов	Конечная точка плоскости данных
Хранилища	Ключи, защищенные с помощью ПО Ключи, защищенные модулем HSM (с ценовой категорией Premium) Сертификаты Ключи учетной записи хранения	https://{имя_хранилища}.vault.azure.net
Управляемый модуль HSM	Ключи, защищенные модулем HSM	https://{имя_hsm}.managedhsm.azure.net

Ниже приведены суффиксы URL-адресов, используемые для доступа к каждому типу объектов.

Тип объекта	Суффикс URL-адреса
Ключи, защищенные с помощью ПО	/keys
Ключи, защищенные модулем HSM	/keys
Секреты	/secrets
Сертификаты	/certificates
Ключи учетной записи хранения	/storageaccounts

Azure Key Vault поддерживает запросы и ответы в формате JSON. Запросы к Azure Key Vault направляются на допустимый URL-адрес Azure Key Vault с помощью HTTPS с некоторыми параметрами URL-адреса и текстом запроса и ответа в формате JSON.

Здесь рассматривается служба Azure Key Vault. Общие сведения об использовании интерфейсов Azure REST, в том числе об аутентификации и авторизации, а также о том, как получить маркер доступа, см. в справочнике по Azure REST API.

Запросить URL-адрес

Операции управления ключами используют команды HTTP DELETE, GET, PATCH, PUT и HTTP POST, а криптографические операции с существующими объектами ключей используют HTTP POST. Клиенты, не поддерживающие определенные HTTP-команды, также могут использовать HTTP POST, указав нужную команду в заголовке X-HTTP-REQUEST. Запросы, которым обычно не требуется текст, должны включать пустой текст при использовании HTTP POST, например при использовании команды POST вместо DELETE.

Ниже приведены примеры URL-адресов для работы с объектами в Azure Key Vault.

Чтобы создать ключ под названием TESTKEY в Key Vault, используйте команду PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1
Чтобы импортировать ключ под названием IMPORTEDKEY в Key Vault, используйте команду POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1
Чтобы получить секрет под названием MYSECRET в Key Vault, используйте команду GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1
Чтобы подписать хэш-код с помощью ключа под названием TESTKEY в Key Vault, используйте команду POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1
Объект авторизации для запроса к Key Vault всегда выглядит следующим образом:
- Для хранилищ: https://{keyvault-name}.vault.azure.net/
- Для управляемых модулей HSM: https://{HSM-name}.managedhsm.azure.net/
Ключи всегда хранятся в пути /keys, а секреты всегда хранятся в пути /secrets.

Версия API

Служба Azure Key Vault поддерживает управление версиями протоколов для обеспечения совместимости с клиентами нижнего уровня, хотя этим клиентам будут доступны не все возможности. Клиенты должны использовать параметр строки запроса api-version, чтобы указать поддерживаемую версию протокола, так как значение по умолчанию отсутствует.

Версии протокола Azure Key Vault следуют схеме нумерации дат в формате {ГГГГ}.{ММ}.{ДД}.

Текст запроса

Согласно спецификации протокола HTTP операции GET не должны иметь текст запроса, а операции POST и PUT должны. Текст в операциях DELETE является необязательным в HTTP.

Если иное не указано в описании операции, то тип содержимого текста запроса должен быть "application/json" и текст должен содержать сериализованный объект JSON, совместимый с типом содержимого.

Если иное не указано в описании операции, заголовок запроса Accept должен содержать тип носителя "application/json".

Текст ответа

Если иное не указано в описании операции, типом содержимого для успешных и неудачных операций будет "application/json", а текст запроса будет содержать подробные сведения об ошибках.

Использование HTTP POST

Некоторые клиенты могут не иметь возможность использовать определенные HTTP-команды, например PATCH или DELETE. В качестве альтернативы для таких клиентов Azure Key Vault поддерживает HTTP POST. При этом клиент также должен включить заголовок X-HTTP-METHOD для определенной исходной HTTP-команды. Поддержка HTTP POST указана для каждого из API в этом документе.

Сообщения об ошибках

Для обработки ошибок используются коды состояния HTTP. Ниже приведены примеры типичных результатов.

"2xx — успешно": используется для нормальной работы. Текст ответа будет содержать ожидаемый результат.
"3xx — перенаправление": ответ "304 — объект не изменялся" может быть возвращен для выполнения условной операции GET. Другие коды 3xx могут использоваться в дальнейшем для указания изменений DNS и пути.
4xx — ошибка клиента: используются для неправильных запросов, отсутствующих ключей, синтаксических ошибок, недопустимых параметров, ошибок проверки подлинности и т. д. Текст ответа будет содержать подробные сведения об ошибке.
"5xx — ошибка сервера": используется для внутренних ошибок сервера. Текст ответа будет содержать сводные сведения об ошибке.

Система должна работать с использованием прокси-сервера или брандмауэра. Таким образом, клиент может получать другие коды ошибок.

Azure Key Vault также возвращает сведения об ошибке в тексте ответа при возникновении проблемы. Текст ответа возвращается в формате JSON и имеет такой вид:


{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}

Проверка подлинности

Все запросы к Azure Key Vault должны пройти проверку подлинности. Azure Key Vault поддерживает маркеры доступа Microsoft Entra, которые могут быть получены с помощью OAuth2 [RFC6749].

Дополнительные сведения о регистрации приложения и проверке подлинности для использования Azure Key Vault см. в статье "Регистрация клиентского приложения с помощью идентификатора Microsoft Entra".

Маркеры доступа должны отправляться в службу с помощью заголовка авторизации HTTP:

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>

Если маркер доступа не задан или не принимается службой, клиенту будет возвращена ошибка HTTP 401 с заголовком WWW-Authenticate, например:

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"

Параметры в заголовке WWW-Authenticate:

authorization: адрес службы авторизации OAuth2, который может использоваться для получения маркера доступа для запроса.
resource: имя ресурса (https://vault.azure.net) для использования в запросе авторизации.

Примечание.

Клиенты пакета SDK для Key Vault для секретов, сертификатов и ключей при первом вызове не предоставляют маркер доступа для получения сведений о клиенте. Предполагается, что получение HTTP 401 осуществляется с помощью клиента SDK для Key Vault, в процессе чего Key Vault указывает приложению заголовок WWW-Authenticate, содержащий ресурс и клиент, к которому оно должно обратиться и запросить маркер. Если все настроено правильно, второй вызов из приложения в Key Vault будет содержать действительный токен и будет успешно обработан.

Поделиться через