Uwierzytelnianie, żądania i odpowiedzi

  • Artykuł

Usługa Azure Key Vault udostępnia dwa typy kontenerów do przechowywania wpisów tajnych dla aplikacji w chmurze i zarządzania nimi:

Typ kontenera Obsługiwane typy obiektów Punkt końcowy płaszczyzny danych
Sklepienia
  • Klucze chronione programowo
  • Klucze chronione przez moduł HSM (z jednostkami SKU w warstwie Premium)
  • Certyfikaty
  • Klucze kont magazynu
 https://{nazwa magazynu}.vault.azure.net
Zarządzany moduł HSM
  • Klucze chronione przez moduł HSM
 https://{hsm-name}.managedhsm.azure.net

Poniżej przedstawiono sufiksy adresów URL używane do uzyskiwania dostępu do każdego typu obiektu

Object type Sufiks adresu URL
Klucze chronione programowo /Klucze
Klucze chronione przez moduł HSM /Klucze
Wpisy tajne /Tajemnice
Certyfikaty /Certyfikaty
Klucze kont magazynu /storageaccounts

Usługa Azure Key Vault obsługuje żądania i odpowiedzi w formacie JSON. Żądania do usługi Azure Key Vault są kierowane do prawidłowego adresu URL usługi Azure Key Vault przy użyciu protokołu HTTPS z pewnymi parametrami adresu URL i kodowanymi treściami żądania i odpowiedzi w formacie JSON.

W tym temacie omówiono szczegółowe informacje dotyczące usługi Azure Key Vault. Aby uzyskać ogólne informacje na temat korzystania z interfejsów REST platformy Azure, w tym uwierzytelniania/autoryzacji i sposobu uzyskiwania tokenu dostępu, zobacz Dokumentacja interfejsu API REST platformy Azure.

Zażądaj URL

Operacje zarządzania kluczami korzystają z operacji HTTP DELETE, GET, PATCH, PUT i HTTP POST oraz operacji kryptograficznych względem istniejących obiektów kluczy przy użyciu protokołu HTTP POST. Klienci, którzy nie mogą obsługiwać określonych czasowników HTTP, mogą również używać żądania HTTP POST przy użyciu nagłówka X-HTTP-REQUEST w celu określenia zamierzonego zlecenia; żądania, które zwykle nie wymagają treści, powinny zawierać pustą treść podczas korzystania z protokołu HTTP POST, na przykład w przypadku używania funkcji POST zamiast DELETE.

Aby pracować z obiektami w usłudze Azure Key Vault, oto przykładowe adresy URL:

  • Aby utworzyć klucz o nazwie TESTKEY w usłudze Key Vault, użyj polecenia — PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • Aby zaimportować klucz o nazwie IMPORTKEY do usługi Key Vault, użyj polecenia — POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • Aby uzyskać wpis tajny o nazwie MYSECRET w usłudze Key Vault, użyj polecenia — GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • Aby podpisać skrót przy użyciu klucza o nazwie TESTKEY w usłudze Key Vault, użyj polecenia — POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

  • Urząd żądania do usługi Key Vault jest zawsze następujący:

    • W przypadku magazynów: https://{keyvault-name}.vault.azure.net/
    • W przypadku zarządzanych modułów HSM: https://{HSM-name}.managedhsm.azure.net/

    Klucze są zawsze przechowywane w ścieżce /keys, wpisy tajne są zawsze przechowywane w ścieżce /secrets.

Wersja interfejsu API

Usługa Azure Key Vault obsługuje przechowywanie wersji protokołu w celu zapewnienia zgodności z klientami na poziomie podrzędnym, chociaż nie wszystkie funkcje będą dostępne dla tych klientów. Klienci muszą użyć parametru api-version ciągu zapytania, aby określić wersję protokołu, który obsługuje, ponieważ nie ma wartości domyślnej.

Wersje protokołu usługi Azure Key Vault są zgodne ze schematem numerowania dat przy użyciu elementu {RRRR}. {MM}. Format {DD}.

Treść żądania

Zgodnie ze specyfikacją HTTP operacje GET nie mogą mieć treści żądania, a operacje POST i PUT muszą mieć treść żądania. Treść operacji DELETE jest opcjonalna w protokole HTTP.

O ile nie określono inaczej w opisie operacji, typ zawartości treści żądania musi być application/json i musi zawierać serializowany obiekt JSON zgodny z typem zawartości.

Jeśli nie określono inaczej w opisie operacji, nagłówek Akceptuj żądanie musi zawierać typ nośnika application/json.

Treść odpowiedzi

O ile nie określono inaczej w opisie operacji, typ zawartości treści odpowiedzi zarówno operacji zakończonych powodzeniem, jak i niepowodzeniem będzie dotyczyć aplikacji/json i zawiera szczegółowe informacje o błędzie.

Korzystanie z protokołu HTTP POST

Niektórzy klienci mogą nie być w stanie używać określonych czasowników HTTP, takich jak PATCH lub DELETE. Usługa Azure Key Vault obsługuje protokół HTTP POST jako alternatywę dla tych klientów, pod warunkiem, że klient zawiera również nagłówek "X-HTTP-METHOD" do określonego oryginalnego zlecenia HTTP. Obsługa protokołu HTTP POST jest zanotowany dla każdego interfejsu API zdefiniowanego w tym dokumencie.

Odpowiedzi na błędy

Obsługa błędów będzie używać kodów stanu HTTP. Typowe wyniki to:

  • 2xx — sukces: używany do normalnego działania. Treść odpowiedzi będzie zawierać oczekiwany wynik

  • 3xx — przekierowanie: 304 "Niezmodyfikowane" może zostać zwrócone w celu spełnienia warunkowego get. Inne kody 3xx mogą być używane w przyszłości w celu wskazania zmian dns i ścieżki.

  • 4xx — błąd klienta: używany w przypadku nieprawidłowych żądań, brakujących kluczy, błędów składni, nieprawidłowych parametrów, błędów uwierzytelniania itp. Treść odpowiedzi będzie zawierać szczegółowe wyjaśnienie błędu.

  • 5xx — błąd serwera: używany w przypadku wewnętrznych błędów serwera. Treść odpowiedzi będzie zawierać podsumowane informacje o błędzie.

    System jest przeznaczony do pracy za serwerem proxy lub zaporą. W związku z tym klient może otrzymać inne kody błędów.

    Usługa Azure Key Vault zwraca również informacje o błędach w treści odpowiedzi, gdy wystąpi problem. Treść odpowiedzi jest sformatowana w formacie JSON i ma postać:


{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}

Uwierzytelnianie

Wszystkie żądania do usługi Azure Key Vault muszą być uwierzytelnione. Usługa Azure Key Vault obsługuje tokeny dostępu firmy Microsoft, które można uzyskać przy użyciu protokołu OAuth2 [RFC6749].

Aby uzyskać więcej informacji na temat rejestrowania aplikacji i uwierzytelniania w celu korzystania z usługi Azure Key Vault, zobacz Rejestrowanie aplikacji klienckiej w usłudze Microsoft Entra ID.

Tokeny dostępu muszą być wysyłane do usługi przy użyciu nagłówka autoryzacji HTTP:

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>

Jeśli token dostępu nie zostanie podany lub gdy token nie zostanie zaakceptowany przez usługę, zostanie zwrócony błąd HTTP 401 do klienta i będzie zawierać nagłówek WWW-Authenticate, na przykład:

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"

Parametry nagłówka WWW-Authenticate to:

  • autoryzacja: adres usługi autoryzacji OAuth2, która może służyć do uzyskania tokenu dostępu dla żądania.

  • resource: nazwa zasobu (https://vault.azure.net) do użycia w żądaniu autoryzacji.

Uwaga

Klienci zestawu Key Vault SDK dla wpisów tajnych, certyfikatów i kluczy w pierwszym wywołaniu usługi Key Vault nie udostępniają tokenu dostępu umożliwiającego pobranie informacji o dzierżawie. Oczekuje się otrzymanie kodu HTTP 401 przy użyciu klienta zestawu Key Vault SDK, w którym usługa Key Vault wyświetla aplikacji nagłówek WWW-Authenticate zawierający zasób oraz dzierżawę, do której należy przejść w celu uzyskania tokenu. Jeśli wszystko jest poprawnie skonfigurowane, drugie wywołanie usługi Key Vault z aplikacji będzie zawierać prawidłowy token i zakończy się pomyślnie.