Add guidance on Firebase + OIDC integration debugging when token exchange fails

[saif-at-scalekit]

Background

Pylon #770 — A developer using Firebase Auth with Scalekit as an OIDC provider (oidc.scalekit) reported an intermittent failure:

INVALID_IDP_RESPONSE: Remote site returned malformed response that cannot be parsed for oidc.scalekit for CODE_EXCHANGE

Setup: SAML to Azure AD → Scalekit → Firebase Auth (as OIDC provider oidc.scalekit) → app

What was found during investigation:

• The Scalekit dashboard showed the flow completing successfully ("Callback to application" green)
• Scalekit had no record of the /oauth/token request from Firebase at the relevant timestamp — suggesting a network connectivity issue between Firebase (Google infrastructure) and Scalekit, rather than a malformed response from Scalekit
• A possible URL encoding artifact was spotted in the callback URL (comma instead of & between code and state params), but this was likely an OpenReplay session recording artifact, not the actual URL
• The issue resolved itself; the customer confirmed successful logins a day later

Problem

Developers setting up Firebase Auth + Scalekit OIDC have no troubleshooting guide when the code exchange silently fails. The Scalekit dashboard only shows events up to "Callback to application" — the /oauth/token exchange is not visible in the event log, making it very hard to self-debug.

Proposed work

Add a troubleshooting section for the Firebase + OIDC integration pattern covering:

1. How to read Auth Logs for SAML+OIDC flows — what each stage in the dashboard represents and where the visibility gap is (after redirect, before token exchange)
2. INVALID_IDP_RESPONSE from Firebase — what it means and common causes:
   • Network issue between Firebase and Scalekit (transient; retry)
   • Clock skew on the auth code (codes are short-lived; long delays between steps can cause this)
   • Malformed callback URL (check that code and state are &-separated, not comma-separated)
3. How to collect a HAR file for sharing with Scalekit support when the issue is intermittent
4. Required attribute mappings for Azure AD SAML → Scalekit → Firebase (the emailaddress → Email mapping must be present; NameID-only assertions will not produce a usable OIDC response)

Suggested location: new ## Troubleshooting section in the Firebase OIDC integration guide, or a new cookbook page.

Additional context

• The /oauth/token exchange not appearing in the customer event log was flagged during this investigation. Consider whether this is an observability gap worth addressing on the platform side.
• Visibility into whether the email claim was present in the SAML assertion required manual investigation by the engineering team. Surfacing this in the Auth Logs UI would reduce future escalation time.