Azure 金鑰保存庫 REST API 錯誤碼

  • 發行項

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 App 服務防火牆 存取。

您必須將 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 倍。 如果使用五個以上的金鑰保存庫，應該考慮使用多個訂用帳戶。

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