Authentifizierung, Anforderungen und Antworten

Azure Key Vault bietet zwei Arten von Containern zum Speichern und Verwalten von geheimen Schlüsseln für Ihre Cloudanwendungen:

Hier sind die Suffixe der URLs, die für den Zugriff auf jeden Objekttyp verwendet werden.

Azure Key Vault unterstützt JSON-formatierte Anforderungen und Antworten. Anforderungen an den Azure Key Vault werden mithilfe von HTTPS mit einigen URL-Parametern und JSON-codierten Anforderungs- und Antworttexten an eine gültige Azure Key Vault-URL weitergeleitet.

In diesem Artikel werden Einzelheiten für den Azure Key Vault-Dienst behandelt. Allgemeine Informationen zur Verwendung von Azure REST-Schnittstellen, einschließlich Authentifizierung/Autorisierung und zum Abrufen eines Zugriffstokens, finden Sie in der Azure REST-API-Referenz.

Anforderungs-URL-Struktur

Schlüsselverwaltungsvorgänge verwenden HTTP-Verben wie DELETE, GET, PATCH und PUT. Kryptografische Vorgänge für vorhandene Schlüsselobjekte verwenden HTTP POST.

Für Clients, die bestimmte HTTP-Verben nicht unterstützen können, ermöglicht Azure Key Vault die Verwendung von HTTP POST mit dem X-HTTP-REQUEST Header, um das beabsichtigte Verb anzugeben. Fügen Sie bei Verwendung von POST als Ersatz (z. B. anstelle von DELETE) einen leeren Text für Anforderungen ein, für die normalerweise keins erforderlich ist.

Zum Arbeiten mit Objekten im Azure Key Vault sind die folgenden Beispiel-URLs aufgeführt:

• Um einen Schlüssel namens TESTKEY in einem Key Vault zu erstellen, verwenden Sie PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• Um einen Schlüssel namens IMPORTEDKEY in eine Key Vault zu importieren, verwenden Sie - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• Um ein Geheimnis namens MYSECRET in einem Key Vault abzurufen, verwenden Sie – GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• Um einen Digest mithilfe eines Schlüssels namens TESTKEY in einem Key Vault zu signieren, verwenden Sie - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• Die autoritative Stelle für eine Anforderung an eine Key Vault-Instanz lautet immer wie folgt:

  • Für Tresore: https://{keyvault-name}.vault.azure.net/
  • Für verwaltete HSMs: https://{HSM-name}.managedhsm.azure.net/ Schlüssel werden immer unter dem Pfad "/keys" gespeichert, während Geheime Schlüssel immer unter dem Pfad "/secrets" gespeichert werden.

Unterstützte API-Versionen

Der Azure Key Vault Service unterstützt die Protokollversionsverwaltung, um Kompatibilität mit Clients auf down-level-Ebene bereitzustellen, obwohl nicht alle Funktionen für diese Clients verfügbar sind. Clients müssen den api-version Abfragezeichenfolgenparameter verwenden, um die Version des Protokolls anzugeben, das sie unterstützen, da keine Standardeinstellung vorhanden ist.

Azure Key Vault-Protokollversionen folgen einem Datumsnummernschema mit einem {YYYY}. {MM}. {DD}-Format.

Anforderungstextanforderungen

Gemäß der HTTP-Spezifikation dürfen GET-Vorgänge KEINEN Anforderungstext aufweisen, und POST- und PUT-Vorgänge müssen über einen Anforderungstext verfügen. Der Text in DELETE-Vorgängen ist in HTTP optional.

Sofern in der Vorgangsbeschreibung nicht anders angegeben, muss der Anforderungstextinhaltstyp "application/json" sein und ein serialisiertes JSON-Objekt enthalten, das dem Inhaltstyp entspricht.

Sofern in der Vorgangsbeschreibung nicht anders angegeben, muss der Accept-Anforderungsheader den Medientyp "application/json" enthalten.

Antworttextformat

Sofern in der Vorgangsbeschreibung nicht anders angegeben, sind der Inhaltstyp des Antworttexts von erfolgreichen und fehlgeschlagenen Vorgängen "application/json" und enthält detaillierte Fehlerinformationen.

Verwenden von HTTP POST als Alternative

Einige Clients können möglicherweise bestimmte HTTP-Verben nicht verwenden, z. B. PATCH oder DELETE. Azure Key Vault unterstützt HTTP POST als Alternative für diese Clients, wenn der Client auch den Header "X-HTTP-METHOD" um das ursprüngliche HTTP-Verb anzugeben enthält. Die Unterstützung für HTTP POST wird für jede in diesem Dokument definierte API angegeben.

Umgang mit Fehlerantworten

Bei der Fehlerbehandlung werden HTTP-Statuscodes verwendet. Typische Ergebnisse sind:

• 2xx – Erfolg: Wird für den normalen Betrieb verwendet. Der Antworttext enthält das erwartete Ergebnis.

• 3xx – Umleitung: Der Statuscode 304 "Nicht geändert" kann ausgegeben werden, um eine bedingte GET-Anforderung zu erfüllen. Andere 3xx-Codes können in Zukunft verwendet werden, um DNS- und Pfadänderungen anzugeben.

• 4xx – Clientfehler: Wird für fehlerhafte Anforderungen, fehlende Schlüssel, Syntaxfehler, ungültige Parameter, Authentifizierungsfehler usw. verwendet. Der Antworttext enthält eine ausführliche Fehlererklärung.

• 5xx – Serverfehler: Wird für interne Serverfehler verwendet. Der Antworttext enthält zusammengefasste Fehlerinformationen.

  Das System ist für die Arbeit hinter einem Proxy oder einer Firewall konzipiert. Daher erhält ein Client möglicherweise andere Fehlercodes.

  Azure Key Vault gibt auch Fehlerinformationen im Antworttext zurück, wenn ein Problem auftritt. Der Antworttext ist JSON formatiert und hat die Form:

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

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

Authentifizierungsanforderungen

Alle Anforderungen an Azure Key Vault MÜSSEN authentifiziert werden. Azure Key Vault unterstützt Microsoft Entra-Zugriffstoken, die mit OAuth2 [RFC6749] abgerufen werden können.

Weitere Informationen zum Registrieren Ihrer Anwendung und Authentifizierung für die Verwendung von Azure Key Vault finden Sie unter Registrieren Ihrer Clientanwendung mit Microsoft Entra ID.

Zugriffstoken müssen mithilfe des HTTP-Autorisierungsheaders an den Dienst gesendet werden:

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

Wenn kein Zugriffstoken bereitgestellt wird oder der Dienst kein Token akzeptiert, wird ein HTTP 401-Fehler an den Client zurückgegeben und enthält beispielsweise den WWW-Authenticate-Header:

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

Die Parameter für die kopfzeile WWW-Authenticate sind:

• Autorisierung: Die Adresse des OAuth2-Autorisierungsdiensts, der zum Abrufen eines Zugriffstokens für die Anforderung verwendet werden kann.

• resource: Der Name der Ressource (https://vault.azure.net), die in der Autorisierungsanfrage verwendet werden soll.