Skip to main content

Troubleshooting (IDP)

Common issues and solutions for the Identity Provider.

Authentication Issues​

401 after login​

  • Check audience mapping (IDP_AUDIENCE_ROLE_MAP) allows your roles for the target audience
  • Verify JWT aud matches the service; confirm CORS allows the SPA origin
  • Ensure X-Client-Audience header is set on login/refresh requests

429 Too Many Requests​

Rate limit exceeded on /auth/refresh:

# Check current limits
kubectl logs -n idp deployment/idp-backend | grep "rate limit"

Solutions:

  • Wait for Retry-After duration (in response header)
  • Client should implement exponential backoff
  • Increase limits if legitimate traffic: IDP_REFRESH_RATE_LIMIT_IP, IDP_REFRESH_RATE_LIMIT_JTI

Refresh loop (continuous 401s)​

Client making repeated /auth/refresh calls returning REFRESH_SESSION_NOT_FOUND:

Symptoms:

  • IDP logs show thousands of refresh attempts
  • Error code REFRESH_SESSION_NOT_FOUND

Causes:

  1. Client not clearing tokens on failed refresh
  2. Storybook/dev builds hitting real IDP
  3. Multiple tabs with stale tokens

Solutions:

  • Ensure client calls logout() on refresh failure
  • Add MSW handlers for /auth/refresh (401) and /auth/csrf (204) in test/dev
  • IDP rate limiting prevents storm (429 response)

Health & Startup Issues​

Health endpoint failures​

# Check health endpoints
curl -s https://idp.uat.digiwedge.com/api/health | jq '.status'
curl -s https://idp.uat.digiwedge.com/api/health/ready | jq '.'
IndicatorIssueSolution
db.status: downDatabase unreachableCheck DATABASE_URL, network policies
redis.status: downRedis unreachableCheck REDIS_HOST, REDIS_PORT
env.missingRequiredMissing env varsAdd missing variables to Infisical/secrets

Set CI_OFFLINE=true in non-prod to skip provider pings.

Template health check failures​

At startup, IDP validates required notification templates exist:

kubectl logs -n idp deployment/idp-backend | grep -E "template|CRITICAL"

Missing templates error:

CRITICAL: Missing required auth templates: account_deletion_requested (EMAIL)

Solution: Seed templates via port-forward:

# Port-forward to messaging DB
kubectl port-forward -n messaging svc/messaging-postgres 5436:5432 &

# Run seed scripts
MESSAGING_DATABASE_URL="postgres://..." pnpm tsx tools/scripts/messaging/seeds/seed-account-deletion-requested.ts

OAuth Issues​

OAuth disabled​

Check /health/providers for oauth.googleEnabled/facebookEnabled:

curl -s https://idp.uat.digiwedge.com/api/health/providers | jq '.info.oauth'

Solutions:

  • Ensure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set
  • Ensure FACEBOOK_APP_ID and FACEBOOK_APP_SECRET are set
  • Verify callback URLs match provider configuration

OAuth redirect failures​

Error: returnTo URL not in allowlist

Solution: Add origin to OAUTH_ALLOWED_RETURN_ORIGINS:

OAUTH_ALLOWED_RETURN_ORIGINS=http://localhost:5173,https://app.example.com

For mobile apps, add scheme to OAUTH_ALLOWED_RETURN_SCHEMES:

OAUTH_ALLOWED_RETURN_SCHEMES=teetime-mobile,exp

Logs & Debugging​

Enable debug logging​

# Set log level
LOG_LEVEL=debug kubectl rollout restart -n idp deployment/idp-backend

View recent errors​

kubectl logs -n idp deployment/idp-backend --since=1h | grep -iE "error|warn|fail"

Check pod events​

kubectl describe pod -n idp -l app=idp-backend | tail -30