Autenticação, solicitações e respostas

2025-04-21

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

Tipo de contêiner	Tipos de objeto com suporte	URL base do ponto de extremidade do plano de dados
Cofres	Chaves protegidas por software Chaves protegidas por HSM (com SKU Premium) Certificados Chaves de conta de armazenamento	https://{vault-name}.vault.azure.net
HSM gerenciado	Chaves protegidas por HSM	https://{hsm-name}.managedhsm.azure.net

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

Tipo de objeto	Sufixo da URL
Chaves protegidas por software	/keys
Chaves protegidas por HSM	/keys
Segredos	/secrets
Certificados	/certificados
Chaves de conta de armazenamento	/storageAccounts

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

Este artigo aborda as especificidades do serviço do 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 a 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 POST como um substituto (por exemplo, em vez de DELETE), inclua um corpo vazio para solicitações que normalmente não exigem uma.

Para trabalhar com objetos no Azure Key Vault, veja a seguir urls de exemplo:

Para criar (CREATE) uma chave chamada TESTKEY em um Key Vault use – PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1
Para importar (IMPORT) uma chave chamada IMPORTEDKEY em um Key Vault use – POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1
Para obter (GET) uma chave chamada MYSECRET em um Key Vault use – GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1
Para assinar (SIGN) 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 para um Key Vault sempre é como segue,
- Para cofres: https://{keyvault-name}.vault.azure.net/
- Para HSMs Gerenciados: https://{HSM-name}.managedhsm.azure.net/ as chaves são sempre armazenadas no caminho /keys, enquanto os segredos são sempre armazenados no caminho /secrets.

Versões de API com suporte

O Serviço do 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 dão suporte, pois não há padrão.

As versões de protocolo do Azure Key Vault seguem um esquema de numeração de data no formato {YYYY}.{MM}.{DD}.

Requisitos do corpo da 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 em operações DELETE é opcional no HTTP.

A menos que observado 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.

A menos que indicado de outra forma 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 ser capazes de 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 é indicado para cada uma das API definidas neste documento.

Manipulando respostas de erro

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

2xx – Êxito: usado para a operação normal. O corpo da resposta contém o resultado esperado
3xx – Redirecionamento: o 304 "Não Modificado" pode ser retornado para atender a um GET condicional. Outros códigos 3xx podem ser usados no futuro para indicar alterações de DNS e 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 foi projetado para funcionar por trá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 o formulário:


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

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

Requisitos de autenticação

Todas as solicitações para o Azure Key Vault DEVEM ser autenticadas. O Azure Key Vault dá suporte a 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 a ID do Microsoft Entra.

Os tokens de acesso devem ser enviados ao serviço usando o cabeçalho de Autorização HTTP:

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:

autorização: o endereço do serviço de autorização OAuth2 que pode ser usado para obter um token de acesso para a solicitação.
recurso: o nome do recurso (https://vault.azure.net) a ser usado na solicitação de autorização.

Observação

Clientes SDK do Key Vault para segredos, certificados e chaves na primeira chamada para Key Vault não fornecem um token de acesso para recuperar informações de locatário. Espera-se que receba um HTTP 401 usando o cliente SDK do Key Vault em que o Key Vault mostra ao aplicativo o cabeçalho de WWW-Authenticate que contém o recurso e o locatário onde ele precisa ir e solicitar o token. Se tudo estiver configurado corretamente, a segunda chamada do aplicativo para Key Vault conterá um token válido e terá êxito.