Erros e segurança do OAuth

Identifique falhas no fluxo OAuth e proteja credenciais, códigos e tokens.

Erros OAuth podem acontecer durante a autorização, na troca ou renovação dos tokens e nas chamadas à API GraphQL.

Não tente corrigir um erro reutilizando códigos, sessões ou tokens antigos. Quando a tentativa não puder ser recuperada com segurança, inicie uma nova autorização.

Erros durante a autorização

Esses erros chegam à URL de redirecionamento.

Situação	O que fazer
error=access_denied	O usuário pode ter negado o acesso, desmarcado todas as permissões ou recebido uma solicitação sem escopos válidos. Mostre que a conexão não foi concluída e ofereça uma nova tentativa somente se ele quiser continuar.
error=login_required	Pode acontecer quando a solicitação usa prompt=none. Este parâmetro não é suportado no momento. Inicie uma autorização normal no navegador, sem prompt=none.
error=invalid_scope	Confira se os escopos existem, estão habilitados no aplicativo e foram enviados separados por espaços.
error=invalid_client	Confira o Client ID, se o aplicativo continua ativo e se a URL de redirecionamento corresponde exatamente à cadastrada.
state ausente ou diferente	Descarte o callback e a sessão de autorização. Não use o código recebido.

Receber menos permissões do que as solicitadas não é necessariamente um erro. O usuário pode conceder apenas um subconjunto. Sua integração deve funcionar dentro do acesso realmente concedido.

Erros na troca do código

O endpoint /oauth/token retorna um erro OAuth e, em alguns casos, um hint com mais detalhes.

Situação	O que fazer
error=invalid_client ou HTTP 401	Confira o Client ID, o Client Secret e se o aplicativo está ativo.
error=invalid_request com indicação de URL inválida	Envie exatamente a mesma redirect_uri cadastrada e usada no início da autorização.
Código ausente, expirado, revogado ou reutilizado	Inicie uma nova autorização. Códigos de autorização são temporários e de uso único.
Código emitido para outro cliente	Use as credenciais do mesmo aplicativo que iniciou a autorização.
code_verifier ausente ou malformado	Envie o verificador da mesma tentativa, com 43 a 128 caracteres.
error=invalid_grant com falha na verificação de PKCE	O code_verifier não corresponde ao code_challenge. Descarte a tentativa e inicie uma nova autorização.

Erros na renovação

Se o refresh_token for rejeitado:

1. confirme que a integração está usando o valor mais recente;

2. verifique se outra requisição já renovou os tokens;

3. interrompa novas tentativas automáticas com o mesmo valor;

4. peça uma nova autorização ao usuário se o token expirou ou foi revogado.

Não repita indefinidamente uma renovação que retornou erro. Isso não recupera o token e pode esconder um problema de concorrência ou revogação.

Erros na API GraphQL

Resposta	Possível causa
HTTP 401 com {"message":"unauthorized"}	O access_token está ausente, inválido, expirado ou foi revogado. Tente renovar os tokens. Se a renovação falhar, solicite uma nova autorização.
HTTP 200 com errors[].message="Unauthorized"	O token foi aceito, mas a permissão necessária não foi concedida ou a operação não aceita OAuth. Confira o escopo da operação.

Como o GraphQL pode retornar erros com HTTP 200, verifique também o campo errors da resposta.

Checklist de segurança

Antes de publicar a integração, confirme:

• O Client Secret existe somente no backend.

• As URLs de redirecionamento usam HTTPS em produção.

• A URL recebida e enviada é comparada exatamente com a cadastrada.

• Cada autorização cria novos valores de state e PKCE.

• O callback rejeita state ausente ou diferente.

• O código de autorização nunca é reutilizado.

• A integração solicita somente as permissões necessárias.

• Tokens são armazenados de forma protegida e nunca aparecem em URLs ou logs.

• A renovação salva o novo refresh_token antes de liberar outras requisições.

• A integração consegue revogar e apagar acessos que não são mais necessários.

Em caso de vazamento

Se houver suspeita de vazamento do Client Secret:

1. crie um novo aplicativo OAuth;

2. atualize a integração com as novas credenciais;

3. confirme que o novo aplicativo está funcionando;

4. revogue o aplicativo comprometido.

A revogação desativa o aplicativo e seus tokens.

Revogue também um aplicativo quando:

• a integração for descontinuada;

• ela não precisar mais acessar as contas dos usuários;

• houver comportamento inesperado que indique uso indevido das credenciais ou tokens.

Depois de conter o incidente, remova credenciais de logs, repositórios e ferramentas em que elas possam ter sido registradas e revise como o vazamento aconteceu.