Códigos de erro da API REST do Azure Key Vault
Os seguintes códigos de erro podem ser retornados por uma operação em um serviço Web do Azure Key Vault.
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 acima 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]
Podemos ver muitas partes importantes nesse token:
- aud (audiência): o recurso do token. Observe que isso é
https://vault.azure.net. Esse token não funcionará para nenhum recurso que não corresponda explicitamente a esse valor, como gráfico. - 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 esse token se torna válido.
- exp (expiração): o número de tiques desde o início da época em que esse token expira.
- appid (ID do aplicativo): o GUID para a ID do aplicativo que faz essa solicitação.
- tid (ID do locatário): o GUID da ID de locatário da entidade de segurança que faz esta 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. Frequentemente, haverá vários objetos no Microsoft Entra ID com o mesmo nome, portanto, é importante escolher o correto. 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