Como Testar APIs OAuth 2.0 no Apidog: Código de Autorização, Credenciais do Cliente e Atualização de Token

Como testar APIs protegidas por OAuth 2.0 no Apidog

Toda equipe de API encontra o mesmo obstáculo: os endpoints funcionam isoladamente, mas, quando o OAuth 2.0 é habilitado, metade da suíte começa a retornar 401. Gerenciar servidores de autorização, tokens de curta duração e escopos — além de copiar tokens manualmente de uma resposta curl para um cabeçalho — rapidamente se torna improdutivo.

A solução não é remover a autenticação dos testes. É transformar o gerenciamento de tokens em parte da configuração para eliminar o trabalho manual.

Experimente o Apidog hoje

Este guia mostra como configurar no Apidog os dois fluxos mais usados em testes de API:

• Código de autorização com PKCE: quando a API age em nome de um usuário.
• Credenciais de cliente: para chamadas máquina a máquina.

Se você precisa revisar todos os tipos de concessão primeiro, consulte nossa visão geral dos fluxos OAuth 2.0.

Os dois fluxos OAuth 2.0 mais importantes

A escolha depende de uma pergunta simples:

A API age em nome de um usuário ou em nome de um serviço?

Código de autorização com PKCE

O fluxo de código de autorização obtém um token vinculado a um usuário:

1. O cliente redireciona o usuário para o servidor de autorização.
2. O usuário faz login e concede acesso.
3. O servidor redireciona o cliente de volta com um código de uso único.
4. O cliente troca esse código por um token de acesso no endpoint de token.

A sequência completa está definida na seção 4.1 da RFC 6749.

O PKCE (Proof Key for Code Exchange) adiciona uma prova de posse à troca:

• O cliente gera um verificador aleatório.
• Envia um desafio derivado desse verificador na requisição de autorização.
• Comprova que possui o verificador original ao resgatar o código.

Assim, quem interceptar o código não conseguirá utilizá-lo. Embora tenha surgido para aplicativos móveis, a orientação atual do oauth.net recomenda PKCE para todas as trocas de código de autorização, inclusive para clientes confidenciais.

Use esse fluxo quando o comportamento depender da identidade do usuário, por exemplo:

• GET /orders retorna apenas os pedidos do chamador;
• endpoints administrativos dependem da função do usuário;
• limites de taxa são aplicados por usuário;
• o consentimento precisa ser validado.

Credenciais de cliente

A concessão de credenciais de cliente ignora o usuário. O cliente se autentica com seu próprio ID e segredo e recebe um token que representa o aplicativo.

Uma requisição típica ao endpoint de token é:

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=orders_service \
  -d [REDACTED CREDENTIAL] \
  -d scope="orders:read orders:write"

Esse é o fluxo adequado para:

• microsserviços internos;
• cron jobs;
• pipelines de CI;
• serviços que chamam uma API de implantação;
• suítes de testes automatizadas.

A documentação sobre credenciais de cliente OAuth 2.0 detalha o fluxo.

Se o ambiente de teste permitir provisionar um cliente próprio, use credenciais de cliente sempre que a identidade do usuário não fizer parte do comportamento testado.

Configurando OAuth 2.0 no Apidog

O Apidog trata OAuth 2.0 como um tipo de autenticação nativo. Configure-o na aba Auth de uma requisição ou pasta; a plataforma busca, anexa e renova os tokens automaticamente.

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;
• Implícito.

Os exemplos abaixo usam uma API fictícia de gerenciamento de pedidos.

Configurando credenciais de cliente

Abra uma requisição — ou, preferencialmente, uma pasta — e:

1. Altere o tipo de autenticação para OAuth 2.0.
2. Escolha Credenciais de Cliente.
3. Preencha os campos:

• URL do Token de Acesso: https://auth.example.com/oauth/token
• ID do Cliente: orders_service
• Segredo do Cliente: o segredo provisionado
• Escopo: orders:read orders:write, em Opções avançadas

O Apidog permite enviar as credenciais de duas formas:

• no cabeçalho de autenticação Basic;
• no corpo da requisição.

Escolha o formato esperado pelo servidor de autorização. Auth0 e Okta aceitam ambos, mas alguns servidores internos analisam apenas o corpo.

Clique em Obter Token. O Apidog chama o endpoint, armazena a resposta e mostra o token com seu período de validade. Os envios seguintes adicionam automaticamente:

[REDACTED CREDENTIAL] <access_token>

Não é necessário copiar e colar o token nem criar uma variável manual como {{token}}.

Configurando código de autorização com PKCE

Para testes baseados em contexto de usuário, selecione Código de Autorização (Com PKCE). No Apidog, PKCE aparece como uma concessão própria, não como uma caixa de seleção.

Preencha:

• URL de Autorizaçã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 registrado no provedor
• ID do Cliente e Segredo do Cliente: os dados do registro do aplicativo OAuth

Clique em Obter Token. O Apidog abrirá uma janela do navegador com a página de login. Faça login com o usuário de teste e aprove o consentimento. O token será armazenado no mesmo mecanismo gerenciado usado no fluxo de credenciais de cliente.

Se o provedor retornar um token de ID OpenID Connect junto com o token de acesso, a opção Token Type Used permite escolher qual token será anexado. Isso é útil quando a API valida tokens de ID.

Dica: use usuários de teste por função

Mantenha um usuário dedicado para cada função que precisa ser coberta:

• comprador;
• administrador;
• auditor somente leitura.

Obtenha um token para cada usuário e execute o mesmo cenário. Essa é uma forma rápida de validar regras de acesso baseadas em função.

Reutilização e atualização automática de tokens

Tokens de acesso normalmente expiram dentro de uma hora. Sem renovação automática, a expiração causa uma falha, exige uma nova busca manual e introduz inconsistência nos testes.

O Apidog pode atualizar tokens OAuth 2.0 automaticamente quando o servidor de autorização fornece um token de atualização. Esse recurso foi incluído na atualização de junho.

Quando o token armazenado expira, o Apidog:

1. usa o token de atualização;
2. solicita um novo token de acesso;
3. substitui o token antigo;
4. envia a requisição com o token atualizado.

Se o provedor separar os endpoints, é possível informar uma URL personalizada para atualização nas opções avançadas.

Em credenciais de cliente, muitos servidores não emitem tokens de atualização. A especificação permite isso, pois o cliente pode se autenticar novamente a qualquer momento. Nesse caso:

• clique novamente em Obter Token;
• em execuções de CI ou agendadas, solicite um token novo no início de cada execução.

Herdando autenticação no nível da pasta

Configurar OAuth 2.0 individualmente em cada requisição aumenta a manutenção. No Apidog, defina a autenticação na pasta e permita que as requisições filhas herdem a configuração.

Por exemplo, configure OAuth 2.0 na pasta API de Pedidos. Todas as requisições atuais e futuras dentro dela compartilharão o token gerenciado.

Isso é especialmente útil em cenários com várias etapas:

POST /carts
POST /carts/{id}/items
POST /orders

Com a autenticação na pasta:

• as três etapas usam a mesma configuração;
• o token pode ser renovado automaticamente durante o cenário;
• a rotação do segredo exige uma única alteração;
• novas requisições herdam a configuração sem trabalho adicional.

As requisições individuais ainda podem substituir a autenticação herdada. Use essa opção para criar testes negativos.

Testando caminhos de falha

Testes de caminho feliz mostram que a obtenção do token funciona. Testes de caminho de falha mostram que a API realmente impõe autenticação e autorização.

Os três casos abaixo são bons candidatos à automação. Para mais contexto sobre a diferença entre mecanismos, consulte a comparação entre chaves de API e tokens bearer.

1. Token ausente ou expirado: espere 401

Duplique uma requisição do cenário e substitua a autenticação herdada por:

• nenhuma autenticação; ou
• um token Bearer [REDACTED], como Bearer [REDACTED].

Valide que:

• o status é 401;
• o cabeçalho de resposta WWW-Authenticate está presente;
• o corpo não expõe stack traces nem nomes de host internos.

A RFC 6750 define as expectativas para tokens bearer.

Um 200 nesse caso é um bug crítico. Um 403 indica um problema de modelagem: a API deve distinguir entre “não sei quem você é” e “sei quem você é, mas você não tem permissão”.

2. Escopo insuficiente: espere 403

Provisione um segundo cliente limitado a orders:read. Obtenha um token e chame um endpoint de escrita:

POST /orders

Valide que:

• o status é 403;
• quando a API segue a RFC 6750, WWW-Authenticate inclui error="insufficient_scope".

Esse teste identifica configurações inconsistentes em que o gateway verifica escopos para algumas rotas, mas não para outras. Se escopos ainda forem novidade para sua equipe, consulte Escopos OAuth 2.0 explicados.

3. Cliente inválido: valide o erro do endpoint de token

Envie uma requisição diretamente para:

https://auth.example.com/oauth/token

Use um client_secret inválido. De acordo com a seção 5.2 da RFC 6749, o servidor deve retornar:

• status 400, ou 401 quando a autenticação do cliente falhar;
• um corpo JSON contendo:

{
  "error": "invalid_client"
}

Valide o status esperado e o campo error. Servidores de autorização também são APIs, portanto seu contrato de erro faz parte da superfície que precisa ser testada.

Validando respostas do endpoint de token

O endpoint de token merece cobertura própria, além do caso de cliente inválido.

Adicione uma etapa que o chame diretamente e valide:

• access_token existe e não está vazio;
• token_type é bearer, sem diferenciar maiúsculas e minúsculas;
• expires_in é maior que zero e está dentro da política, por exemplo, no máximo 3600;
• scope corresponde ao solicitado.

A última asserção detecta servidores que restringem concessões silenciosamente.

Os cenários de teste do Apidog permitem adicionar asserções visuais à resposta JSON sem escrever scripts. Também é possível extrair access_token para uma variável e usá-lo em uma etapa posterior, caso você queira testar o handshake bruto em vez da autenticação gerenciada.

Conecte o cenário à execução de CI. Dessa forma, um servidor de autorização com comportamento incorreto falha a build, em vez de aparecer apenas como um 401 misterioso em produção.

Fluxo recomendado

Uma configuração prática combina:

1. OAuth 2.0 no nível da pasta para o caminho feliz;
2. Substituições por requisição para os casos de 401 e 403;
3. Um cenário dedicado para validar o contrato do endpoint de token;
4. Código de autorização com PKCE para APIs baseadas em usuário;
5. Credenciais de cliente para APIs serviço a serviço;
6. Atualização automática sempre que o provedor emitir tokens de atualização.

Você pode baixar o Apidog e testar gratuitamente. O tipo de autenticação OAuth 2.0 está disponível no plano gratuito, permitindo apontar a ferramenta para seu próprio endpoint de token em poucos minutos.

FAQ

Qual fluxo OAuth devo usar para testes de API?

Use credenciais de cliente para chamadas máquina a máquina e para a maioria das suítes automatizadas, pois não exigem interação com o navegador.

Use código de autorização com PKCE quando o teste depender da identidade do usuário, como:

• isolamento de dados por usuário;
• verificações de função;
• comportamento de consentimento.

Evite as concessões implícita e de senha em novos planos de teste; ambas são desencorajadas pela orientação OAuth atual.

Como atualizo automaticamente um token expirado no Apidog?

Configure OAuth 2.0 na aba Auth e clique em Obter Token. Quando o servidor retornar um token de atualização, o Apidog renovará o token de acesso após a expiração, sem exigir novo login.

Se o provedor usar um endpoint separado, informe a URL nas opções avançadas. Em configurações de credenciais de cliente sem tokens de atualização, execute Obter Token novamente para emitir um token novo.

Cada requisição de um cenário pode compartilhar um único token OAuth?

Sim. Defina OAuth 2.0 na pasta pai. As requisições internas herdarão a configuração e o cenário será executado com um token gerenciado.

As requisições individuais podem substituir a configuração da pasta. É assim que você adiciona testes negativos de token expirado ou escopo insuficiente ao mesmo cenário.

O que 401 e 403 devem significar em APIs protegidas por OAuth?

Retorne 401 quando a autenticação falhar: o token está ausente, expirado ou malformado.

Retorne 403 quando o token for válido, mas não conceder a permissão necessária, como um escopo ausente.

Confundir os dois códigos quebra a lógica de nova tentativa do cliente: 401 indica que o cliente deve se autenticar novamente, enquanto 403 indica que deve interromper a tentativa. Para aprofundar a validação do token, consulte o guia sobre como testar a autenticação JWT.