Toda equipe de API atinge o mesmo obstáculo. Os endpoints funcionam isoladamente, então alguém liga o OAuth 2.0 e metade da suíte de testes começa a retornar 401s. De repente, você está gerenciando servidores de autorização, tokens de acesso de curta duração e escopos, e copiar tokens manualmente de uma resposta curl para um campo de cabeçalho se torna cansativo na terceira execução.
A solução não é pular a autenticação em seus testes. É tornar o tratamento de tokens parte da configuração de teste para que deixe de ser um trabalho manual. Este guia aborda os dois fluxos que você encontrará em quase todos os planos de teste: o fluxo de código de autorização OAuth (com PKCE) para APIs que agem em nome de um usuário, e o fluxo de credenciais de cliente para chamadas máquina a máquina. Se você quiser o mapa completo das concessões primeiro, nossa visão geral dos fluxos OAuth 2.0 explica todos eles.
Em seguida, passamos à prática: configurando a autenticação OAuth 2.0 no Apidog, buscando um token uma vez e reutilizando-o em várias requisições, permitindo que tokens expirados se renovem sozinhos, herdando a autenticação no nível da pasta e testando os caminhos de falha que sua revisão de segurança irá pedir.
Os dois fluxos que importam para o teste de API
OAuth 2.0 define vários tipos de concessão, mas para o teste diário de API, você passará a maior parte do seu tempo com dois deles. Escolha com base em uma pergunta: a API age em nome de um usuário ou em nome de um serviço?
Fluxo de código de autorização, com PKCE
O fluxo de código de autorização é a maneira padrão de obter um token vinculado a um usuário. O cliente envia o usuário para o servidor de autorização, o usuário faz login e consente, o servidor redireciona de volta com um código de uso único, e o cliente troca o código por um token de acesso no endpoint de token. A RFC 6749 define toda a sequência na seção 4.1.
PKCE (Proof Key for Code Exchange, RFC 7636) fortalece a troca. O cliente gera um verificador aleatório, envia um desafio em hash com a requisição de autorização e, em seguida, prova que possui o verificador original ao resgatar o código. Um atacante que intercepta o código não pode usá-lo. O PKCE começou como uma correção para aplicativos móveis, mas a orientação atual do oauth.net o recomenda para toda troca de código de autorização, incluindo clientes confidenciais.
Teste com este fluxo sempre que o comportamento do endpoint depender de quem é o usuário: GET /orders retornando apenas os pedidos do chamador, endpoints administrativos restritos por função, limites de taxa por usuário.
Fluxo de credenciais de cliente
A concessão de credenciais de cliente OAuth 2.0 ignora o usuário completamente. O cliente se autentica com seu próprio ID e segredo e recebe um token representando o próprio aplicativo. Uma requisição POST para o endpoint de token, sem navegador, sem redirecionamento:
curl -X POST https://auth.example.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=orders_service \
-d client_secret=s3cr3t_value \
-d scope="orders:read orders:write"
Este é o fluxo para APIs máquina a máquina: microsserviços internos, cron jobs, pipelines de CI chamando uma API de implantação. É também o motor dos testes automatizados, porque não precisa de intervenção humana. Se seu ambiente de teste permite provisionar um cliente de teste, use credenciais de cliente para tudo, exceto nos casos em que a identidade do usuário é o que está sendo testado.
Configurando a autenticação OAuth 2.0 no Apidog
O Apidog trata o OAuth 2.0 como um tipo de autenticação de primeira classe. Você o configura uma vez, na aba Auth de uma requisição ou pasta, e a plataforma se encarrega de buscar, anexar e renovar tokens. Os tipos de concessão suportados incluem Código de Autorização, Código de Autorização (Com PKCE), Credenciais de Cliente, Credenciais de Senha e Implícito.
Aqui está a configuração para os dois fluxos acima, usando uma API de gerenciamento de pedidos fictícia.
Configuração de credenciais de cliente
Abra a requisição (ou melhor, a pasta; mais sobre isso abaixo), mude o tipo de autenticação para OAuth 2.0 e escolha Credenciais de Cliente como o tipo de concessão. Preencha:
- URL do Token de Acesso:
https://auth.example.com/oauth/token - ID do Cliente:
orders_service - Segredo do Cliente: seu segredo provisionado
- Escopo:
orders:read orders:write(definido nas opções avançadas)
O Apidog oferece duas maneiras de entregar as credenciais: como um cabeçalho de autenticação Básica ou no corpo da requisição. Corresponda ao que seu servidor de autorização espera; Auth0 e Okta aceitam ambos, mas alguns servidores internos só analisam o corpo.
Clique em Obter Token. O Apidog chama o endpoint de token, armazena o resultado e mostra o token junto com seu período de validade. A partir daí, cada envio o anexa ao cabeçalho Authorization com o prefixo Bearer. Sem copiar e colar, sem uso de variável {{token}}.
Configuração de código de autorização com PKCE
Para testes de contexto de usuário, escolha Código de Autorização (Com PKCE) como o tipo de concessão. PKCE é sua própria opção de concessão no Apidog, não uma caixa de seleção. Você precisará de mais alguns campos:
- URL de Autenticação:
https://auth.example.com/oauth/authorize - URL do Token de Acesso:
https://auth.example.com/oauth/token - URL de Retorno (Callback URL): o URI de redirecionamento registrado com seu provedor
- ID do Cliente e Segredo do Cliente: do seu registro de aplicativo OAuth
Clique em Obter Token e o Apidog abre uma janela do navegador apontando para a página de login. Faça login como seu usuário de teste, aprove a tela de consentimento, e o token retorna e aterrissa no mesmo slot gerenciado de antes. Se seu provedor retornar um token de ID OpenID Connect junto com o token de acesso, uma opção "Token Type Used" permite que você troque qual será anexado; útil quando a API em teste valida tokens de ID.
Uma dica prática: mantenha um usuário de teste dedicado por função que você precisa cobrir (comprador, administrador, auditor somente leitura). Obter um token como cada usuário e reexecutar o mesmo cenário é a maneira mais rápida de verificar as regras de acesso baseadas em função.
Reutilização de token e auto-atualização
Tokens de acesso expiram, geralmente dentro de uma hora. Antes do Apidog lidar com isso, um token expirado significava uma execução falha e uma nova busca manual, que é exatamente o tipo de falha inconsistente que as equipes aprendem a ignorar.
Agora o Apidog atualiza os tokens OAuth 2.0 por conta própria quando o servidor de autorização emitiu um token de atualização, uma capacidade que foi lançada na atualização de junho. Quando o token de acesso armazenado expira, o Apidog usa o token de atualização para obter um novo e o troca antes de enviar. Você também pode apontá-lo para uma URL de token de atualização personalizada nas configurações avançadas, se seu provedor separar os dois endpoints.
Para credenciais de cliente, muitos servidores ignoram completamente os tokens de atualização (a especificação permite, já que o cliente pode se reautenticar a qualquer momento). Na prática, isso não prejudica: refazer a busca com Obter Token é um clique, e execuções agendadas ou de CI podem solicitar um token novo no início de cada execução.
Herdar autenticação no nível da pasta
Configurar OAuth em cada requisição é a altitude errada. O Apidog permite que você defina a autenticação em uma pasta, e as requisições dentro dela herdam a configuração de seu pai. Defina o OAuth 2.0 uma vez em sua pasta "API de Pedidos" e cada requisição abaixo dela, incluindo novas que seus colegas de equipe adicionarem no próximo sprint, enviará o mesmo token gerenciado.
Isso é mais importante em cenários de teste com várias etapas. Um cenário de checkout pode encadear POST /carts, POST /carts/{id}/items e POST /orders. Com a autenticação no nível da pasta, todas as três etapas compartilham um único token e uma única configuração. Quando o token expira no meio do cenário, a atualização automática o cobre. E quando sua equipe de segurança rotaciona o segredo do cliente, você atualiza uma pasta em vez de quarenta requisições.
As requisições mantêm a opção de sobrescrever o pai, o que é exatamente o que você deseja para testes negativos. Mais sobre isso agora.
Testando os caminhos de falha
Testes OAuth de "caminho feliz" provam que sua pipeline de token funciona. Testes de "caminho de falha" provam que sua API impõe a autenticação. Ignore-os e você estará confiando nos padrões do framework. Aqui estão os três casos que valem a pena automatizar; para uma revisão do que cada código de status deve significar, veja nossa comparação de chaves de API e tokens bearer.
Token expirado ou ausente: espere 401
Duplique uma requisição em seu cenário e sobrescreva sua autenticação herdada com nenhuma autenticação ou um token bearer hardcoded e há muito tempo expirado, como Bearer expired_token_do_not_rotate. Afirme que:
- O código de status é
401 - O cabeçalho de resposta
WWW-Authenticateestá presente (o companheiro da RFC 6749, RFC 6750, espera isso) - O corpo não vaza rastreamentos de pilha ou nomes de host internos
Um 200 aqui é um bug crítico. Um 403 é um cheiro de design que vale um ticket: o servidor deve distinguir "Eu não sei quem você é" de "Eu te conheço, e não."
Escopo errado: espere 403
Provisione um segundo cliente de teste limitado a orders:read, obtenha seu token e chame um endpoint de escrita como POST /orders. Afirme que o status é 403 e, se sua API segue a RFC 6750, o cabeçalho WWW-Authenticate inclui error="insufficient_scope". Este teste detecta a clássica má configuração onde os escopos são verificados no gateway para algumas rotas e esquecidos em outras. Se escopos são novidade para sua equipe, escopos OAuth 2.0 explicados abrange como fatiá-los.
Cliente inválido: espere um erro limpo do endpoint de token
Aponte uma requisição diretamente para https://auth.example.com/oauth/token com um client_secret inválido. De acordo com a seção 5.2 da RFC 6749, o servidor deve retornar 400 (ou 401 para autenticação de cliente falha) com um corpo JSON contendo "error": "invalid_client". Afirme ambos. Servidores de autorização também são APIs, e seu contrato de erro faz parte de sua superfície.
Validando respostas de token em cenários de teste
O endpoint de token merece sua própria cobertura além do caso de cliente inválido. Adicione uma etapa em seu cenário de teste chamando o endpoint de token diretamente e, em seguida, anexe asserções à resposta:
access_tokenexiste e não está vaziotoken_typeé igual abearer(ignorando maiúsculas e minúsculas conforme a especificação)expires_iné maior que 0 e dentro de sua política, digamos, não mais que 3600scopecorresponde ao que foi solicitado, detectando servidores que silenciosamente restringem as concessões
Os cenários de teste do Apidog permitem que você adicione essas asserções visuais ao JSON da resposta, sem necessidade de script, e você pode extrair o access_token para uma variável para uma etapa de acompanhamento quando quiser testar o handshake bruto em vez de usar a autenticação gerenciada. Conecte o cenário à sua execução de CI e um servidor de autorização com mau comportamento falhará a build em vez de aparecer como um misterioso 401 em produção.
O loop completo se parece com isso: configuração OAuth 2.0 no nível da pasta para o caminho feliz, substituições por requisição para os casos 401 e 403, e um cenário testando o contrato do endpoint de token. Isso cobre APIs de contexto de usuário através do código de autorização com PKCE e APIs serviço a serviço através de credenciais de cliente, com a atualização de token gerenciada para você. Baixe o Apidog e experimente gratuitamente; o tipo de autenticação OAuth 2.0 funciona no plano gratuito, então você pode apontá-lo para seu próprio endpoint de token em alguns minutos.
FAQ
Qual fluxo OAuth devo usar para testes de API?
Use credenciais de cliente para qualquer coisa máquina a máquina e para a maioria das suítes automatizadas, pois não requer interação com o navegador. Use o fluxo de código de autorização com PKCE quando o teste depender da identidade do usuário: isolamento de dados por usuário, verificações de função ou comportamento de consentimento. Evite as concessões implícitas e de senha em novos planos de teste; ambas são desencorajadas na orientação OAuth atual.
Como faço para atualizar um token expirado automaticamente no Apidog?
Configure o OAuth 2.0 na aba Auth e obtenha um token com "Obter Token". Quando o servidor de autorização retorna um token de atualização, o Apidog atualiza o token de acesso na expiração sem que você precise reautenticar, e você pode definir uma URL de token de atualização separada nas configurações avançadas se seu provedor usar uma. Para configurações de credenciais de cliente sem tokens de atualização, executar novamente "Obter Token" emite um novo.
Cada requisição em um cenário pode compartilhar um único token OAuth?
Sim. Defina a configuração OAuth 2.0 na pasta pai e as requisições internas herdam a configuração, de modo que um cenário de várias etapas é executado sob um único token gerenciado. As requisições individuais ainda podem sobrescrever a configuração da pasta, que é como você insere testes negativos (token expirado, escopo errado) no mesmo cenário.
O que um 401 versus um 403 deve significar em APIs protegidas por OAuth?
Retorne 401 quando a autenticação falhou: o token está ausente, expirado ou malformado. Retorne 403 quando o token é válido, mas não tem permissão, como um escopo ausente. Confundi-los quebra a lógica de nova tentativa do cliente, porque um 401 diz ao cliente para reautenticar enquanto um 403 diz para parar. Nosso guia sobre testar a autenticação JWT aprofunda-se na validação do próprio token.