docs(auth): document federated_identity claims in beforeLogin hook#138
Merged
Conversation
The Built-in IdP now forwards the upstream Google/Microsoft profile to the beforeLogin hook on claims.federated_identity, and the SDK types it (tailor-platform/sdk#1456). Document the consumer-facing behavior so app developers know the claim exists, its shape, the per-provider differences (Microsoft issues no picture), and that it is populated only on a user's next federated login with no backfill. docs/sdk/services/auth.md is intentionally left untouched; it is auto-synced from the SDK repo by the sdk-docs-sync workflow, whose source page was already updated in the SDK PR.
The handler signature is { claims, idpConfigName, env } per the SDK auth
docs, but the guide's Handler Arguments table listed only claims and
idpConfigName, misrepresenting the signature for readers relying on this
page.
federated_identity is undefined for any non-federated login, not just
password logins, so generalize the guard note to avoid implying it
exists for external IdP flows. Also update the Execution Flow diagram to
the object-shaped beforeLogin({ claims, idpConfigName, env }) so it no
longer disagrees with the Handler Arguments table.
The Google/Microsoft OAuth notes read as if the upstream profile is always forwarded, but federated_identity is only observable when a beforeLogin hook is configured to receive it. Reword both to state the condition explicitly so readers do not expect it in tokens or without a hook.
federated_identity is just another value available in the beforeLogin hook, and persisting it is the application's responsibility, which the preceding tip already covers. A dedicated no-backfill warning over-emphasizes the claim and adds noise.
anukiransolur
approved these changes
Jun 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When the Built-in IdP federates a Google or Microsoft login, the upstream provider's profile (such as
picture,name,given_name,family_name,locale) is now forwarded to thebeforeLoginhook onclaims.federated_identity. The SDK types this claim in tailor-platform/sdk#1456. This documents the consumer-facing behavior in the auth guides so app developers know the claim exists and how to use it.Changes
docs/guides/auth/hook.md— add a Federated Identity Claims section under the Before Login Hook guide: thefederated_identityshape (provider+claims), per-provider availability (Microsoft issues nopicture), a usage example, and notes that the claim is hook-only (not on the app-facing session token) and is populated only on the next federated login with no backfill. Cross-references it from the Handler Arguments table.docs/guides/auth/integration/built-in-idp.md— note in the Google OAuth and Microsoft OAuth sections that the account profile is forwarded to thebeforeLoginhook, linking to the new section.docs/sdk/services/auth.mdis intentionally not edited here. It is auto-synced from the SDK repo by thesdk-docs-syncworkflow, and the source page was already updated in the SDK PR.Verification
pnpm build✅ (pages render, internal anchor link resolves, dead-link check passes)Note for reviewers
This documents behavior tied to the Built-in IdP Google/Microsoft OAuth feature, which is already marked preview in
built-in-idp.md. Kept as a draft until the platform-side rollout lands.