Skip to main content

Runbook: Authentication Issues

Purpose​

Restore authentication flows when users cannot log in or receive SSO errors.

Symptoms​

  • Login redirects loop or fail
  • OAuth callback errors in logs
  • Users receive 401/403 after login

Prerequisites​

  • SSH access to odin
  • Access to Zitadel admin console

Procedure​

Step 1: Check Zitadel availability​

curl -I https://auth.ravenhelm.dev

Step 2: Inspect OAuth2-Proxy / service logs​

# OAuth2-Proxy example
ssh ravenhelm@100.115.101.81 "docker logs oauth2-proxy --tail 200"

# Service-specific auth logs
ssh ravenhelm@100.115.101.81 "docker logs <service> --tail 200"

Step 3: Validate redirect URIs​

Confirm the redirect/callback URLs configured in Zitadel match the service URL.

If sessions are failing across all services, verify the OAuth2-Proxy cookie secret is present and consistent.

ssh ravenhelm@100.115.101.81 "grep OAUTH2_PROXY_COOKIE_SECRET ~/ravenhelm/secrets/.env"

Step 5: Restart auth components​

ssh ravenhelm@100.115.101.81 "docker restart oauth2-proxy"

Verification​

  • Successful login redirects to the expected app
  • No new auth errors in logs

Rollback​

If changes were made to redirect URIs or secrets, revert to the previous values and restart affected services.