Zum Hauptinhalt springen

Debug authentication issue

Use this page when authentication, claims, session, or redirect behavior fails before the intended task can run.

When to use this page​

  • Login or redirect behavior fails.
  • Claims or session posture looks wrong.
  • You need a public-safe diagnosis path that avoids leaking secrets.

Prerequisites​

  • You can capture the visible auth failure and first failing boundary.
  • You can redact sensitive evidence before escalation.

Architecture / Flow​

Step-by-step procedure​

1. Classify the auth symptom​

Determine whether the failure is:

  • login
  • token or session
  • claims mapping
  • redirect handling
  • secret lookup

2. Capture the first failing boundary​

Record:

  • the visible login or redirect error
  • the first point where flow diverges
  • whether the issue is tenant-specific, browser-specific, or stack-wide

3. Prefer read-only verification first​

Start with the canonical Heddle owner troubleshooting path and other read-only readiness, claims, or config checks. Do not start by rewriting identity or secret configuration.

4. Keep evidence public-safe​

Share:

  • redacted claims or session posture
  • non-secret readiness indicators
  • redirect mismatch symptoms without secret values

5. Escalate when the next step would require unsafe secret exposure​

If the remaining diagnosis requires secret or internal-only mutation detail, stop and escalate with redacted evidence.

Verification​

This runbook is being used correctly when:

  1. the auth symptom is classified before mutation
  2. evidence remains redacted and public-safe
  3. the fix is validated by replaying the same login or task path

Common failure modes​

Rewriting secrets or redirects before capturing evidence​

Problem:

  • the original boundary failure becomes harder to explain.

Better path:

  • capture the first failing boundary and redacted evidence first

Treating every auth issue as the same class​

Problem:

  • claims, redirect, and secret issues get mixed together.

Better path:

  • classify the auth failure before choosing the owner path

Source Truth​

  • contracts/docs/public_manufacturer_docs_post_v1_runbooks_v1.json
  • JaddaHelpifyr/jhf-heddle:docs/TROUBLESHOOTING.md
  • JaddaHelpifyr/jhf-heddle:docs/SECURITY.md
  • JaddaHelpifyr/jhf-keystore:docs/SECURITY.md

Next paths​