Verificatie, vragen en antwoorden

Artikel
08/07/2024

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

Containertype	Ondersteunde objecttypen	Eindpunt van gegevensvlak
Kluizen	Met software beveiligde sleutels Met HSM beveiligde sleutels (met Premium SKU) Certificaten Opslagaccountsleutels	https://{vault-name}.vault.azure.net
Beheerde HSM	HSM-beveiligde sleutels	https://{hsm-name}.managedhsm.azure.net

Dit zijn de URL-achtervoegsels die worden gebruikt voor toegang tot elk type object

Object type	URL-achtervoegsel
Met software beveiligde sleutels	/keys
HSM-beveiligde sleutels	/keys
Geheimen	/secrets
Certificaten	/certificates
Opslagaccountsleutels	/storageaccounts

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 onderwerp 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.

Aanvraag-URL

Sleutelbeheerbewerkingen maken gebruik van HTTP DELETE, GET, PATCH, PUT en HTTP POST en cryptografische bewerkingen voor bestaande sleutelobjecten maken gebruik van HTTP POST. Clients die specifieke HTTP-woorden niet kunnen ondersteunen, kunnen ook HTTP POST gebruiken met behulp van de X-HTTP-REQUEST-header om het beoogde werkwoord op te geven; aanvragen waarvoor normaal gesproken geen hoofdtekst is vereist, moeten een lege hoofdtekst bevatten bij het gebruik van HTTP POST, bijvoorbeeld bij het gebruik van POST in plaats van DELETE.

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

Een sleutel maken met de naam TESTKEY in een Key Vault- 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
Een geheim ophalen met de naam MYSECRET in een Key Vault- GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1
Een samenvatting ondertekenen met behulp van een sleutel met de naam TESTKEY in een Key Vault-gebruik - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1
De autoriteit voor een aanvraag bij 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, geheimen worden altijd opgeslagen onder het pad /secrets.

API-versie

De Azure Key Vault-service biedt ondersteuning voor protocolversiebeheer om compatibiliteit met clients op lager niveau te bieden, 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.

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 beschrijving van de bewerking, moet de header Aanvraag accepteren het mediatype application/json bevatten.

Hoofdtekst van antwoord

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

HTTP POST gebruiken

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 header X-HTTP-METHOD bevat voor specifiek het oorspronkelijke HTTP-werkwoord. Ondersteuning voor HTTP POST wordt vermeld voor elke API die in dit document is gedefinieerd.

Foutreacties

Bij foutafhandeling worden HTTP-statuscodes gebruikt. 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 foutgegevens.

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

Verificatie

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 een token niet wordt geaccepteerd door de service, wordt een HTTP 401-fout geretourneerd naar de client en wordt de header WWW-Authenticate opgenomen, bijvoorbeeld:

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

De parameters in de header WWW-Authenticate 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.

Notitie

Key Vault SDK-clients voor geheimen, certificaten en sleutels in de eerste aanroep naar Key Vault bieden geen toegang token voor het ophalen van tenantgegevens. Het wordt verwacht een HTTP 401 te ontvangen met behulp van de Key Vault SDK-client, waarbij de Key Vault aan de toepassing de WWW-Authenticate-header toont die de resource bevat en de tenant waar deze naartoe moet gaan en om het token moet vragen. Als alles correct is geconfigureerd, bevat de tweede aanroep van de toepassing Key Vault een geldig token en slaagt deze.

Share via