Authentification, demandes et réponses

Azure Key Vault fournit deux types de conteneurs pour stocker et gérer des secrets pour vos applications cloud :

Voici les suffixes des URL utilisées pour accéder à chaque type d’objet

Azure Key Vault prend en charge les demandes et réponses au format JSON. Les demandes adressées à Azure Key Vault sont dirigées vers une URL Azure Key Vault valide à l’aide de HTTPS avec certains paramètres d’URL et des corps de requête et de réponse encodés JSON.

Cet article décrit les spécificités du service Azure Key Vault. Pour obtenir des informations générales sur l’utilisation d’interfaces REST Azure, notamment l’authentification/autorisation et la façon d’acquérir un jeton d’accès, consultez informations de référence sur l’API REST Azure.

Structure d’URL de requête

Les opérations de gestion des clés utilisent des verbes HTTP, notamment DELETE, GET, PATCH et PUT. Les opérations de chiffrement sur les objets clés existants utilisent HTTP POST.

Pour les clients qui ne peuvent pas prendre en charge des verbes HTTP spécifiques, Azure Key Vault autorise l’utilisation de HTTP POST avec l’en-tête X-HTTP-REQUEST pour spécifier le verbe prévu. Lorsque vous utilisez POST comme substitut (par exemple, au lieu de DELETE), incluez un corps vide pour les requêtes qui n’en nécessitent normalement pas.

Pour utiliser des objets dans Azure Key Vault, voici des exemples d’URL :

• Pour CRÉER une clé appelée TESTKEY dans un coffre de clés, utilisez : PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• Pour IMPORTER une clé appelée IMPORTEDKEY dans un coffre de clés, utilisez - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• Pour OBTENIR un secret appelé MYSECRET dans un coffre de clés, utilisez - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• Pour SIGNER un code de hachage utilisant une clé nommée TESTKEY dans Key Vault, utilisez : POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• L’autorité pour une demande adressée à un Key Vault est toujours la suivante :

  • Pour les coffres : https://{keyvault-name}.vault.azure.net/
  • Pour les modules HSM managés : https://{HSM-name}.managedhsm.azure.net/ les clés sont toujours stockées sous le chemin /keys, tandis que les secrets sont toujours stockés sous le chemin /secrets.

Versions d'API prises en charge

Le service Azure Key Vault prend en charge le contrôle de version de protocole pour assurer la compatibilité avec les clients de bas niveau, bien que toutes les fonctionnalités ne soient pas disponibles pour ces clients. Les clients doivent utiliser le api-version paramètre de chaîne de requête pour spécifier la version du protocole qu’ils prennent en charge, car il n’existe pas de valeur par défaut.

Les versions du protocole Azure Key Vault suivent un schéma de numérotation de dates utilisant le format {AAAA}.{MM}.{JJ}.

Conditions requises pour le corps de la demande

Conformément à la spécification HTTP, les opérations GET ne doivent pas avoir de corps de requête, et les opérations POST et PUT doivent avoir un corps de requête. Le corps des opérations DELETE est facultatif dans HTTP.

Sauf indication contraire dans la description de l’opération, le type de contenu du corps de la requête doit être application/json et doit contenir un objet JSON sérialisé conforme au type de contenu.

Sauf indication contraire dans la description de l’opération, l’en-tête Accepter la demande doit contenir le type de média application/json.

Format du corps de la réponse

Sauf indication contraire dans la description de l’opération, le type de contenu du corps de réponse des opérations réussies et ayant échoué est application/json et contient des informations d’erreur détaillées.

Utilisation de HTTP POST comme alternative

Certains clients peuvent ne pas être en mesure d’utiliser certains verbes HTTP, tels que PATCH ou DELETE. Azure Key Vault prend en charge HTTP POST comme alternative pour ces clients si le client inclut également l’en-tête « X-HTTP-METHOD » pour spécifier le verbe HTTP d'origine. La prise en charge de HTTP POST est notée pour chacune des API définies dans ce document.

Gestion des réponses aux erreurs

La gestion des erreurs utilise des codes d’état HTTP. Les résultats classiques sont les suivants :

• 2xx – Réussite : utilisé pour l’opération normale. Le corps de la réponse contient le résultat attendu

• 3xx – Redirection : le 304 « Non modifié » peut être retourné pour remplir un GET conditionnel. D’autres codes 3xx peuvent être utilisés ultérieurement pour indiquer les modifications dns et de chemin d’accès.

• 4xx – Erreur du client : utilisé pour les requêtes incorrectes, clés manquantes, erreurs de syntaxe, paramètres non valides, erreurs d’authentification, etc. Le corps de la réponse contient une explication détaillée des erreurs.

• 5xx – Erreur du serveur : utilisée pour les erreurs de serveur interne. Le corps de la réponse contient des informations d’erreur résumées.

  Le système est conçu pour fonctionner derrière un proxy ou un pare-feu. Par conséquent, un client peut recevoir d’autres codes d’erreur.

  Azure Key Vault retourne également des informations d’erreur dans le corps de la réponse lorsqu’un problème se produit. Le corps de la réponse est au format JSON et prend la forme suivante :

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

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

Exigences relatives à l’authentification

Toutes les demandes adressées à Azure Key Vault DOIVENT être authentifiées. Azure Key Vault prend en charge les jetons d’accès Microsoft Entra qui peuvent être obtenus à l’aide d’OAuth2 [RFC6749].

Pour plus d’informations sur l’inscription de votre application et l’authentification pour utiliser Azure Key Vault, consultez Inscrire votre application cliente avec l’ID Microsoft Entra.

Les jetons d’accès doivent être envoyés au service à l’aide de l’en-tête d’autorisation HTTP :

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

Lorsqu’un jeton d’accès n’est pas fourni ou que le service n’accepte pas de jeton, une erreur HTTP 401 est retournée au client et inclut l’en-tête WWW-Authenticate, par exemple :

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

Les paramètres de l’en-tête WWW-Authenticate sont les suivants :

• autorisation : adresse du service d’autorisation OAuth2 qui peut être utilisée pour obtenir un jeton d’accès pour la demande.

• ressource : nom de la ressource (https://vault.azure.net) à utiliser dans la demande d’autorisation.