Udostępnij za pośrednictwem

Uwierzytelnianie, żądania i odpowiedzi

Usługa Azure Key Vault udostępnia dwa typy kontenerów do przechowywania i zarządzania tajemnicami dla aplikacji w chmurze.

Typ kontenera Obsługiwane typy obiektów Punkt końcowy płaszczyzny danych
Skarbce
  • Klucze chronione programowo
  • Klucze chronione za pomocą HSM (SKU Premium)
  • Certyfikaty
  • Klucze konta przechowywania danych
 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żywanych do uzyskiwania dostępu do każdego typu obiektu

Typ obiektu Sufiks adresu URL
Klucze chronione programowo /Klucze
Klucze chronione przez moduł HSM /Klucze
Tajemnice /Tajemnice
Certyfikaty /Certyfikaty
Klucze konta przechowywania danych /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 artykule opisano 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.

Struktura adresu URL żądania

Operacje zarządzania kluczami używają czasowników HTTP, takich jak DELETE, GET, PATCH i PUT. Operacje kryptograficzne na istniejących obiektach kluczy używają protokołu HTTP POST.

W przypadku klientów, którzy nie mogą obsługiwać określonych czasowników HTTP, usługa Azure Key Vault umożliwia użycie protokołu HTTP POST z nagłówkiem X-HTTP-REQUEST w celu określenia zamierzonego czasownika. W przypadku używania funkcji POST jako zamiennika (na przykład zamiast DELETE), dołącz pustą treść dla żądań, które zwykle jej nie wymagają.

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 POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

  • Uprawnienia dla żądania do usługi Key Vault są zawsze takie same.

    • W przypadku skarbcó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, podczas gdy sekrety są zawsze przechowywane w ścieżce /secrets.

Obsługiwane wersje 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 są 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 w formacie {YYYY}.{MM}.{DD}.

Wymagania dotyczące treści żą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 żądania Accept musi zawierać typ nośnika application/json.

Format treści 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 to application/json i zawiera szczegółowe informacje o błędzie.

Używanie protokołu HTTP POST jako alternatywy

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, jeśli klient zawiera również nagłówek "X-HTTP-METHOD" do określonego oryginalnego zlecenia HTTP. Obsługa protokołu HTTP POST jest opisana dla każdej zdefiniowanej w tym dokumencie API.

Obsługa odpowiedzi na błędy

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

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

  • 3xx — Przekierowanie: 304 "Niezmodyfikowane" może zostać zwrócone w celu spełnienia warunkowego żądania 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 zawiera szczegółowe wyjaśnienie błędu.

  • 5xx — błąd serwera: używany w przypadku wewnętrznych błędów serwera. Treść odpowiedzi 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’."  
    }  
  }  
}

Wymagania dotyczące uwierzytelniania

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 usługa nie akceptuje tokenu, zwracany jest błąd HTTP 401 do klienta i zawiera nagłówek WWW-Authenticate, na przykład:

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

Parametry na nagłówku 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 / Notatka

Klienci SDK Key Vault dla tajemnic, certyfikatów i kluczy podczas pierwszego wywołania Key Vault nie dostarczają tokenu dostępu do pobrania informacji o dzierżawcy. Oczekuje się otrzymanie kodu HTTP 401 przy użyciu klienta SDK Key Vault, w którym usługa Key Vault wyświetla aplikacji nagłówek WWW-Authenticate zawierający zasób i dzierżawcę, do której trzeba się udać 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.