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

2025-04-16

Операция с веб-службой 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. Маркер не работает для любого ресурса, который явно не соответствует значению, например графу.
iat (issued at) — число тактов с начала эпохи, когда был выдан маркер.
nbf (не раньше): число галок с начала эпохи, когда маркер становится допустимым.
exp (срок действия): число галок с момента начала эпохи, когда срок действия маркера истекает.
appid (идентификатор приложения): GUID для идентификатора приложения, выполняющего запрос.
tid (идентификатор клиента): 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. Дополнительные сведения см. в записи блога о доверенных службах.

Необходимо добавить 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.