Verificatie, aanvragen en antwoorden

Azure Key Vault biedt twee typen containers voor het opslaan en beheren van geheimen voor uw cloudtoepassingen:

Dit zijn de achtervoegsels van de URL's die worden gebruikt voor toegang tot elk type object

Azure Key Vault ondersteunt door JSON opgemaakte aanvragen en antwoorden. Aanvragen voor Azure Key Vault worden omgeleid naar een geldige Azure Key Vault-URL met behulp van HTTPS met enkele URL-parameters en met JSON gecodeerde aanvraag- en antwoordteksten.

In dit artikel vindt u informatie over de Azure Key Vault-service. Zie azure REST API-referentiemateriaal voor algemene informatie over het gebruik van Azure REST-interfaces, waaronder verificatie/autorisatie en het verkrijgen van een toegangstoken.

Url-structuur aanvragen

Sleutelbeheerbewerkingen maken gebruik van HTTP-woorden, waaronder DELETE, GET, PATCH en PUT. Cryptografische bewerkingen op bestaande sleutelobjecten maken gebruik van HTTP POST.

Voor clients die specifieke HTTP-woorden niet kunnen ondersteunen, staat Azure Key Vault het gebruik van HTTP POST met de X-HTTP-REQUEST header toe om het beoogde werkwoord op te geven. Wanneer u POST als vervanging gebruikt (bijvoorbeeld in plaats van DELETE), neem dan een lege body op voor verzoeken die normaal gesproken geen body vereisen.

Als u wilt werken met objecten in Azure Key Vault, zijn de volgende voorbeeld-URL's:

• Om een sleutel genaamd TESTKEY aan te maken in een Key Vault te gebruiken - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• Als u een sleutel met de naam IMPORTEDKEY wilt importeren in een Sleutelkluis, gebruikt u - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• Gebruik - om een geheim met de naam MYSECRET in een Key Vault op te halenGET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• Om een samenvatting te ondertekenen met behulp van een sleutel genaamd TESTKEY in een Key Vault, gebruik - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• De autorisatie voor een aanvraag voor een Key Vault is altijd als volgt,

  • Voor kluizen: https://{keyvault-name}.vault.azure.net/
  • Voor beheerde HSM's: https://{HSM-name}.managedhsm.azure.net/ sleutels worden altijd opgeslagen onder het pad /keys, terwijl geheimen altijd worden opgeslagen onder het pad /secrets.

Ondersteunde API-versies

De Azure Key Vault-service biedt ondersteuning voor protocolversiebeheer om compatibiliteit te bieden met clients op lager niveau, hoewel niet alle mogelijkheden beschikbaar zijn voor deze clients. Clients moeten de api-version querytekenreeksparameter gebruiken om de versie op te geven van het protocol dat ze ondersteunen, omdat er geen standaardwaarde is.

Protocolversies van Azure Key Vault volgen een datumnummeringsschema met behulp van een {JJJJ}. {MM}. {DD}-indeling.

Vereisten voor de aanvraagbody

Volgens de HTTP-specificatie mogen GET-bewerkingen geen aanvraagbody hebben en moeten POST- en PUT-bewerkingen een aanvraagbody hebben. De hoofdtekst in DELETE-bewerkingen is optioneel in HTTP.

Tenzij anders vermeld in de beschrijving van de bewerking, moet het inhoudstype van de aanvraagtekst toepassing/json zijn en moet een geserialiseerd JSON-object bevatten dat voldoet aan het inhoudstype.

Tenzij anders vermeld in de omschrijving van de bewerking, moet de Accept-header het mediatype application/json bevatten.

Hoofdtekstindeling van antwoord

Tenzij anders vermeld in de beschrijving van de bewerking, is het inhoudstype antwoordtekst van zowel geslaagde als mislukte bewerkingen toepassing/json en bevat gedetailleerde foutinformatie.

HTTP POST gebruiken als alternatief

Sommige clients kunnen mogelijk bepaalde HTTP-woorden, zoals PATCH of DELETE, niet gebruiken. Azure Key Vault biedt ondersteuning voor HTTP POST als alternatief voor deze clients, mits de client ook de "X-HTTP-METHOD" header bevat om het oorspronkelijke HTTP-werkwoord aan te geven. Ondersteuning voor HTTP POST wordt vermeld voor elke API die in dit document is gedefinieerd.

Foutreacties verwerken

Foutafhandeling maakt gebruik van HTTP-statuscodes. Typische resultaten zijn:

• 2xx – Succes: Wordt gebruikt voor normale werking. De hoofdtekst van het antwoord bevat het verwachte resultaat

• 3xx – Omleiding: De 304 "Niet gewijzigd" kan worden geretourneerd om te voldoen aan een voorwaardelijke GET. Andere 3xx-codes kunnen in de toekomst worden gebruikt om DNS- en padwijzigingen aan te geven.

• 4xx – Clientfout: Gebruikt voor ongeldige aanvragen, ontbrekende sleutels, syntaxisfouten, ongeldige parameters, verificatiefouten, enzovoort. De hoofdtekst van het antwoord bevat gedetailleerde foutuitleg.

• 5xx – Serverfout: Wordt gebruikt voor interne serverfouten. De hoofdtekst van het antwoord bevat samengevatte foutinformatie.

  Het systeem is ontworpen om achter een proxy of firewall te werken. Daarom kan een client andere foutcodes ontvangen.

  Azure Key Vault retourneert ook foutinformatie in de hoofdtekst van het antwoord wanneer er een probleem optreedt. De hoofdtekst van het antwoord is opgemaakt met JSON en heeft de volgende vorm:

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

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

Authenticatievereisten

Alle aanvragen voor Azure Key Vault moeten worden geverifieerd. Azure Key Vault biedt ondersteuning voor Microsoft Entra-toegangstokens die kunnen worden verkregen met behulp van OAuth2 [RFC6749].

Zie Uw clienttoepassing registreren bij Microsoft Entra ID voor meer informatie over het registreren van uw toepassing en het verifiëren voor het gebruik van Azure Key Vault.

Toegangstokens moeten naar de service worden verzonden met behulp van de HTTP-autorisatieheader:

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

Wanneer er geen toegangstoken wordt opgegeven of wanneer de service geen token accepteert, wordt een HTTP 401-fout geretourneerd naar de client en wordt de WWW-Authenticate header opgenomen, bijvoorbeeld:

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

De parameters in de WWW-Authenticate header zijn:

• autorisatie: het adres van de OAuth2-autorisatieservice die kan worden gebruikt om een toegangstoken voor de aanvraag te verkrijgen.

• resource: de naam van de resource (https://vault.azure.net) die moet worden gebruikt in de autorisatieaanvraag.