Autentisering, begäranden och svar

Artikel
08/07/2024

Azure Key Vault innehåller två typer av containrar för att lagra och hantera hemligheter för dina molnprogram:

Behållartyp	Objekttyper som stöds	Dataplansslutpunkt
Valv	Programvaruskyddade nycklar HSM-skyddade nycklar (med Premium SKU) Certifikat Lagringskontonycklar	https://{vault-name}.vault.azure.net
Hanterad HSM	HSM-skyddade nycklar	https://{hsm-name}.managedhsm.azure.net

Här är URL-suffixen som används för att komma åt varje typ av objekt

Object type	URL-suffix
Programvaruskyddade nycklar	/Nycklar
HSM-skyddade nycklar	/Nycklar
Hemligheter	/Hemligheter
Certifikat	/certifikaten
Lagringskontonycklar	/storageaccounts

Azure Key Vault stöder JSON-formaterade begäranden och svar. Begäranden till Azure Key Vault dirigeras till en giltig Azure Key Vault-URL med HTTPS med vissa URL-parametrar och JSON-kodade begärande- och svarsorgan.

Det här avsnittet beskriver detaljer för Azure Key Vault-tjänsten. Allmän information om hur du använder Azure REST-gränssnitt, inklusive autentisering/auktorisering och hur du hämtar en åtkomsttoken, finns i Referens för Azure REST API.

Begärans-URL

Nyckelhanteringsåtgärder använder HTTP DELETE-, GET-, PATCH-, PUT- och HTTP POST-åtgärder och kryptografiska åtgärder mot befintliga nyckelobjekt använder HTTP POST. Klienter som inte stöder specifika HTTP-verb kan också använda HTTP POST med huvudet X-HTTP-REQUEST för att ange det avsedda verbet. begäranden som normalt inte kräver en brödtext ska innehålla en tom brödtext när du använder HTTP POST, till exempel när du använder POST i stället för DELETE.

Följande är exempel-URL:er för att arbeta med objekt i Azure Key Vault:

Skapa en nyckel med namnet TESTKEY i en Key Vault-användning – PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1
Importera en nyckel med namnet IMPORTEDKEY till en Key Vault-användning – POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1
Hämta en hemlighet med namnet MYSECRET i en Key Vault-användning – GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1
Så här signerar du en sammandrag med en nyckel med namnet TESTKEY i en Key Vault-användning – POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1
Utfärdaren för en begäran till ett Key Vault är alltid följande:
- För valv: https://{keyvault-name}.vault.azure.net/
- För hanterade HSM:er: https://{HSM-name}.managedhsm.azure.net/
Nycklar lagras alltid under sökvägen /keys. Hemligheter lagras alltid under sökvägen /secrets.

API-version

Azure Key Vault Service stöder protokollversionering för att ge kompatibilitet med klienter på låg nivå, men alla funktioner är inte tillgängliga för dessa klienter. Klienter måste använda frågesträngsparametern api-version för att ange den version av protokollet som de stöder eftersom det inte finns någon standard.

Azure Key Vault-protokollversioner följer ett datumnumreringsschema med hjälp av {YYYY}. {MM}. {DD} format.

Begärandetext

Enligt HTTP-specifikationen får GET-åtgärderna INTE ha någon begärandetext, och POST- och PUT-åtgärderna måste ha en begärandetext. Brödtexten i DELETE-åtgärder är valfri i HTTP.

Om inget annat anges i åtgärdsbeskrivningen måste innehållstypen för begärandetexten vara application/json och innehålla ett serialiserat JSON-objekt som överensstämmer med innehållstypen.

Om inget annat anges i åtgärdsbeskrivningen måste huvudet Acceptera begäran innehålla medietypen application/json.

Svarstext

Om inget annat anges i åtgärdsbeskrivningen kommer innehållstypen för svarstexten för både lyckade och misslyckade åtgärder att vara application/json och innehåller detaljerad felinformation.

Använda HTTP POST

Vissa klienter kanske inte kan använda vissa HTTP-verb, till exempel PATCH eller DELETE. Azure Key Vault har stöd för HTTP POST som ett alternativ för dessa klienter, förutsatt att klienten även innehåller rubriken "X-HTTP-METHOD" för att specifika det ursprungliga HTTP-verbet. Stöd för HTTP POST noteras för vart och ett av de API:er som definierats i det här dokumentet.

Felsvar

Felhantering använder HTTP-statuskoder. Typiska resultat är:

2xx – Lyckades: Används för normal drift. Svarstexten innehåller det förväntade resultatet
3xx – Omdirigering: 304 "Inte ändrad" kan returneras för att uppfylla en villkorsstyrd GET. Andra 3xx-koder kan användas i framtiden för att ange DNS- och sökvägsändringar.
4xx – Klientfel: Används för felaktiga begäranden, saknade nycklar, syntaxfel, ogiltiga parametrar, autentiseringsfel osv. Svarstexten innehåller detaljerad felförklaring.
5xx – Serverfel: Används för interna serverfel. Svarstexten innehåller sammanfattad felinformation.

Systemet är utformat för att fungera bakom en proxy eller brandvägg. Därför kan en klient få andra felkoder.

Azure Key Vault returnerar också felinformation i svarstexten när ett problem uppstår. Svarstexten är JSON-formaterad och har formatet :


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

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

Autentisering

Alla begäranden till Azure Key Vault MÅSTE autentiseras. Azure Key Vault stöder Microsoft Entra-åtkomsttoken som kan hämtas med OAuth2 [RFC6749].

Mer information om hur du registrerar ditt program och autentiserar för att använda Azure Key Vault finns i Registrera ditt klientprogram med Microsoft Entra-ID.

Åtkomsttoken måste skickas till tjänsten med http-auktoriseringshuvudet:

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

När en åtkomsttoken inte har angetts, eller när en token inte godkänns av tjänsten, returneras ett HTTP 401-fel till klienten och innehåller rubriken WWW-Authenticate, till exempel:

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

Parametrarna i rubriken WWW-Authenticate är:

auktorisering: Adressen till OAuth2-auktoriseringstjänsten som kan användas för att hämta en åtkomsttoken för begäran.
resurs: Namnet på resursen (https://vault.azure.net) som ska användas i auktoriseringsbegäran.

Kommentar

Key Vault SDK-klienter för hemligheter, certifikat och nycklar i det första anropet till Key Vault ger inte en åtkomsttoken för hämtning av klientorganisationsinformation. Den förväntas att en HTTP 401 tas emot med hjälp av Key Vault SDK-klienten, där Key Vault visar för programmet det WWW-Authenticate-huvud som innehåller resursen och den klientorganisation dit den behöver gå och fråga efter token. Om allt är korrekt konfigurerat innehåller det andra anropet från programmet till Key Vault en giltig token och lyckas.

Dela via