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

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

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

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

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

Структура URL-адреса запроса

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

Для клиентов, которые не могут поддерживать определенные HTTP-команды, Azure Key Vault позволяет использовать HTTP POST с заголовком X-HTTP-REQUEST , чтобы указать предназначенную команду. При использовании POST в качестве замены (например, вместо DELETE) включите пустое тело для запросов, которые обычно в нём не нуждаются.

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

• Чтобы СОЗДАТЬ ключ с именем 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

• Полномочия для запроса к хранилищу ключей всегда следующие.

  • Для хранилищ: https://{keyvault-name}.vault.azure.net/
  • Для управляемых HSM: https://{HSM-name}.managedhsm.azure.net/ ключи всегда хранятся в пути /key, а секреты всегда хранятся в пути /secret.

Supported API versions

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

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

Требования к тексту запроса

В спецификации 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 Authorization.

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:

• авторизация: адрес службы авторизации OAuth2, который может быть использован для получения токена доступа для запроса.

• ресурс: имя ресурса (https://vault.azure.net) для использования в запросе авторизации.