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: Solicitação não autenticada

401 significa que a solicitação não está autenticada para Key Vault.

Uma solicitação será autenticada se:

• O cofre de chaves conhece a identidade do chamador; e
• O chamador tem permissão para tentar acessar recursos de Key Vault.

Há vários motivos pelos quais uma solicitação pode retornar um 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 com cada chamada para o Key Vault para operações de plano de dados. Se o cabeçalho estiver ausente, a resposta deverá 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 faz o escopo do token para seu uso pretendido. O recurso para todos os tokens acessarem um Key Vault é https://vault.keyvault.net (sem nenhuma barra à direita).

O token está expirado

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 grafo.
• iat (emitido em): o número de tiques desde o início da época em que o token foi emitido.
• nbf (não antes): o número de tiques desde o início da época em que o token se torna válido.
• exp (expiração): o número de tiques desde o início da época em que o token expira.
• appid (ID do aplicativo): o GUID para a ID do aplicativo que está fazendo a solicitação.
• tid (ID do locatário): o GUID para a ID do locatário da entidade de segurança que está fazendo a solicitação

É importante que todos os valores sejam corretamente 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

401s deve ser investigado a partir do ponto de geração de token, antes que a solicitação seja feita ao cofre de chaves. Geralmente, o código está sendo usado para solicitar o token. Depois que o token é recebido, ele é passado para a solicitação de Key Vault. Se o código estiver sendo executado localmente, você poderá usar o Fiddler para capturar a solicitação/resposta para https://login.microsoftonline.com. A solicitação se parece com:

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:

• A ID do locatário do cofre de chaves
• O valor do recurso definido como https%3A%2F%2Fvault.azure.net (codificação de URL)
• ID do cliente
• Segredo do cliente

Certifique-se de que o restante da solicitação é 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

O HTTP 403 significa que a solicitação foi autenticada (ela conhece a identidade solicitada), mas a identidade não tem permissão para acessar o recurso solicitado. Há duas causas:

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

O HTTP 403 geralmente ocorre quando o aplicativo do cliente não está usando a ID do cliente que o cliente acha que está. 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á lidar com isso adicionando uma nova tentativa periódica.

Solução de problemas 403

Primeiro, ative o registro em log. Para obter instruções de como fazer isso, consulte Registrar em log do Azure Key Vault.

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

Erro devido à política de firewall

"O endereço do cliente (00.00.00.00) não é 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 Confiável do Azure. Para obter mais informações, consulte a postagem no blog Serviços confiáveis.

Você deve adicionar o endereço de IP do site do Azure ao Key Vault para que ele funcione.

Se devido à política de acesso: localize a ID do objeto para a solicitação e verifique se a 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 na ID do Microsoft Entra, que têm o mesmo nome, portanto, escolher o correto é importante. Ao excluir e adicionar novamente 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: Número Excessivo de Solicitações

A limitação ocorre quando o número de solicitações excede o máximo declarado para o período. Se a limitação ocorrer, a resposta do Key Vault será HTTP 429. Há máximos declarados para tipos de solicitações feitas. 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 do HSM têm um limite de solicitação 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 Key Vault são limitadas a 4.000 solicitações/10 segundos. As exceções são Operações Importantes, conforme documentado em Limites do serviço Key Vault

Solução de problemas 429

A limitação é contornada usando estas técnicas:

• Reduzir o número de solicitações feitas ao Key Vault determinando se há padrões para um recurso solicitado e tentando armazená-los em cache no aplicativo de chamada.

• Quando ocorrer limitação do Key Vault, adapte o código solicitante para usar uma retirada exponencial para tentar novamente. O algoritmo é explicado aqui: Como restringir seu aplicativo

• Se o número de solicitações não puder ser reduzido por cache e a retirada em tempo hábil não funcionar, considere dividir as chaves em vários cofres de chaves. O limite de serviço para uma única assinatura é cinco vezes o limite individual do Key Vault. Se estiver usando mais de cinco Key Vaults, considere o uso de várias assinaturas.

Diretrizes detalhadas, incluindo solicitação para aumentar os limites, podem ser encontradas aqui: Diretrizes de limitação do Key Vault