Autenticação, Pedidos e Respostas

Artigo
08/07/2024

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

Tipo de contentor	Tipos de objeto suportados	Ponto de extremidade do plano de dados
Cofres	Chaves protegidas por software Chaves protegidas por HSM (com Premium SKU) Certificados Chaves de contas de armazenamento	https://{nome do cofre}.vault.azure.net
HSM gerenciado	Chaves protegidas por HSM	https://{hsm-name}.managedhsm.azure.net

Aqui estão os sufixos de URL usados para acessar cada tipo de objeto:

Object type	Sufixo do URL
Chaves protegidas por software	/chaves
Chaves protegidas por HSM	/chaves
Segredos	/segredos
Certificados	/certificados
Chaves de contas de armazenamento	/storageaccounts

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 tópico 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.

URL do Pedido

As operações de gerenciamento de chaves usam HTTP DELETE, GET, PATCH, PUT e HTTP POST e as operações criptográficas em objetos de chave existentes usam HTTP POST. Os clientes que não suportam verbos HTTP específicos também podem usar HTTP POST usando o cabeçalho X-HTTP-REQUEST para especificar o verbo pretendido; solicitações que normalmente não exigem um corpo devem incluir um corpo vazio ao usar HTTP POST, por exemplo, ao usar POST em vez de DELETE.

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 em um Cofre de Chaves use - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1
Para ASSINAR um resumo usando uma chave chamada TESTKEY em um Key Vault use - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1
A autoridade para uma solicitaçã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, os segredos são sempre armazenados sob o caminho /secrets.

Versão da API

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 um {YYYY}. {MM}. Formato {DD}.

Corpo do Pedido

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.

Organismo de resposta

Salvo indicação em contrário na descrição da operação, o tipo de conteúdo do corpo de resposta das operações bem-sucedidas e com falha será application/json e conterá informações detalhadas sobre erros.

Usando HTTP POST

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, 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.

Respostas de erro

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

2xx – Sucesso: Usado para operação normal. O corpo da resposta conterá 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 conterá uma explicação detalhada do erro.
5xx – Erro do servidor: Usado para erros internos do servidor. O corpo da resposta conterá 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’."  
    }  
  }  
}

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 um token não é aceito pelo serviço, um erro HTTP 401 será retornado ao cliente e incluirá 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.

Nota

Os clientes SDK do Key Vault para segredos, certificados e chaves na primeira chamada ao Key Vault não proporcionam nenhum token de acesso para recuperar as informações do inquilino. Espera-se que receba um erro HTTP 401 ao utilizar o cliente SDK do Key Vault onde o Key Vault mostra à aplicação o cabeçalho WWW-Authenticate com o recurso e o inquilino para onde precisa de ir e pedir o token. Se tudo estiver configurado corretamente, a segunda chamada da aplicação ao Key Vault conterá um token válido e terá sucesso.

Partilhar via