Autenticação, Pedidos e RespostasAuthentication, requests and responses

O Azure Key Vault fornece dois tipos de recipientes para armazenar e gerir segredos para as suas aplicações em nuvem:Azure Key Vault provides two types of containers to store and manage secrets for your cloud applications:

Tipo de recipienteContainer type Tipos de objetos suportadosSupported object types Ponto final do plano de dadosData-plane endpoint
CofresVaults
  • Chaves protegidas por softwareSoftware-protected keys
  • Chaves protegidas pelo HSM (com SKU Premium)HSM-protected keys (with Premium SKU)
  • CertificadosCertificates
  • Chaves de contas de armazenamentoStorage account keys
https://{vault-name}.vault.azure.nethttps://{vault-name}.vault.azure.net
HSM geridoManaged HSM
  • Chaves protegidas por HSMHSM-protected keys
https://{hsm-name}.managedhsm.azure.nethttps://{hsm-name}.managedhsm.azure.net

Aqui estão os sufixos URL usados para aceder a cada tipo de objetoHere are the URL suffixes used to access each type of object

Tipo de ObjetoObject type Sufixo do URLURL suffix
Chaves protegidas por softwareSoftware-protected keys /chaves/keys
Chaves protegidas por HSMHSM-protected keys /chaves/keys
SegredosSecrets /segredos/secrets
CertificadosCertificates /certificados/certificates
Chaves de contas de armazenamentoStorage account keys /contas de armazenamento/storageaccounts

O Azure Key Vault suporta pedidos e respostas formatados json.Azure Key Vault supports JSON formatted requests and responses. Os pedidos para o Cofre da Chave Azure são direcionados para um URL de cofre de chave Azure válido usando HTTPS com alguns parâmetros URL e json codificado pedido e corpos de resposta.Requests to the Azure Key Vault are directed to a valid Azure Key Vault URL using HTTPS with some URL parameters and JSON encoded request and response bodies.

Este tópico abrange especificidades para o serviço Azure Key Vault.This topic covers specifics for the Azure Key Vault service. Para obter informações gerais sobre a utilização de interfaces Azure REST, incluindo autenticação/autorização e como adquirir um token de acesso, consulte referência API API Azure REST.For general information on using Azure REST interfaces, including authentication/authorization and how to acquire an access token, see Azure REST API Reference.

URL do PedidoRequest URL

As principais operações de gestão utilizam http DELETE, GET, PATCH, PUT e HTTP POST e operações criptográficas contra os objectos-chave existentes usam HTTP POST.Key management operations use HTTP DELETE, GET, PATCH, PUT and HTTP POST and cryptographic operations against existing key objects use HTTP POST. Os clientes que não possam suportar verbos HTTP específicos também podem utilizar o http post utilizando o cabeçalho X-HTTP-REQUEST para especificar o verbo pretendido; pedidos que normalmente não requerem um corpo devem incluir um corpo vazio quando se utiliza HTTP POST, por exemplo, quando se utiliza o POST em vez de DELETE.Clients that cannot support specific HTTP verbs may also use HTTP POST using the X-HTTP-REQUEST header to specify the intended verb; requests that do not normally require a body should include an empty body when using HTTP POST, for example when using POST instead of DELETE.

Para trabalhar com objetos no Cofre da Chave Azure, os seguintes são URLs de exemplo:To work with objects in the Azure Key Vault, the following are example URLs:

  • Para criar uma chave chamada TESTKEY numa utilização do Cofre de Chaves - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1To CREATE a key called TESTKEY in a Key Vault use - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • Importar uma chave chamada IMPORTEDKEY para uma utilização do Cofre de Chaves - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1To IMPORT a key called IMPORTEDKEY into a Key Vault use - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • Para obter um segredo chamado MYSECRET em um uso de Cofre chave - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1To GET a secret called MYSECRET in a Key Vault use - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • Para assinar uma digestão usando uma chave chamada TESTKEY numa utilização do Cofre de Chaves - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1To SIGN a digest using a key called TESTKEY in a Key Vault use - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

  • A autoridade para um pedido a um Cofre chave é sempre a seguinte,The authority for a request to a Key Vault is always as follows,

    • Para cofres: https://{keyvault-name}.vault.azure.net/For vaults: https://{keyvault-name}.vault.azure.net/
    • Para HSMs geridos: https://{HSM-name}.managedhsm.azure.net/For Managed HSMs: https://{HSM-name}.managedhsm.azure.net/

    As chaves são sempre armazenadas sob o caminho /chaves, os segredos são sempre armazenados sob o caminho /segredos.Keys are always stored under the /keys path, Secrets are always stored under the /secrets path.

Versão da APIAPI Version

O Azure Key Vault Service suporta a versão protocolar para fornecer compatibilidade com clientes de nível inferior, embora nem todas as capacidades estejam disponíveis para esses clientes.The Azure Key Vault Service supports protocol versioning to provide compatibility with down-level clients, although not all capabilities will be available to those clients. Os clientes devem utilizar o api-version parâmetro de cadeia de consulta para especificar a versão do protocolo que suportam, uma vez que não existe incumprimento.Clients must use the api-version query string parameter to specify the version of the protocol that they support as there is no default.

As versões do protocolo Azure Key Vault seguem um esquema de numeração de data usando um {YYYY}. {MM}. {DD} formato.Azure Key Vault protocol versions follow a date numbering scheme using a {YYYY}.{MM}.{DD} format.

Corpo do PedidoRequest Body

De acordo com a especificação HTTP, as operações GET NÃO devem ter um órgão de pedido, e as operações POST e PUT devem ter um órgão de pedido.As per the HTTP specification, GET operations must NOT have a request body, and POST and PUT operations must have a request body. O corpo em operações de DELETE é opcional em HTTP.The body in DELETE operations is optional in HTTP.

Salvo indicação em contrário na descrição da operação, o tipo de conteúdo do corpo de pedido deve ser aplicação/json e deve conter um objeto JSON serializado conforme com o tipo de conteúdo.Unless otherwise noted in operation description, the request body content type must be application/json and must contain a serialized JSON object conformant to content type.

Salvo indicação em contrário na descrição do funcionamento, o cabeçalho de pedido aceitar deve conter o tipo de mídia de aplicação/json.Unless otherwise noted in operation description, the Accept request header must contain the application/json media type.

Corpo de RespostaResponse Body

Salvo indicação em contrário na descrição da operação, o tipo de conteúdo do corpo de resposta de operações bem sucedidas e falhadas será aplicação/json e contém informações detalhadas de erro.Unless otherwise noted in operation description, the response body content type of both successful and failed operations will be application/json and contains detailed error information.

Utilização DE HTTP POSTUsing HTTP POST

Alguns clientes podem não ser capazes de utilizar certos verbos HTTP, tais como PATCH ou DELETE.Some clients may not be able to use certain HTTP verbs, such as PATCH or DELETE. A Azure Key Vault suporta http POST como uma alternativa para estes clientes, desde que o cliente também inclua o cabeçalho "X-HTTP-METHOD" para especificar o verbo HTTP original.Azure Key Vault supports HTTP POST as an alternative for these clients provided that the client also includes the “X-HTTP-METHOD” header to specific the original HTTP verb. O suporte para HTTP POST é anotado para cada uma das API definidas neste documento.Support for HTTP POST is noted for each of the API defined in this document.

Respostas de ErroError Responses

O manuseamento de erros utilizará códigos de estado HTTP.Error handling will use HTTP status codes. Os resultados típicos são:Typical results are:

  • 2xx – Sucesso: Utilizado para o funcionamento normal.2xx – Success: Used for normal operation. O corpo de resposta conterá o resultado esperadoThe response body will contain the expected result

  • 3xx – Reorientação: O 304 "Não Modificado" pode ser devolvido para cumprir um GET condicional.3xx – Redirection: The 304 "Not Modified" may be returned to fulfill a conditional GET. Outros códigos 3xx podem ser usados no futuro para indicar DNS e alterações de caminhos.Other 3xx codes may be used in the future to indicate DNS and path changes.

  • 4xx – Erro do Cliente: Utilizado para pedidos insípares, chaves em falta, erros de sintaxe, parâmetros inválidos, erros de autenticação, etc. O corpo de resposta conterá uma explicação detalhada de erro.4xx – Client Error: Used for bad requests, missing keys, syntax errors, invalid parameters, authentication errors, etc. The response body will contain detailed error explanation.

  • 5xx – Erro do servidor: Utilizado para erros internos do servidor.5xx – Server Error: Used for internal server errors. O corpo de resposta conterá informações de erro sumárias.The response body will contain summarized error information.

    O sistema foi concebido para funcionar atrás de um representante ou firewall.The system is designed to work behind a proxy or firewall. Portanto, um cliente pode receber outros códigos de erro.Therefore, a client might receive other error codes.

    O Azure Key Vault também devolve informações de erro no corpo de resposta quando ocorre um problema.Azure Key Vault also returns error information in the response body when a problem occurs. O corpo de resposta é formatado por JSON e assume o formulário:The response body is JSON formatted and takes the form:


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

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

AutenticaçãoAuthentication

Todos os pedidos para a Azure Key Vault DEVEM ser autenticados.All requests to Azure Key Vault MUST be authenticated. O Azure Key Vault suporta fichas de acesso do Azure Ative Directory que podem ser obtidas usando o OAuth2 [RFC6749].Azure Key Vault supports Azure Active Directory access tokens that may be obtained using OAuth2 [RFC6749].

Para obter mais informações sobre o registo da sua aplicação e autenticação para utilizar o Cofre da Chave Azure, consulte Registar a sua aplicação de cliente com Azure AD.For more information on registering your application and authenticating to use Azure Key Vault, see Register your client application with Azure AD.

Os tokens de acesso devem ser enviados para o serviço utilizando o cabeçalho de autorização HTTP:Access tokens must be sent to the service using the HTTP Authorization header:

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 é aceite pelo serviço, um erro HTTP 401 será devolvido ao cliente e incluirá o cabeçalho WWW-Authenticate, por exemplo:When an access token is not supplied, or when a token is not accepted by the service, an HTTP 401 error will be returned to the client and will include the WWW-Authenticate header, for example:

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

Os parâmetros no cabeçalho WWW-Authenticate são:The parameters on the WWW-Authenticate header are:

  • autorização: O endereço do serviço de autorização OAuth2 que pode ser utilizado para obter um sinal de acesso para o pedido.authorization: The address of the OAuth2 authorization service that may be used to obtain an access token for the request.

  • recurso: O nome do recurso https://vault.azure.net () a utilizar no pedido de autorização.resource: The name of the resource (https://vault.azure.net) to use in the authorization request.

Nota

Os clientes Key Vault SDK para segredos, certificados e chaves na primeira chamada para Key Vault não fornecem um sinal de acesso para recuperar informações do inquilino.Key Vault SDK clients for secrets, certificates, and keys in the first call to Key Vault do not provide an access token to retrieve tenant information. Espera-se que receba um HTTP 401 usando o cliente Key Vault SDK onde o Key Vault mostra à aplicação o cabeçalho WWW-Authenticate contendo o recurso e o inquilino onde precisa de ir e pedir o token.It’s expected to receive an HTTP 401 using Key Vault SDK client where the Key Vault shows to the application the WWW-Authenticate header containing the resource and the tenant where it needs to go and ask for the token. Se tudo estiver configurado corretamente, a segunda chamada da aplicação para Key Vault conterá um token válido e terá sucesso.If everything is configured correctly, the second call from the application to Key Vault will contain a valid token and will succeed.