Azure 金鑰保存庫 REST API 錯誤碼

發行項
09/06/2024

Azure 金鑰保存庫 Web 服務上的作業可能會傳回下列錯誤碼。

HTTP 401：未驗證的要求

401 表示要求未經驗證，金鑰保存庫。

如果：

金鑰保存庫知道呼叫者的身分識別;和
允許呼叫端嘗試存取金鑰保存庫資源。

要求可能會傳回 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)"
}

「授權」標頭是數據平面作業的每個呼叫金鑰保存庫所需的存取令牌。如果標頭遺失，則響應必須是 401。

令牌缺少與其相關聯的正確資源

從 Azure OAUTH 端點要求存取令牌時，必須有稱為「資源」的參數。對於令牌提供者而言，此值很重要，因為它會將令牌的範圍限定為其預定用途。存取金鑰保存庫之所有令牌的資源為 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 （發行於）：發行令牌時自 epoch 開始以來的刻度數目。
nbf （不是之前）：當這個令牌變成有效時，自 epoch 開頭以來的刻度數。
exp （到期）：自此令牌到期后，自 epoch 開頭以來的刻度數。
appid （應用程式識別符）：提出此要求之應用程式識別碼的 GUID。
tid （租使用者標識符）：提出此要求之主體之租用戶標識碼的 GUID

請務必在令牌中正確識別所有值，以便要求能夠運作。如果一切正確，則要求不會產生 401。

疑難解答 401

在對密鑰保存庫提出要求之前，應該先從令牌產生點調查 401。一般而言，程式代碼是用來要求令牌。收到令牌之後，它會傳入金鑰保存庫要求。如果程式代碼在本機執行，您可以使用 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 金鑰保存庫記錄。

開啟記錄之後，您可以判斷 403 是否因為存取原則或防火牆原則所致。

因為防火牆原則而發生錯誤

「用戶端位址（00.00.00.00.00）未獲授權，且呼叫者不是受信任的服務」

「Azure 信任的服務」清單有限。 Azure 網站不是信任的 Azure 服務。如需詳細資訊，請參閱部落格文章信任的服務。

您必須將 Azure 網站的 IP 位址新增至金鑰保存庫，才能運作。

如果由於存取原則：尋找要求的物件標識符，並確定對象標識元符合用戶嘗試指派存取原則的物件。 Microsoft Entra ID 中，通常會有多個物件具有相同的名稱，因此選擇正確的物件很重要。藉由刪除和讀取存取原則，就可以查看多個物件是否存在同名。

此外，大部分的存取原則都不需要使用「已授權的應用程式」，如入口網站所示。授權的應用程式會用於「代表」驗證案例，這是罕見的。

HTTP 429：太多要求

當要求數目超過指定時間範圍的最大值時，就會進行節流。如果發生節流，Key Vault 的回應將會是 HTTP 429。所提出要求類型的最大數目。例如：建立 HSM 2048 位密鑰是每 10 秒 10 個要求，但所有其他 HSM 交易的限制為 2,000 個要求/10 秒。因此，請務必瞭解判斷節流原因時，要進行哪種類型的呼叫。一般而言，對金鑰保存庫的要求限製為4,000個要求/10秒。例外狀況為金鑰作業，如金鑰保存庫服務限制中所述

疑難解答 429

節流是使用下列技術來解決的：

藉由判斷要求的資源是否有模式，並嘗試在呼叫的應用程式中加以快取，減少對 Key Vault 提出的要求數目。
發生金鑰保存庫節流時，請調整要求程式碼以使用指數輪詢重試。此處將說明演算法：如何節流您的應用程式
如果快取無法減少要求數目，且計時輪詢無法運作，請考慮將金鑰分割成多個 Key Vault。單一訂用帳戶的服務限制是個別 Key Vault 限制的 5 倍。如果使用五個以上的金鑰保存庫，應該考慮使用多個訂用帳戶。

如需詳細指引，包括增加限制的要求，請參閱這裡：金鑰保存庫節流指引

共用方式為