🔧 Troubleshooting

Erros Comuns

ValueError: cript_verifier_secret must be a valid 44-character Fernet key

Causa: cript_verifier_secret não é um valor Fernet válido.

Solução:

from govbr_auth.utils import generate_cript_verifier_secret
secret = generate_cript_verifier_secret()
# Cole em seu .env

ValueError: Invalid or missing code_verifier

Causa: State foi corrompido, expirou ou secret foi trocado.

Verificar:

cript_verifier_secret é o mesmo entre requests
State não foi truncado na URL
Session não expirou (15 min aprox)

Solução: Gere novo authorize URL e tente novamente

GovBrAuthenticationError: JWT signature verification failed

Causa: Token JWT está inválido ou foi signed com secret diferente.

Se em desenvolvimento:

# Certifique que jwt_secret bate
GOVBR_JWT_SECRET=sua-chave-aqui

Se em produção:

Chaves públicas JWKS estão diferentes?

Issuer URL está correta?

Solução: Verifique logs e configuração de JWT

GovBrAuthenticationError: Token de ID não encontrado na resposta

Causa: Gov.br retornou erro ou resposta inválida.

Verificar:

client_id e client_secret estão corretos?
redirect_uri bate com registrado no Gov.br?
URLs de auth/token estão corretas?

Solução: Verifique .env e dados de cadastro no Gov.br

Endpoints Fake Não Aparecem

Sintoma: Acessar http://localhost:8000/fake-govbr/authorize retorna 404.

Possíveis causas:

Modo fake não está ativado

config = GovBrConfig(..., use_fake=True)  # ← Necessário

URLs não apontam para endpoints fake

config = GovBrConfig(
    govbr_auth_url="http://localhost:8000/fake-govbr/authorize",  # ✅
    govbr_token_url="http://localhost:8000/fake-govbr/token",      # ✅
    use_fake=True
)

Connector.init_*() não foi chamado

connector.init_fastapi(app)  # ← Registra as rotas

Solução: Verifique .env e código de inicialização

Login Fake Não Funciona

Sintoma: Página de login fake não aceita suas credenciais.

Causas comuns:

CPF não está nos usuários padrão

Usuários padrão: 12345678901, 98765432100, 11122233344

Crie custom fake users:

from govbr_auth import FakeUserData

fake_users = {
    "12345678901": FakeUserData(
        cpf="12345678901",
        nome="Seu Nome",
        email="seu@email.com"
    )
}

connector = GovBrConnector(config, fake_users=fake_users)

Senha incorreta

A senha é sempre o CPF!

CPF: 12345678901
Senha: 12345678901  ✅

Callback de Sucesso Não é Chamado

Sintoma: Após autenticação, callback não executa.

Possíveis causas:

Callback não retorna Response válida (FastAPI)

# ❌ Errado
def on_auth_success(data, request):
    return None  # FastAPI não sabe o que fazer

# ✅ Correto
def on_auth_success(data, request):
    return {"status": "ok"}

Erro em callback está silencioso

Adicione try/except no callback:

def on_auth_success(data, request):
    try:
        user = data["id_token_decoded"]
        # seu código
        return {"status": "ok"}
    except Exception as e:
        print(f"Erro: {e}")
        raise

Callback é async mas não foi awaited (FastAPI)

O framework detecta automaticamente:

# ✅ Ambos funcionam
async def on_auth_success(data, request):
    await db.save_user(...)
    return {"status": "ok"}

CORS Bloqueando Requisição

Sintoma: Console do navegador mostra CORS error.

Solução para FastAPI:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "https://seu-app.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Solução para Flask:

from flask_cors import CORS

app = Flask(__name__)
CORS(app, origins=["http://localhost:3000", "https://seu-app.com"])

Estado Criptografado Perdido Após Redeploy

Sintoma: Ao reiniciar servidor, state fica inválido.

Causa: cript_verifier_secret mudou ou estado em cache foi perdido.

Prevenção:

Mantenha mesmo secret entre deployments

# Todos os servers devem ter:
CRIPT_VERIFIER_SECRET=mesmo-valor

Estado válido por ~15 min

Não é esperado manter session entre restarts.

Redirect URI Mismatch

Sintoma: Gov.br rejeita com “redirect_uri mismatch”.

Causa: URL registrada no Gov.br não bate com usada no código.

Verificar:

Acesse cadastro no Gov.br
Copie exatamente o redirect_uri registrado

Cole em .env:

GOVBR_REDIRECT_URI=https://seu-app.com/auth/govbr/callback

Verifique protocolo (http vs https)
Verifique porta
Verifique caminho exato

Endpoint Retorna 500

Sintoma: POST/GET retorna 500 Internal Server Error.

Verificar:

Logs do servidor

# FastAPI
# O erro é exibido no console

.env está completo?

# Campos obrigatórios
GOVBR_CLIENT_ID=
GOVBR_CLIENT_SECRET=
GOVBR_REDIRECT_URI=
CRIPT_VERIFIER_SECRET=
GOVBR_AUTH_URL=
GOVBR_TOKEN_URL=

Faça ping para Gov.br

curl https://sso.acesso.gov.br/authorize

Firewall está bloqueando?

Teste conectividade com Gov.br

Teste de Conectividade

Testar conexão com Gov.br:

python -c "
import httpx
try:
    r = httpx.get('https://sso.acesso.gov.br/authorize', timeout=10)
    print(f'Status: {r.status_code}')
except Exception as e:
    print(f'Erro: {e}')
"

Testar fernet key:

from cryptography.fernet import Fernet
from govbr_auth.utils import generate_cript_verifier_secret

secret = generate_cript_verifier_secret()
print(f"Válido: {len(secret) == 44}")

# Ou teste uma chave existente
secret = "Vvd9H5VC2Aqk-dwFOJX6MvQTuZZARmb37y7un9wkj0c="
try:
    f = Fernet(secret.encode())
    print("Chave válida!")
except:
    print("Chave inválida!")

Performance Lenta

Sintoma: Login leva muito tempo.

Possíveis causas:

Conexão lenta com Gov.br
- Teste latência: ping sso.acesso.gov.br
- Tente diferentes regiões
JWKS fetch lento
- Primeira chamada baixa chaves públicas (slow)
- Depois cacham (rápido)
Banco de dados no callback
- Se callback faz operações DB lentas
- Otimize queries ou use async

Suporte e Ajuda

Se nenhuma solução acima funcionou:

Verifique CHANGELOG.md para known issues
Abra issue no GitHub
Inclua:
- Versão Python
- Versão biblioteca
- Stack trace completo
- .env (sem secrets)
- Reprodução mínima