Коды ошибок REST API службы Azure Key Vault

Статья
02/20/2024

Следующие коды ошибок могут быть возвращены в результате операции на веб-службе хранилища Azure Key Vault.

HTTP 401: запрос не прошел проверку подлинности

Код 401 означает, что запрос не прошел проверку подлинности для Key Vault.

Запрос проходит проверку подлинности, если:

хранилище ключей определило идентификатор вызывающего объекта и
вызывающему объекту разрешено попытаться получить доступ к ресурсам Key Vault.

Существует несколько причин, по которым запрос может вернуть ошибку 401.

Маркер проверки подлинности не подключен к запросу

Ниже приведен пример запроса PUT, задающий значение секрета:

PUT https://putreqexample.vault.azure.net//secrets/DatabaseRotatingPassword?api-version=7.0 HTTP/1.1
x-ms-client-request-id: 03d275a2-52a4-4bed-82c8-6fe15165affb
accept-language: en-US
Authorization: Bearer     eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSIsImtpZCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSJ9.eyJhdWQiOiJodHRwczovL3ZhdWx0LmF6dXJlLm5ldCIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0Ny8iLCJpYXQiOjE1NDg2OTc1MTMsIm5iZiI6MTU0ODY5NzUxMywiZXhwIjoxNTQ4NzAxNDEzLCJhaW8iOiI0MkpnWUhoODVqaVBnZHF5ZlRGZE5TdHY3bGUvQkFBPSIsImFwcGlkIjoiZmFkN2Q1YjMtNjlkNi00YjQ4LTkyNTktOGQxMjEyNGUxY2YxIiwiYXBwaWRhY3IiOiIxIiwiaWRwIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3LyIsIm9pZCI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInN1YiI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInV0aSI6IjItZ3JoUmtlSWs2QmVZLUxuNDJtQUEiLCJ2ZXIiOiIxLjAifQ.fgubiz1MKqTJTXI8dHIV7t9Fle6FdHrkaGYKcBeVRX1WtLVuk1QVxzIFDlZKLXJ7QPNs0KWpeiWQI9IWIRK-8wO38yCqKTfDlfHOiNWGOpkKddlG729KFqakVf2w0GPyGPFCONRDAR5wjQarN9Bt8I8YbHwZQz_M1hztlnv-Lmsk1jBmech9ujD9-lTMBmSfFFbHcqquev119V7sneI-zxBZLf8C0pIDkaXf1t8y6Xr8CUJDMdlWLslCf3pBCNIOy65_TyGvy4Z4AJryTPBarNBPwOkNAtjCfZ4BDc2KqUZM5QN_VK4foP64sVzUL6mSr0Gh7lQJIL5b1qIpJxjxyQ
User-Agent: FxVersion/4.7.3324.0 OSName/Windows OSVersion/6.2.9200.0 Microsoft.Azure.KeyVault.KeyVaultClient/3.0.3.0
Content-Type: application/json; charset=utf-8
Host: putreqexample.vault.azure.net
Content-Length: 31

{
   "value": "m*gBJ7$Zuoz)"
}

Заголовок "Authorization" — это маркер доступа, обязательный в каждом вызове Key Vault для операций в плоскости данных. Если этот заголовок отсутствует, ответ должен быть кодом 401.

Маркер не имеет правильного ресурса, связанного с ним

При запросе маркера доступа из конечной точки Azure OAUTH параметр с именем "resource" является обязательным. Это значение важно для поставщика маркеров, поскольку оно определяет область использования маркера по назначению. Ресурс для всех маркеров для доступа к Key Vault — https://vault.keyvault.net (без конечной косой черты).

Истек срок действия маркера.

Маркеры представлены в кодировке Base64, причем их значения можно декодировать на веб-сайтах, например http://jwt.calebb.net. Далее показано декодирование приведенного выше маркера.

    {
 typ: "JWT",
 alg: "RS256",
 x5t: "nbCwW11w3XkB-xUaXwKRSLjMHGQ",
 kid: "nbCwW11w3XkB-xUaXwKRSLjMHGQ"
}.
{
 aud: "https://vault.azure.net",
 iss: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 iat: 1548697513,
 nbf: 1548697513,
 exp: 1548701413,
 aio: "42JgYHh85jiPgdqyfTFdNStv7le/BAA=",
 appid: "fad7d5b3-69d6-4b48-9259-8d12124e1cf1",
 appidacr: "1",
 idp: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 oid: "3975aeed-7d08-453b-b6f4-445f32698091",
 sub: "3975aeed-7d08-453b-b6f4-445f32698091",
 tid: "72f988bf-86f1-41af-91ab-2d7cd011db47",
 uti: "2-grhRkeIk6BeY-Ln42mAA",
 ver: "1.0"
}.
[signature]

В этом маркере можно увидеть много важных частей.

aud (audience) — ресурс маркера. Обратите внимание, что он равен https://vault.azure.net. Этот маркер не будет работать для любого ресурса, который явно не соответствует этому значению, например graph.
iat (issued at) — число тактов с начала эпохи, когда был выдан маркер.
nbf (not before) — число тактов с начала эпохи, когда этот маркер стал действительным.
exp (expiration) — число тактов с начала эпохи, когда срок действия этого маркера истекает.
appid (application ID) — GUID для идентификатора приложения, выполнившего этот запрос.
tid (tenant ID) — GUID идентификатора арендатора субъекта, выполнившего этот запрос.

Для работы запроса важно, чтобы все значения были правильно указаны в маркере. Если все правильно, запрос не приведет к 401.

Устранение неполадок с кодом 401

Ошибки 401 необходимо исследовать, начиная с момента генерации маркера, до того, как осуществляется запрос к хранилищу ключей. Обычно для запроса маркера используется код. После получения маркера он передается в запрос Key Vault. Если код выполняется локально, можно использовать Fiddler для перехвата и регистрации запроса/ответа в https://login.microsoftonline.com. Запрос выглядит так:


POST https://login.microsoftonline.com/<key vault tenant ID>/oauth2/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 192

resource=https%3A%2F%2Fvault.azure.net&client_id=<registered-app-ID>&client_secret=<registered-app-secret>&client_info=1&grant_type=client_credentials

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

идентификатор арендатора хранилища ключей;
значение ресурса, установленное в https%3A%2F%2Fvault.azure.net (в кодировке URL).
ИД клиента
Секрет клиента

Убедитесь, что остальная часть запроса практически идентична.

Если вы можете получить только маркер доступа к ответу, его можно декодировать, чтобы убедиться, что идентификатор клиента, идентификатор клиента (идентификатор приложения) и ресурс.

HTTP 403: недостаточно прав

Код HTTP 403 означает, что запрос прошел проверку подлинности (запрашивающее удостоверение известно), но удостоверение не имеет разрешения на доступ к запрошенному ресурсу. Существуют две причины.

У удостоверения отсутствует политика доступа.
IP-адрес запрашивающего ресурса не утвержден в параметрах брандмауэра хранилища ключей.

Код HTTP 403 часто возникает, когда приложение клиента не использует идентификатор клиента, который, по мнению клиента, у него имеется. Это обычно означает, что политики доступа неправильно настроены для фактического вызывающего удостоверения.

Если сразу после добавления удостоверения в политику доступа возникает ошибка 403, вы можете обработать ее, добавив периодические повторные попытки.

Устранение неполадок с кодом 403

Во-первых, включите ведение журнала. Инструкции о том, как это сделать, см. в разделе Ведение журнала Azure Key Vault.

Включив ведение журнала, можно определить, вызвана ли ошибка 403 политикой доступа или политикой брандмауэра.

Ошибка из-за политики брандмауэра

"Адрес клиента (00.00.00.00) не авторизован, а вызывающий объект не является доверенной службой"

Существует ограниченный список "доверенных служб Azure". Веб-сайты Azure не являются доверенными службами Azure. Дополнительные сведения см. в записи блога Доступ к брандмауэру Key Vault с помощью служб приложений Azure.

Необходимо добавить IP-адрес веб-сайта Azure в хранилище Key Vault, чтобы доступ заработал.

Если ошибка возникает из-за политики доступа, найдите идентификатор объекта для запроса и убедитесь, что идентификатор объекта соответствует объекту, которому пользователь пытается назначить политику доступа. Часто в идентификаторе Microsoft Entra будет несколько объектов, которые имеют одно и то же имя, поэтому выбор правильного имеет значение. При удалении и чтении политики доступа можно увидеть, существуют ли несколько объектов с одинаковым именем.

Кроме того, большинство политик доступа не требует использования "авторизованного приложения", как показано на портале. Авторизованные приложения используются для сценариев проверки подлинности "от имени другого пользователя", которые применяются редко.

HTTP 429 — слишком много запросов

Регулирование происходит, когда количество запросов превышает заявленное максимальное значение для временного интервала. В случае регулирования в службе Key Vault возникнет ошибка HTTP 429. Для типов запросов указаны максимальные значения. Например, создание 2048-битного ключа HSM ограничено 10 запросами в течение 10 секунд, но все остальные транзакции HSM имеют ограничение в 2000 запросов за 10 секунд. Поэтому при определении причины ограничения частоты запросов важно понимать, какие типы вызовов выполняются. В общем случае запросы к Key Vault ограничены 4000 запросами за 10 секунд. К исключениям относятся операции с ключами, как описано в разделе Ограничения службы Key Vault

Устранение неполадок с кодом 429

Регулирование можно обойти с помощью этих методов:

Сократите количество запросов к Key Vault. Для этого определите закономерности обращений к запрашиваемому ресурсу и попытайтесь кэшировать обращения в вызывающем приложении.
При регулировании Key Vault адаптируйте запрашивающий код для использования экспоненциального обратного выхода для повтора. Этот алгоритм описан здесь: Как ограничить частоту запросов в приложении
Если количество запросов нельзя сократить с помощью кэширования, а временная задержка не работает, рассмотрите возможность разделения ключей между несколькими хранилищами Key Vault. Ограничение службы для одной подписки в 5 раз больше, чем ограничения отдельных хранилищ Key Vault. При использовании более пяти хранилищ ключей следует учитывать использование нескольких подписок.

Подробное руководство, а также сведения о запросах на увеличение ограничений можно найти здесь: Руководство по ограничению частоты запросов Key Vault.