From 4a30c60b19489a72ad81ef43e47417f7695e98b1 Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 16 Jun 2026 14:47:55 +0900 Subject: [PATCH 1/5] docs(auth): document federated_identity claims in beforeLogin hook 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. --- docs/guides/auth/hook.md | 38 +++++++++++++++++++- docs/guides/auth/integration/built-in-idp.md | 4 +++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/guides/auth/hook.md b/docs/guides/auth/hook.md index 50e9764..62d9b64 100644 --- a/docs/guides/auth/hook.md +++ b/docs/guides/auth/hook.md @@ -93,9 +93,45 @@ The hook handler receives the following arguments: | Argument | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------ | -| **claims** | object | The claims returned by the Identity Provider (e.g., email, name). | +| **claims** | object | The claims returned by the Identity Provider (e.g., email, name). For Built-in IdP federated logins, also carries [`federated_identity`](#federated-identity-claims). | | **idpConfigName** | string | The name of the IdP configuration that authenticated the user. | +## Federated Identity Claims + +When a user signs in through a [Built-in IdP](/guides/auth/integration/built-in-idp) OAuth provider (Google or Microsoft), the upstream provider's profile is forwarded to the hook on `claims.federated_identity`. A common use is to populate the user record from the provider's profile during [JIT provisioning](#example-jit-user-provisioning). + +`claims.federated_identity` is `undefined` for password logins, so guard before reading it. + +| Field | Type | Description | +| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **provider** | `"google" \| "microsoft"` | The upstream OAuth provider that federated the login. | +| **claims** | object | Profile claims from the provider's ID token. Commonly present claims (`name`, `given_name`, `family_name`, `picture`, `locale`) are available; any other claim the provider issues is forwarded as-is. | + +Claim availability varies by provider. For example, Microsoft does not issue `picture`. + +```typescript +hooks: { + beforeLogin: { + handler: async ({ claims }) => { + const federated = claims.federated_identity; + if (federated?.provider === "google") { + // Populate the user record from the upstream profile + const avatarUrl = federated.claims.picture; + } + }, + invoker: "hook-invoker", + }, +} +``` + +:::tip +`claims.federated_identity` is a login-flow signal available only inside the `beforeLogin` hook. It is not part of the app-facing session token. Persist whatever your app needs into your own TailorDB type during the hook. +::: + +:::warning +`federated_identity` is populated on a user's next federated login. Profiles for users who logged in before this feature are not backfilled, because the upstream claims were never stored. +::: + ## Example: JIT User Provisioning The following example configures a `beforeLogin` hook inline in `defineAuth` that creates a user record in TailorDB when a user logs in for the first time: diff --git a/docs/guides/auth/integration/built-in-idp.md b/docs/guides/auth/integration/built-in-idp.md index cc178fd..e0b97b0 100644 --- a/docs/guides/auth/integration/built-in-idp.md +++ b/docs/guides/auth/integration/built-in-idp.md @@ -328,6 +328,8 @@ The Built-in IdP supports "Sign in with Google", allowing users to authenticate 4. If the user does not yet exist, a new IdP user is automatically created using the Google account's email address (without a password) 5. The user is signed in and redirected to the application +During login, the Google account's profile (such as `picture`, `name`, `given_name`, `family_name`, and `locale`) is forwarded to the [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims) on `claims.federated_identity`. Use it to populate your user record from the provider's profile. + :::tip Users created via Google OAuth do not have a password set. They can only sign in using Google. To enable password-based login for these users, use the `_sendPasswordResetEmail` mutation to set an initial password. ::: @@ -379,6 +381,8 @@ The Built-in IdP supports "Sign in with Microsoft", allowing users to authentica 4. If the user does not yet exist, a new IdP user is automatically created using the Microsoft account's preferred username (UPN) (without a password) 5. The user is signed in and redirected to the application +During login, the Microsoft account's profile (such as `name`, `given_name`, and `family_name`) is forwarded to the [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims) on `claims.federated_identity`. Microsoft does not issue `picture`. + :::tip Users created via Microsoft OAuth do not have a password set. They can only sign in using Microsoft. ::: From 0e5170c940976d8dfb9a4e9d5f0b13d76b59da16 Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 16 Jun 2026 15:30:02 +0900 Subject: [PATCH 2/5] docs(auth): add env to beforeLogin Handler Arguments table 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. --- docs/guides/auth/hook.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/auth/hook.md b/docs/guides/auth/hook.md index 62d9b64..52c8c35 100644 --- a/docs/guides/auth/hook.md +++ b/docs/guides/auth/hook.md @@ -95,6 +95,7 @@ The hook handler receives the following arguments: | ----------------- | ------ | ------------------------------------------------------------------ | | **claims** | object | The claims returned by the Identity Provider (e.g., email, name). For Built-in IdP federated logins, also carries [`federated_identity`](#federated-identity-claims). | | **idpConfigName** | string | The name of the IdP configuration that authenticated the user. | +| **env** | object | Environment variables defined in `defineConfig({ env })` (the same values available via `context.env` in resolvers). | ## Federated Identity Claims From c0992cbef28b861e69e11b4e1c88cf1569076e38 Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 16 Jun 2026 15:37:10 +0900 Subject: [PATCH 3/5] docs(auth): clarify federated_identity scope and sync the flow diagram 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. --- docs/guides/auth/hook.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/auth/hook.md b/docs/guides/auth/hook.md index 52c8c35..613283e 100644 --- a/docs/guides/auth/hook.md +++ b/docs/guides/auth/hook.md @@ -31,7 +31,7 @@ sequenceDiagram User->>+IdP: Authenticate IdP->>-Auth: Authentication success (claims) - Auth->>+Hook: beforeLogin(claims, idpConfigName) + Auth->>+Hook: beforeLogin({ claims, idpConfigName, env }) Hook->>DB: Custom logic (e.g., create user) DB->>Hook: Result Hook->>-Auth: Success / Error @@ -101,7 +101,7 @@ The hook handler receives the following arguments: When a user signs in through a [Built-in IdP](/guides/auth/integration/built-in-idp) OAuth provider (Google or Microsoft), the upstream provider's profile is forwarded to the hook on `claims.federated_identity`. A common use is to populate the user record from the provider's profile during [JIT provisioning](#example-jit-user-provisioning). -`claims.federated_identity` is `undefined` for password logins, so guard before reading it. +`claims.federated_identity` is `undefined` for any non-federated login (for example, password logins or external IdP flows), so guard before reading it. | Field | Type | Description | | ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | From 704ad569955df697c8971a352fcf1ac0708d24cf Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 16 Jun 2026 15:46:34 +0900 Subject: [PATCH 4/5] docs(auth): make federated_identity availability conditional on the hook 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. --- docs/guides/auth/integration/built-in-idp.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/auth/integration/built-in-idp.md b/docs/guides/auth/integration/built-in-idp.md index e0b97b0..f69c031 100644 --- a/docs/guides/auth/integration/built-in-idp.md +++ b/docs/guides/auth/integration/built-in-idp.md @@ -328,7 +328,7 @@ The Built-in IdP supports "Sign in with Google", allowing users to authenticate 4. If the user does not yet exist, a new IdP user is automatically created using the Google account's email address (without a password) 5. The user is signed in and redirected to the application -During login, the Google account's profile (such as `picture`, `name`, `given_name`, `family_name`, and `locale`) is forwarded to the [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims) on `claims.federated_identity`. Use it to populate your user record from the provider's profile. +If you configure a [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims), the Google account's profile (such as `picture`, `name`, `given_name`, `family_name`, and `locale`) is available to it on `claims.federated_identity`, so you can populate your user record from the provider's profile. :::tip Users created via Google OAuth do not have a password set. They can only sign in using Google. To enable password-based login for these users, use the `_sendPasswordResetEmail` mutation to set an initial password. @@ -381,7 +381,7 @@ The Built-in IdP supports "Sign in with Microsoft", allowing users to authentica 4. If the user does not yet exist, a new IdP user is automatically created using the Microsoft account's preferred username (UPN) (without a password) 5. The user is signed in and redirected to the application -During login, the Microsoft account's profile (such as `name`, `given_name`, and `family_name`) is forwarded to the [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims) on `claims.federated_identity`. Microsoft does not issue `picture`. +If you configure a [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims), the Microsoft account's profile (such as `name`, `given_name`, and `family_name`) is available to it on `claims.federated_identity`. Microsoft does not issue `picture`. :::tip Users created via Microsoft OAuth do not have a password set. They can only sign in using Microsoft. From 7aebdd683da3dc7b3082eea0e971b548fb9d38cb Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 16 Jun 2026 16:09:27 +0900 Subject: [PATCH 5/5] docs(auth): drop the federated_identity backfill warning 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. --- docs/guides/auth/hook.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/guides/auth/hook.md b/docs/guides/auth/hook.md index 613283e..aa61898 100644 --- a/docs/guides/auth/hook.md +++ b/docs/guides/auth/hook.md @@ -129,10 +129,6 @@ hooks: { `claims.federated_identity` is a login-flow signal available only inside the `beforeLogin` hook. It is not part of the app-facing session token. Persist whatever your app needs into your own TailorDB type during the hook. ::: -:::warning -`federated_identity` is populated on a user's next federated login. Profiles for users who logged in before this feature are not backfilled, because the upstream claims were never stored. -::: - ## Example: JIT User Provisioning The following example configures a `beforeLogin` hook inline in `defineAuth` that creates a user record in TailorDB when a user logs in for the first time: