Autenticação, solicitações e respostas

O Azure Key Vault oferece dois tipos de contentores para armazenar e gerir segredos para as suas aplicações cloud:

Aqui estão os sufixos das URLs usadas para acessar cada tipo de objeto:

O Azure Key Vault suporta pedidos e respostas formatados em JSON. Os pedidos para o Azure Key Vault são encaminhados para uma URL válida do Azure Key Vault usando HTTPS com alguns parâmetros URL e corpos de pedido e resposta codificados em JSON.

Este artigo cobre os detalhes do serviço Azure Key Vault. Para informações gerais sobre a utilização de interfaces REST Azure, incluindo autenticação/autorização e como adquirir um token de acesso, consulte Azure REST API Reference.

Estrutura de URL de solicitação

As operações de gerenciamento de chaves usam verbos HTTP, incluindo DELETE, GET, PATCH e PUT. As operações criptográficas em objetos de chave existentes usam HTTP POST.

Para clientes que não suportam verbos HTTP específicos, Azure Key Vault permite usar HTTP POST com o cabeçalho X-HTTP-REQUEST para especificar o verbo pretendido. Ao usar o POST como um substituto (por exemplo, em vez de DELETE), inclua um corpo vazio para solicitações que normalmente não exigem um.

Para trabalhar com objetos no Azure Key Vault, os seguintes são exemplos de URLs:

• Para CRIAR uma chave chamada TESTKEY num Key Vault, utilize o comando - PUT /keys/TESTKEY?api-version=<api-version> HTTP/1.1

• Para importar uma chave chamada IMPORTEDKEY num Key Vault, use - POST /keys/IMPORTEDKEY/import?api-version=<api-version> HTTP/1.1

• Para OBTER um segredo chamado MYSECRET num Cofre de Chaves, usar - GET /secrets/MYSECRET?api-version=<api-version> HTTP/1.1

• Para ASSINAR um digest com uma chave chamada TESTKEY no Key Vault, use - POST /keys/TESTKEY/sign?api-version=<api-version> HTTP/1.1

• A autoridade para uma solicitação para um Key Vault é sempre a seguinte,

  • Para cofres: https://<vault-name>.vault.azure.net/
  • Para HSMs gerenciados: https://{HSM-name}.managedhsm.azure.net/ as chaves são sempre armazenadas sob o caminho /keys, enquanto os segredos são sempre armazenados sob o caminho /secrets.

Versões de API suportadas

O Azure Key Vault Service suporta versionamento de protocolos para garantir compatibilidade com clientes de nível inferior, embora nem todas as funcionalidades estejam disponíveis para esses clientes. Os clientes devem usar o api-version parâmetro de cadeia de caracteres de consulta para especificar a versão do protocolo que eles suportam, pois não há padrão.

As versões do protocolo Azure Key Vault seguem um esquema de numeração de datas usando um {YYYY}. {MM}. {DD} format.

Requisitos do corpo de solicitação

De acordo com a especificação HTTP, as operações GET NÃO devem ter um corpo de solicitação e as operações POST e PUT devem ter um corpo de solicitação. O corpo nas operações DELETE é opcional em HTTP.

A menos que indicado de outra forma na descrição da operação, o tipo de conteúdo do corpo da solicitação deve ser application/json e deve conter um objeto JSON serializado em conformidade com o tipo de conteúdo.

Salvo indicação em contrário na descrição da operação, o cabeçalho da solicitação Accept deve conter o tipo de mídia application/json.

Formato do corpo da resposta

A menos que indicado de outra forma na descrição da operação, o tipo de conteúdo do corpo da resposta das operações bem-sucedidas e com falha é application/json e contém informações detalhadas de erro.

Usando HTTP POST como alternativa

Alguns clientes podem não conseguir usar determinados verbos HTTP, como PATCH ou DELETE. O Azure Key Vault suporta HTTP POST como alternativa para estes clientes, desde que o cliente também inclua o cabeçalho "X-HTTP-METHOD" para especificar o verbo HTTP original. O suporte para HTTP POST é observado para cada uma das APIs definidas neste documento.

Gestão de respostas de erro

O tratamento de erros usa códigos de status HTTP. Os resultados típicos são:

• 2xx – Sucesso: Usado para operação normal. O corpo da resposta contém o resultado esperado

• 3xx – Redireccionamento: O 304 "Não Modificado" poderá ser devolvido para cumprir um GET condicional. Outros códigos 3xx podem ser usados no futuro para indicar DNS e alterações de caminho.

• 4xx – Erro do cliente: Usado para solicitações incorretas, chaves ausentes, erros de sintaxe, parâmetros inválidos, erros de autenticação, etc. O corpo da resposta contém uma explicação detalhada do erro.

• 5xx – Erro do servidor: Usado para erros internos do servidor. O corpo da resposta contém informações de erro resumidas.

  O sistema é projetado para funcionar atrás de um proxy ou firewall. Portanto, um cliente pode receber outros códigos de erro.

  O Azure Key Vault também devolve informação de erro no corpo da resposta quando ocorre um problema. O corpo da resposta é formatado em JSON e assume a forma:

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

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

Requisitos de autenticação

Todos os pedidos ao Azure Key Vault DEVEM ser autenticados. Azure Key Vault suporta tokens de acesso Microsoft Entra que podem ser obtidos usando OAuth2 [RFC6749].

Para mais informações sobre como registar a sua candidatura e autenticar-se para usar Azure Key Vault, consulte Registe a sua candidatura de cliente com Microsoft Entra ID.

Os tokens de acesso devem ser enviados para o serviço usando o cabeçalho HTTP Authorization:

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

Quando um token de acesso não é fornecido, ou quando o serviço não aceita um token, um erro HTTP 401 é retornado ao cliente e inclui o cabeçalho WWW-Authenticate, por exemplo:

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

Os parâmetros no cabeçalho WWW-Authenticate são:

• authorization: O endereço do serviço de autorização OAuth2 que pode ser usado para obter um token de acesso para a solicitação.

• resource: O nome do recurso (https://vault.azure.net) a ser usado na solicitação de autorização.