Códigos de erro da API REST do Azure Key Vault

Uma operação em um serviço Web do Azure Key Vault pode retornar os seguintes códigos de erro.

HTTP 401: Pedido Não Autenticado

401 significa que a solicitação não está autenticada para o Cofre da Chave.

Um pedido é autenticado se:

• O cofre de chaves sabe a identidade do chamador; e ainda
• O chamador tem permissão para tentar acessar os recursos do Cofre da Chave.

Existem várias razões pelas quais um pedido pode devolver 401.

Nenhum token de autenticação anexado à solicitação

Aqui está um exemplo de solicitação PUT, definindo o valor de um segredo:

PUT https://putreqexample.vault.azure.net//secrets/DatabaseRotatingPassword?api-version=7.0 HTTP/1.1
x-ms-client-request-id: 03d275a2-52a4-4bed-82c8-6fe15165affb
accept-language: en-US
Authorization: Bearer     eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSIsImtpZCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSJ9.eyJhdWQiOiJodHRwczovL3ZhdWx0LmF6dXJlLm5ldCIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0Ny8iLCJpYXQiOjE1NDg2OTc1MTMsIm5iZiI6MTU0ODY5NzUxMywiZXhwIjoxNTQ4NzAxNDEzLCJhaW8iOiI0MkpnWUhoODVqaVBnZHF5ZlRGZE5TdHY3bGUvQkFBPSIsImFwcGlkIjoiZmFkN2Q1YjMtNjlkNi00YjQ4LTkyNTktOGQxMjEyNGUxY2YxIiwiYXBwaWRhY3IiOiIxIiwiaWRwIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3LyIsIm9pZCI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInN1YiI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInV0aSI6IjItZ3JoUmtlSWs2QmVZLUxuNDJtQUEiLCJ2ZXIiOiIxLjAifQ.fgubiz1MKqTJTXI8dHIV7t9Fle6FdHrkaGYKcBeVRX1WtLVuk1QVxzIFDlZKLXJ7QPNs0KWpeiWQI9IWIRK-8wO38yCqKTfDlfHOiNWGOpkKddlG729KFqakVf2w0GPyGPFCONRDAR5wjQarN9Bt8I8YbHwZQz_M1hztlnv-Lmsk1jBmech9ujD9-lTMBmSfFFbHcqquev119V7sneI-zxBZLf8C0pIDkaXf1t8y6Xr8CUJDMdlWLslCf3pBCNIOy65_TyGvy4Z4AJryTPBarNBPwOkNAtjCfZ4BDc2KqUZM5QN_VK4foP64sVzUL6mSr0Gh7lQJIL5b1qIpJxjxyQ
User-Agent: FxVersion/4.7.3324.0 OSName/Windows OSVersion/6.2.9200.0 Microsoft.Azure.KeyVault.KeyVaultClient/3.0.3.0
Content-Type: application/json; charset=utf-8
Host: putreqexample.vault.azure.net
Content-Length: 31

{
   "value": "m*gBJ7$Zuoz)"
}

O cabeçalho "Autorização" é o token de acesso necessário em cada chamada para o Cofre de Chaves para operações de plano de dados. Se o cabeçalho estiver faltando, a resposta deve ser 401.

O token não tem o recurso correto associado a ele

Ao solicitar um token de acesso do ponto de extremidade OAUTH do Azure, um parâmetro chamado "recurso" é obrigatório. O valor é importante para o provedor de token porque ele define o escopo do token para seu uso pretendido. O recurso para todos os tokens acessarem um Cofre de Chaves é https://vault.keyvault.net (sem barra à direita).

O token expirou

Os tokens são codificados em base64 e os valores podem ser decodificados em sites como http://jwt.calebb.net. Aqui está o token decodificado:

    {
 typ: "JWT",
 alg: "RS256",
 x5t: "nbCwW11w3XkB-xUaXwKRSLjMHGQ",
 kid: "nbCwW11w3XkB-xUaXwKRSLjMHGQ"
}.
{
 aud: "https://vault.azure.net",
 iss: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 iat: 1548697513,
 nbf: 1548697513,
 exp: 1548701413,
 aio: "42JgYHh85jiPgdqyfTFdNStv7le/BAA=",
 appid: "fad7d5b3-69d6-4b48-9259-8d12124e1cf1",
 appidacr: "1",
 idp: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 oid: "3975aeed-7d08-453b-b6f4-445f32698091",
 sub: "3975aeed-7d08-453b-b6f4-445f32698091",
 tid: "72f988bf-86f1-41af-91ab-2d7cd011db47",
 uti: "2-grhRkeIk6BeY-Ln42mAA",
 ver: "1.0"
}.
[signature]

O token contém muitas partes importantes:

• aud (audiência): O recurso do token. Observe que o valor é https://vault.azure.net. O token NÃO funciona para nenhum recurso que não corresponda explicitamente ao valor, como gráfico.
• iat (emitido em): O número de ticks desde o início da época em que o token foi emitido.
• nbf (não antes): O número de ticks desde o início da época em que o token se torna válido.
• exp (expiração): O número de ticks desde o início da época em que o token expira.
• appid (ID do aplicativo): O GUID do ID do aplicativo que faz a solicitação.
• tid (tenant ID): o GUID para o ID do locatário da entidade de segurança que faz a solicitação

É importante que todos os valores sejam devidamente identificados no token para que a solicitação funcione. Se tudo estiver correto, a solicitação não resultará em 401.

Solução de problemas 401

Os 401s devem ser investigados desde o ponto de geração do token, antes que a solicitação seja feita ao cofre de chaves. Geralmente, o código está sendo usado para solicitar o token. Assim que o token é recebido, ele é passado para a solicitação do Cofre da Chave. Se o código estiver sendo executado localmente, você poderá usar o Fiddler para capturar a solicitação/resposta para https://login.microsoftonline.com. Um pedido tem o seguinte aspeto:

POST https://login.microsoftonline.com/<key vault tenant ID>/oauth2/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 192

resource=https%3A%2F%2Fvault.azure.net&client_id=<registered-app-ID>&client_secret=<registered-app-secret>&client_info=1&grant_type=client_credentials

As seguintes informações fornecidas pelo usuário devem estar corretas:

• O ID do locatário do cofre de chaves
• Valor do recurso definido como https%3A%2F%2Fvault.azure.net (URL codificado)
• ID do Cliente
• Segredo do cliente

Certifique-se de que o resto do pedido é quase idêntico.

Se você só puder obter o token de acesso de resposta, poderá decodificá-lo para garantir a ID do locatário, a ID do cliente (ID do aplicativo) e o recurso.

HTTP 403: Permissões Insuficientes

HTTP 403 significa que a solicitação foi autenticada (ele conhece a identidade solicitante), mas a identidade não tem permissão para acessar o recurso solicitado. Existem duas causas:

• Não há política de acesso para a identidade.
• O endereço IP do recurso solicitante não é aprovado nas configurações de firewall do cofre de chaves.

HTTP 403 geralmente ocorre quando o aplicativo do cliente não está usando a ID do cliente que o cliente acha que é. Isso geralmente significa que as políticas de acesso não estão configuradas corretamente para a identidade de chamada real.

Se você receber um erro 403 imediatamente após adicionar uma identidade à política de acesso, poderá manipulá-lo adicionando novas tentativas periódicas.

Solução de problemas 403

Primeiro, ative o registro. Para obter instruções sobre como fazer isso, consulte Registro em log do Cofre da Chave do Azure.

Depois que o registro em log estiver ativado, você poderá determinar se o 403 se deve à política de acesso ou à diretiva de firewall.

Erro devido à política de firewall

"O endereço do cliente (00.00.00.00) não está autorizado e o chamador não é um serviço confiável"

Há uma lista limitada de "Serviços Confiáveis do Azure". Os Sites do Azure não são um Serviço Fidedigno do Azure. Para obter mais informações, consulte a postagem do blog Serviços confiáveis.

Você deve adicionar o endereço IP do Site do Azure ao Cofre da Chave para que ele funcione.

Se devido à política de acesso: localize o ID do objeto para a solicitação e verifique se o ID do objeto corresponde ao objeto ao qual o usuário está tentando atribuir a política de acesso. Muitas vezes, há vários objetos no Microsoft Entra ID, que têm o mesmo nome, portanto, escolher o correto é importante. Ao excluir e readicionar a política de acesso, é possível ver se existem vários objetos com o mesmo nome.

Além disso, a maioria das políticas de acesso não exige o uso do "Aplicativo autorizado", conforme mostrado no portal. Os aplicativos autorizados são usados para cenários de autenticação "em nome de", que são raros.

HTTP 429: Demasiados Pedidos

A limitação ocorre quando o número de pedidos excede o máximo indicado para o período de tempo. Se a limitação ocorrer, a resposta do Key Vault será HTTP 429. Existem máximos indicados para os tipos de pedidos efetuados. Por exemplo: a criação de uma chave HSM de 2048 bits é de 10 solicitações por 10 segundos, mas todas as outras transações HSM têm um limite de 2.000 solicitações/10 segundos. Portanto, é importante entender quais tipos de chamadas estão sendo feitas ao determinar a causa da limitação. Em geral, as solicitações para o Cofre da Chave são limitadas a 4.000 solicitações/10 segundos. As exceções são as Operações de Chave, conforme documentado nos limites de serviço do Cofre de Chaves

Resolução de problemas 429

A limitação da largura de banda de rede é contornada com as seguintes técnicas:

• Reduza o número de pedidos feitos ao Key Vault ao determinar se existem padrões para um recurso pedido e ao tentar colocá-los em cache na aplicação de chamada.

• Quando a limitação do Cofre de Chaves ocorrer, adapte o código de solicitação para usar um backoff exponencial para tentar novamente. O algoritmo é explicado aqui: Como limitar seu aplicativo

• Se não for possível reduzir o número de pedidos com a colocação em cache e se o recuo com limite de tempo não funcionar, considere dividir as chaves em vários Key Vaults. O limite do serviço para uma única subscrição é 5 vezes o limite individual do Key Vault. Se estiver usando mais de cinco Cofres de Chaves, deve-se considerar o uso de várias assinaturas.

Orientações detalhadas, incluindo solicitação para aumentar limites, podem ser encontradas aqui: Key Vault throttling guidance