Autenticação, solicitações e respostas

O Azure Key Vault fornece dois tipos de contêineres para armazenar e gerenciar segredos para seus aplicativos na nuvem:

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

O Azure Key Vault dá suporte a solicitações e respostas formatadas em JSON. As solicitações para o Cofre da Chave do Azure são direcionadas para uma URL válida do Cofre da Chave do Azure usando HTTPS com alguns parâmetros de URL e corpos de solicitação e resposta codificados em JSON.

Este artigo aborda detalhes específicos para o serviço Azure Key Vault. Para obter informações gerais sobre como usar interfaces REST do Azure, incluindo autenticação/autorização e como adquirir um token de acesso, consulte Referência da API REST do Azure.

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 podem dar suporte a verbos HTTP específicos, o Azure Key Vault permite usar HTTP POST com o X-HTTP-REQUEST cabeçalho 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 Cofre da Chave do Azure, seguem-se exemplos de URLs:

• Para CRIAR uma chave chamada TESTKEY em um Cofre de Chaves, use - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• Para IMPORTAR uma chave chamada IMPORTEDKEY para um Cofre de Chaves, use - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• Para OBTER um segredo chamado MYSECRET num Key Vault, use - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• Para assinar um resumo criptográfico usando uma chave chamada TESTKEY num Key Vault, use - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• A autoridade para uma requisição a um Cofre de Chaves é sempre a seguinte:

  • Para cofres: https://{keyvault-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 Serviço Azure Key Vault dá suporte ao controle de versão de protocolo para fornecer compatibilidade com clientes de nível inferior, embora nem todos os recursos 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 do Azure Key Vault seguem um esquema de numeração de data usando o formato {YYYY}.{MM}.{DD}.

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 dá suporte a HTTP POST como uma alternativa para esses clientes se o cliente também incluir 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 retorna informações 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

Todas as solicitações ao Azure Key Vault DEVEM ser autenticadas. O Azure Key Vault suporta tokens de acesso do Microsoft Entra que podem ser obtidos usando OAuth2 [RFC6749].

Para obter mais informações sobre como registrar seu aplicativo e autenticar para usar o Azure Key Vault, consulte Registrar seu aplicativo cliente com o 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.