Autentisering, begäranden och svar

Artikel
2025-04-17

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

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

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

Objekttyp	URL-suffix
Programvaruskyddade nycklar	/Nycklar
HSM-skyddade nycklar	/Nycklar
Hemligheter	/Hemligheter
Certifikaten	/certifikat
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.

Den här artikeln 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.

Url-struktur för begäranden

Nyckelhanteringsåtgärder använder HTTP-verb som DELETE, GET, PATCH och PUT. Kryptografiska åtgärder på befintliga nyckelobjekt använder HTTP POST.

För klienter som inte har stöd för specifika HTTP-verb tillåter Azure Key Vault användning av HTTP POST med X-HTTP-REQUEST rubriken för att ange det avsedda verbet. När du använder POST som ersättning (till exempel i stället för DELETE) ska du ta med en tom brödtext för begäranden som normalt inte kräver någon.

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
För att hämta en hemlighet som heter MYSECRET i en Key Vault, använd - 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
Myndigheten för en begäran till ett Key Vault är alltid som följer:
- 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, medan Hemligheter alltid lagras under sökvägen /secrets.

Supported API versions

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.

Krav för 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 begäranshuvudet Accept innehålla medietypen application/json.

Format för svarstext

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

Använda HTTP POST som ett alternativ

Vissa klienter kanske inte kan använda vissa HTTP-verb, till exempel PATCH eller DELETE. Azure Key Vault stöder HTTP POST som ett alternativ för dessa klienter om klienten även innehåller rubriken "X-HTTP-METHOD" för 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.

Hantera 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’."  
    }  
  }  
}

Autentiseringskrav

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 tjänsten inte accepterar en token, returneras ett HTTP 401-fel till klienten och innehåller WWW-Authenticate-huvudet, till exempel:

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

Parametrarna i WWW-Authenticate-huvudet ä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.

Anmärkning

Key Vault SDK-klienter för hemligheter, certifikat och nycklar i det första anropet till Key Vault levererar inte en åtkomsttoken för att hämta hyresgästinformation. Det förväntas att en HTTP 401 tas emot vid användning av Key Vault SDK-klienten, där Key Vault visar för programmet det WWW-Authenticate-huvudfält som innehåller resursen och den hyresgäst där det behöver gå för att begära en token. Om allt är korrekt konfigurerat innehåller det andra anropet från programmet till Key Vault en giltig token och lyckas.

Dela via