Kody błędów interfejsu API REST usługi Azure Key Vault
Następujące kody błędów mogą być zwracane przez operację w usłudze internetowej usługi Azure Key Vault.
HTTP 401: nieuwierzytelnione żądanie
401 oznacza, że żądanie jest nieuwierzytelnione dla usługi Key Vault.
Żądanie jest uwierzytelniane, jeśli:
- Magazyn kluczy zna tożsamość obiektu wywołującego; I
- Obiekt wywołujący może spróbować uzyskać dostęp do zasobów usługi Key Vault.
Istnieje kilka powodów, dla których żądanie może zwrócić 401.
Brak tokenu uwierzytelniania dołączonego do żądania
Oto przykładowe żądanie PUT, ustawiając wartość wpisu tajnego:
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)"
}
Nagłówek "Autoryzacja" to token dostępu wymagany z każdym wywołaniem usługi Key Vault na potrzeby operacji płaszczyzny danych. Jeśli brakuje nagłówka, odpowiedź musi mieć wartość 401.
Token nie ma skojarzonego z nim odpowiedniego zasobu
Podczas żądania tokenu dostępu z punktu końcowego protokołu OAUTH platformy Azure parametr o nazwie "resource" jest obowiązkowy. Wartość jest ważna dla dostawcy tokenów, ponieważ określa zakres tokenu do jego zamierzonego użycia. Zasób dla wszystkich tokenów dostępu do usługi Key Vault to https://vault.keyvault.net (bez ukośnika końcowego).
Token wygasł
Tokeny są zakodowane w formacie base64, a wartości można dekodować w witrynach internetowych, takich jak http://jwt.calebb.net. Poniżej przedstawiono powyższy token zdekodowany:
{
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]
W tym tokenie można zobaczyć wiele ważnych części:
- aud (odbiorcy): zasób tokenu. Zwróć uwagę, że jest
https://vault.azure.netto . Ten token nie będzie działać dla żadnego zasobu, który nie jest jawnie zgodny z tą wartością, na przykład dla grafu. - iat (wystawiony pod adresem): liczba kleszczy od początku epoki, gdy token został wystawiony.
- nbf (nie wcześniej): liczba kleszczy od początku epoki, gdy ten token stanie się prawidłowy.
- exp (wygaśnięcie): liczba znaczników od początku epoki, gdy ten token wygaśnie.
- appid (identyfikator aplikacji): identyfikator GUID identyfikatora aplikacji wysyłającego to żądanie.
- tid (identyfikator dzierżawy): identyfikator GUID dla identyfikatora dzierżawy podmiotu zabezpieczeń wysyłającego to żądanie
Ważne jest, aby wszystkie wartości zostały prawidłowo zidentyfikowane w tokenie, aby żądanie działało. Jeśli wszystko jest poprawne, żądanie nie spowoduje błędu 401.
Rozwiązywanie problemów 401
401s należy zbadać z punktu generowania tokenu, zanim żądanie zostanie wykonane do magazynu kluczy. Zazwyczaj kod jest używany do żądania tokenu. Po odebraniu tokenu jest on przekazywany do żądania usługi Key Vault. Jeśli kod działa lokalnie, możesz użyć programu Fiddler do przechwycenia żądania/odpowiedzi na https://login.microsoftonline.comadres . Żądanie wygląda następująco:
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
Następujące informacje dostarczone przez użytkownika muszą być poprawne:
- Identyfikator dzierżawy magazynu kluczy
- Wartość zasobu ustawiona na https%3A%2F%2Fvault.azure.net (zakodowany adres URL)
- Identyfikator klienta
- Wpis tajny klienta
Upewnij się, że pozostałe żądania są prawie identyczne.
Jeśli możesz uzyskać tylko token dostępu odpowiedzi, możesz go zdekodować, aby upewnić się, że identyfikator dzierżawy, identyfikator klienta (identyfikator aplikacji) i zasób.
HTTP 403: niewystarczające uprawnienia
HTTP 403 oznacza, że żądanie zostało uwierzytelnione (zna tożsamość żądającą), ale tożsamość nie ma uprawnień dostępu do żądanego zasobu. Istnieją dwie przyczyny:
- Nie ma żadnych zasad dostępu dla tożsamości.
- Adres IP żądanego zasobu nie jest zatwierdzony w ustawieniach zapory magazynu kluczy.
Protokół HTTP 403 często występuje, gdy aplikacja klienta nie korzysta z identyfikatora klienta, który klient uważa za to. Zwykle oznacza to, że zasady dostępu nie są poprawnie skonfigurowane dla rzeczywistej tożsamości wywołującej.
Jeśli natychmiast po dodaniu tożsamości do zasad dostępu zostanie wyświetlony błąd 403, możesz go obsłużyć, dodając okresowe ponawianie próby.
Rozwiązywanie problemów 403
Najpierw włącz rejestrowanie. Aby uzyskać instrukcje dotyczące tego, jak to zrobić, zobacz Rejestrowanie usługi Azure Key Vault.
Po włączeniu rejestrowania można określić, czy wartość 403 jest spowodowana zasadami dostępu lub zasadami zapory.
Błąd spowodowany zasadami zapory
"Adres klienta (00.00.00.00) nie jest autoryzowany, a obiekt wywołujący nie jest zaufaną usługą"
Istnieje ograniczona lista "Zaufanych usług platformy Azure". Witryny internetowe platformy Azure nie są zaufaną usługą platformy Azure. Aby uzyskać więcej informacji, zobacz wpis w blogu Dotyczący dostępu do zapory usługi Key Vault przez usługi aplikacja systemu Azure Services.
Aby działała, musisz dodać adres IP witryny internetowej platformy Azure do usługi Key Vault.
Jeśli ze względu na zasady dostępu: znajdź identyfikator obiektu dla żądania i upewnij się, że identyfikator obiektu jest zgodny z obiektem, do którego użytkownik próbuje przypisać zasady dostępu. W identyfikatorze Entra firmy Microsoft często występuje wiele obiektów, które mają taką samą nazwę, dlatego wybranie prawidłowego obiektu jest ważne. Usuwając i odczytując zasady dostępu, można sprawdzić, czy istnieje wiele obiektów o tej samej nazwie.
Ponadto większość zasad dostępu nie wymaga użycia "Autoryzowanej aplikacji", jak pokazano w portalu. Autoryzowane aplikacje są używane w scenariuszach uwierzytelniania "w imieniu", które są rzadkie.
HTTP 429: zbyt wiele żądań
Gdy liczba żądań przekracza maksimum określone dla horyzontu czasowego, następuje ograniczenie przepustowości. Jeśli wystąpi ograniczanie przepustowości, usługa Key Vault odpowie komunikatem o będzie HTTP 429. Istnieją określone maksymalne wartości dla typów żądań. Na przykład: utworzenie klucza 2048-bitowego HSM to 10 żądań na 10 sekund, ale wszystkie inne transakcje HSM mają limit 2000 żądań/10 sekund. Dlatego ważne jest, aby zrozumieć, jakie typy wywołań są wykonywane podczas określania przyczyny ograniczania przepustowości. Ogólnie rzecz biorąc, żądania do usługi Key Vault są ograniczone do 4000 żądań/10 sekund. Wyjątki to operacje klucza, zgodnie z dokumentacją w temacie Limity usługi Key Vault
Rozwiązywanie problemów związanych z błędem 429
Problem z ograniczaniem przepustowości można obejść, wykonując następujących czynności:
Zmniejsz liczbę żądań do usługi Key Vault, określając, czy istnieją wzorce żądanego zasobu i próbując buforować je w wywołującej aplikacji.
Po wystąpieniu ograniczania usługi Key Vault dostosuj kod żądający, aby użyć wycofywania wykładniczego w celu ponawiania próby. Algorytm został wyjaśniony tutaj: Jak ograniczyć przepustowość aplikacji
Jeśli liczby żądań nie można zmniejszyć przez buforowanie, a odczekiwanie nie działa, rozważ rozdzielenie kluczy na wiele magazynów kluczy. Limit usługi dla pojedynczej subskrypcji to pięciokrotność limitu pojedynczego magazynu kluczy. W przypadku korzystania z więcej niż pięciu magazynów kluczy należy wziąć pod uwagę używanie wielu subskrypcji.
Szczegółowe wskazówki, w tym żądanie zwiększenia limitów, można znaleźć tutaj: Wskazówki dotyczące ograniczania przepustowości usługi Key Vault