Azure Key Vault REST API 错误代码Azure Key Vault REST API Error Codes

在 Azure Key Vault Web 服务中执行操作时,可能会返回以下错误代码。The following error codes could be returned by an operation on an Azure Key Vault web service.

HTTP 401:未经身份验证的请求HTTP 401: Unauthenticated Request

401 表示请求对 Key Vault 进行身份验证。401 means that the request is unauthenticated for Key Vault.

如果符合以下条件,则会对请求进行身份验证:A request is authenticated if:

  • Key Vault 知道调用方的标识;并且The key vault knows the identity of the caller; and
  • 允许调用方尝试访问 Key Vault 资源。The caller is allowed to try to access Key Vault resources.

有多种不同的原因会导致请求返回 401。There are several different reason why a request may return 401.

未将身份验证令牌附加到请求。No authentication token attached to the request.

下面是设置机密值的示例 PUT 请求:Here is an example PUT request, setting the value of a secret:

PUT https://putreqexample.vault.azure.cn/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.cn
Content-Length: 31

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

“Authorization”标头是访问令牌,每次调用 Key Vault 执行数据平面操作时,都需要提供此令牌。The "Authorization" header is the access token that is required with every call to the Key Vault for data-plane operations. 如果缺少该标头,则响应必须是 401。If the header is missing, then the response must be 401.

令牌缺少关联的适当资源。The token lacks the correct resource associated with it.

从 Azure OAUTH 终结点请求访问令牌时,必须提供名为“resource”的参数。When requesting an access token from the Azure OAUTH endpoint, a parameter called "resource" is mandatory. 该值对于令牌提供程序而言非常重要,因为它限定了令牌的目标使用范围。The value is important for the token provider because it scopes the token for its intended use. 用于访问 Key Vault 的所有令牌的资源为 https://vault.keyvault.cn(不包括尾部斜杠)。The resource for all tokens to access a Key Vault is https://vault.keyvault.cn (with no trailing slash).

令牌已过期The token is expired

令牌采用 base64 编码,可以在 http://jwt.calebb.net 之类的网站中将值解码。Tokens are base64 encoded and the values can be decoded at websites such as http://jwt.calebb.net. 下面是上述令牌在解码后的情况:Here is the above token decoded:

    {
 typ: "JWT",
 alg: "RS256",
 x5t: "nbCwW11w3XkB-xUaXwKRSLjMHGQ",
 kid: "nbCwW11w3XkB-xUaXwKRSLjMHGQ"
}.
{
 aud: "https://vault.azure.cn",
 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]

在此令牌中可以看到许多重要组成部分:We can see many important parts in this token:

  • aud(受众):令牌的资源。aud (audience): The resource of the token. 请注意,此资源为 https://vault.azure.cnNotice that this is https://vault.azure.cn. 对于不显式匹配此值的任何资源(例如 Graph),此令牌将不适用。This token will NOT work for any resource that does not explicitly match this value, such as graph.
  • iat(颁发时间):颁发令牌时距离纪元开始时间的计时周期数。iat (issued at): The number of ticks since the start of the epoch when the token was issued.
  • nbf(不早于):此令牌生效时距离纪元开始时间的计时周期数。nbf (not before): The number of ticks since the start of the epoch when this token becomes valid.
  • exp(过期时间):此令牌过期时距离纪元开始时间的计时周期数。exp (expiration): The number of ticks since the start of the epoch when this token expires.
  • appid(应用程序 ID):发出此请求的应用程序 ID 的 GUID。appid (application ID): The GUID for the application ID making this request.
  • tid(租户 ID):发出此请求的主体的租户 ID 的 GUIDtid (tenant ID): The GUID for the tenant ID of the principal making this request

必须在令牌中正确标识所有值才能使请求正常工作。It is important that all of the values be properly identified in the token in order for the request to work. 如果所有设置正确,则请求不会导致 401。If everything is correct, then the request will not result in 401.

故障排除 401Troubleshooting 401

在向 Key Vault 发出请求之前,应从令牌生成时间点开始调查 401 错误。401s should be investigated from the point of token generation, before the request is made to the key vault. 通常使用代码来请求令牌。Generally code is being used to request the token. 收到令牌后,会将其传入 Key Vault 请求。Once the token is received, it is passed into the Key Vault request. 如果代码在本地运行,则可以使用 Fiddler 捕获对 https://login.partner.microsoftonline.cn 的请求/响应。If the code is running locally, you can use Fiddler to capture the request/response to https://login.partner.microsoftonline.cn. 请求如下所示:A request looks like this:

POST https://login.partner.microsoftonline.cn/<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.cn&client_id=<registered-app-ID>&client_secret=<registered-app-secret>&client_info=1&grant_type=client_credentials

用户提供的以下信息必须正确:The following user-supplied information must be correct:

  • Key Vault 租户 IDThe key vault tenant ID
  • 设置为“https%3A%2F%2Fvault.azure.cn”(URL 编码)的资源值Resource value set to https%3A%2F%2Fvault.azure.cn (URL encoded)
  • 客户端 IDClient ID
  • 客户端机密Client secret

确保请求的剩余部分几乎完全相同。Ensure the rest of the request is nearly identical.

如果只能获取响应访问令牌,可将其解码(如上所示),以确保租户 ID、客户端 ID(应用 ID)和资源正确。If you can only get the response access token, you can decode it (as shown above) to ensure the tenant ID, the client ID (app ID), and the resource.

HTTP 403:权限不足HTTP 403: Insufficient Permissions

HTTP 403 表示请求已完成身份验证(知道请求方标识),但标识无权访问请求的资源。HTTP 403 means that the request was authenticated (it knows the requesting identity) but the identity does not have permission to access the requested resource. 此错误有两种原因:There are two causes:

  • 没有为标识设置访问策略。There is no access policy for the identity.
  • 请求方资源的 IP 地址未列入 Key Vault 防火墙设置中的允许列表。The IP address of the requesting resource is not whitelisted in the key vault's firewall settings.

如果客户的应用程序未使用客户端 ID,但客户认为已使用,则往往会出现 HTTP 403。HTTP 403 often occurs when the customer's application is not using the client ID that the customer thinks it is. 这通常意味着,未为实际调用方标识正确设置访问策略。That usually means that the access policies is not correctly set up for the actual calling identity.

排除故障 403Troubleshooting 403

首先启用日志记录。First, turn on logging. 有关说明,请参阅 Azure Key Vault 日志记录For instructions on how to do so, see Azure Key Vault logging.

启用日志记录后,可以确定 403 错误是由访问策略还是防火墙策略造成的。Once logging is turned on, you can determine if the 403 is due to access policy or firewall policy.

防火墙策略造成的错误Error due to firewall policy

“客户端地址(00.00.00.00)未获授权,调用方不是受信任的服务”"Client address (00.00.00.00) is not authorized and caller is not a trusted service"

有一个有限的“Azure 信任的服务”列表。There is a limited list of "Azure Trusted Services". Azure 网站不是受信任的 Azure 服务。Azure Web Sites are not a Trusted Azure Service.

必须将 Azure 网站的 IP 地址添加到 Key Vault 才能使其正常工作。You must add the IP address of the Azure Web Site to the Key Vault in order for it to work.

如果错误是访问策略造成的:请查找请求的对象 ID,并确保该对象 ID 与用户尝试将访问策略分配到的对象相匹配。If due to access policy: find the object ID for the request and ensure that the object ID matches the object to which the user is trying to assign the access policy. AAD 中往往有多个同名的对象,因此选择正确的对象非常重要。There will often be multiple objects in the AAD which have the same name, so choosing the correct one is very important. 可以通过删除并重新添加访问策略,来查看是否存在多个同名的对象。By deleting and re-adding the access policy, it is possible to see if multiple objects exist with the same name.

此外,大多数访问策略不需要按门户中所示使用“已授权的应用程序”。In addition, most access policies do not require the use of the "Authorized application" as shown in the portal. 已授权的应用程序用于“代理”身份验证方案,而这种方案极少出现。Authorized application are used for "on-behalf-of" authentication scenarios, which are rare.

HTTP 429:请求过多HTTP 429: Too Many Requests

当请求数超过时间范围规定的最大次数时,将发生限制。Throttling occurs when the number of requests exceeds the stated maximum for the timeframe. 如果发生限制,Key Vault 的响应将是 HTTP 429。If throttling occurs, the Key Vault's response will be HTTP 429. 发出的不同类型的请求有规定的最大次数。There are stated maximums for types of requests made. 例如:创建软件 2048 位密钥的请求规定为每 10 秒最多 10 次,但所有其他软件事务的限制为每 10 秒最多 2000 个请求。For instance: the creation of a Software 2048-bit key is 10 requests per 10 seconds, but all other Software transactions have a 2000 request/10 seconds limit. 因此,在确定限制的原因时,请务必了解所发出的调用类型。Therefore it is important to understand which types of calls are being made when determining the cause of throttling. 一般情况下,对 Key Vault 的请求数限制为每 10 秒 2000 个请求。In general, requests to the Key Vault are limited to 2000 requests/10 seconds. 密钥操作除外,具体请参阅 Key Vault 服务限制Exceptions are Key Operations, as documented in Key Vault service limits

故障排除 429Troubleshooting 429

使用以下方法克服限制:Throttling is worked around using these techniques:

  • 确定所请求资源是否存在模式并尝试在调用方应用程序中缓存这些模式,以此减少对 Key Vault 发出的请求数。Reduce number of requests made to the Key Vault by determining if there are patterns to a requested resource and attempting to cache them in the calling application.

  • 发生 Key Vault 限制时,调整请求代码以使用指数退避进行重试。When Key Vault throttling occurs, adapt the requesting code to use a exponential backoff for retrying. 以下文章解释了算法:如何限制应用The algorithm is explained here: How to throttle your app

  • 如果通过缓存无法减少请求数,并且计时退避不起作用,请考虑将密钥拆分到多个 Key Vault 中。If the number of requests cannot be reduced by caching and timed backoff does not work, then consider splitting the keys up into multiple Key Vaults. 单个订阅的服务限制是单个 Key Vault 限制的 5 倍。The service limit for a single subscription is 5x the individual Key Vault limit. 如果使用 5 个以上的 Key Vault,应考虑使用多个订阅。If using more than 5 Key Vaults, consideration should be given to using multiple subscriptions.

可在以下文章中找到详细的指导,包括如何请求提高限制:Azure Key Vault 限制指南Detailed guidance including request to increase limits, can be find here: Key Vault throttling guidance