Autenticación, solicitudes y respuestas

Azure Key Vault proporciona dos tipos de contenedores para almacenar y administrar secretos para las aplicaciones en la nube:

Estos son los sufijos de las direcciones URL que se usan para tener acceso a cada tipo de objeto.

Azure Key Vault admite solicitudes y respuestas con formato JSON. Las solicitudes a Azure Key Vault se dirigen a una dirección URL válida de Azure Key Vault mediante HTTPS con algunos parámetros de dirección URL y cuerpos de solicitud y respuesta codificados en JSON.

En este artículo se tratan aspectos específicos del servicio Azure Key Vault. Para obtener información general sobre el uso de interfaces REST de Azure, incluida la autenticación y autorización y cómo adquirir un token de acceso, consulte Referencia de la API REST de Azure.

Estructura de dirección URL de solicitud

Las operaciones de administración de claves usan verbos HTTP, incluidos DELETE, GET, PATCH y PUT. Las operaciones criptográficas en objetos de clave existentes usan HTTP POST.

En el caso de los clientes que no admiten verbos HTTP específicos, Azure Key Vault permite usar HTTP POST con el X-HTTP-REQUEST encabezado para especificar el verbo previsto. Cuando se usa POST como sustituto (por ejemplo, en lugar de DELETE), incluya un cuerpo vacío para las solicitudes que normalmente no requieren una.

Para trabajar con objetos en Azure Key Vault, estas son direcciones URL de ejemplo:

• Para CREAR una clave denominada TESTKEY en un almacén de claves, use : PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• Para IMPORTAR una clave denominada IMPORTEDKEY en un almacén de claves, use : POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• Para obtener un secreto denominado MYSECRET en un almacén de claves, use : GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• Para FIRMAR un resumen mediante una clave denominada TESTKEY en una bóveda de claves, use: POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• La autoridad para una solicitud a una instancia de Key Vault es siempre la siguiente,

  • Para almacenes: https://{keyvault-name}.vault.azure.net/
  • Para los HSM administrados: https://{HSM-name}.managedhsm.azure.net/ las claves siempre se almacenan en la ruta de acceso /keys, mientras que los secretos siempre se almacenan en la ruta de acceso /secrets.

Versiones de API admitidas

El servicio Azure Key Vault admite el control de versiones de protocolo para proporcionar compatibilidad con clientes de nivel inferior, aunque no todas las funcionalidades están disponibles para esos clientes. Los clientes deben usar el api-version parámetro de cadena de consulta para especificar la versión del protocolo que admiten, ya que no hay ningún valor predeterminado.

Las versiones del protocolo de Azure Key Vault siguen un esquema de numeración de fechas mediante un formato {AAAA}.{MM}.{DD}.

Requisitos del cuerpo de la solicitud

Según la especificación HTTP, las operaciones GET NO deben tener un cuerpo de solicitud y las operaciones POST y PUT deben tener un cuerpo de solicitud. El cuerpo de las operaciones DELETE es opcional en HTTP.

A menos que se indique lo contrario en la descripción de la operación, el tipo de contenido del cuerpo de la solicitud debe ser application/json y debe contener un objeto JSON serializado conforme al tipo de contenido.

A menos que se indique lo contrario en la descripción de la operación, el encabezado de solicitud Accept debe contener el tipo de medio application/json.

Formato del cuerpo de la respuesta

A menos que se indique lo contrario en la descripción de la operación, el tipo de contenido del cuerpo de la respuesta de las operaciones correctas y con errores son application/json y contiene información detallada sobre errores.

Uso de HTTP POST como alternativa

Es posible que algunos clientes no puedan usar determinados verbos HTTP, como PATCH o DELETE. Azure Key Vault admite HTTP POST como alternativa para estos clientes si el cliente también incluye el encabezado "X-HTTP-METHOD" para especificar el verbo HTTP original. La compatibilidad con HTTP POST se indica para cada una de las API definidas en este documento.

Gestión de respuestas de error

El control de errores usa códigos de estado HTTP. Los resultados típicos son:

• 2xx - Correcto: se utiliza para el funcionamiento normal. El cuerpo de la respuesta contiene el resultado esperado.

• 3xx – Redireccionamiento: se puede devolver el 304 "No modificado" para cumplir con un GET condicional. Otros códigos 3xx se pueden usar en el futuro para indicar los cambios de DNS y ruta de acceso.

• 4xx – Error de cliente: se usa para solicitudes incorrectas, claves que faltan, errores de sintaxis, parámetros no válidos, errores de autenticación, etc. El cuerpo de la respuesta contiene una explicación detallada del error.

• 5xx – Error de servidor: se usa para errores internos del servidor. El cuerpo de la respuesta contiene información de error resumida.

  El sistema está diseñado para funcionar detrás de un proxy o firewall. Por lo tanto, un cliente puede recibir otros códigos de error.

  Azure Key Vault también devuelve información de error en el cuerpo de la respuesta cuando se produce un problema. El cuerpo de la respuesta tiene formato JSON y tiene la forma :

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

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

Requisitos de autenticación

Todas las solicitudes a Azure Key Vault DEBEN autenticarse. Azure Key Vault admite tokens de acceso de Microsoft Entra que se pueden obtener mediante OAuth2 [RFC6749].

Para obtener más información sobre el registro de la aplicación y la autenticación para usar Azure Key Vault, consulte Registro de la aplicación cliente con el identificador de Microsoft Entra.

Los tokens de acceso deben enviarse al servicio mediante el encabezado de autorización HTTP:

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

Cuando no se proporciona un token de acceso o cuando el servicio no acepta un token, se devuelve un error HTTP 401 al cliente e incluye el encabezado WWW-Authenticate, por ejemplo:

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

Los parámetros del encabezado WWW-Authenticate son:

• authorization: la dirección del servicio de autorización OAuth2 que se puede usar para obtener un token de acceso para la solicitud.

• resource: el nombre del recurso (https://vault.azure.net) que se va a usar en la solicitud de autorización.