Add workflows to dynamically capture IdP claims and inject into tokens

[Koosha-Owji]

Explain your changes

This PR adds two workflows that dynamically capture ALL claims from social identity providers (Google, Microsoft, etc.) and inject them into Kinde tokens.

How it works

Workflow 1: CaptureIdpClaimsWorkflow (PostAuthentication)

• Captures all claims from the IdP's ID token
• Filters out noise claims (standard JWT claims, Microsoft's large aio token, etc.)
• Stores them in a single idp_claims user property as JSON
• Automatically creates the property if it doesn't exist

Workflow 2: AddIdpClaimsToTokensWorkflow (TokensGeneration)

• Reads the stored idp_claims property via Management API
• Adds all claims to both access and ID tokens with idp_ prefix
• Works on every token generation, not just initial authentication

Checklist

• I have read the "Pull requests" section in the contributing guidelines.
• I agree to the terms within the code of conduct.

🛟 If you need help, consider asking for advice over in the Kinde community.

Summary by CodeRabbit

• New Features
  • New workflows to capture identity provider claims from OAuth2/OIDC social authentications, securely store them as user properties, and automatically inject them into both access and ID tokens with an idp_ prefix, enabling downstream applications to leverage enriched authentication context
• Documentation
  • Updated README with new endpoint documentation and practical usage examples for the identity provider claims capture and token injection workflows

[coderabbitai]

Walkthrough

Two new TypeScript workflows were added: one captures IdP/OIDC id_token claims on PostAuthentication and stores them as a JSON user property; the other runs on token generation, reads that stored JSON, and injects claims into access and ID tokens with an idp_ prefix.

Changes

Cohort / File(s)	Summary
IdP Claims Capture Workflow captureIdpClaimsToTokens/CaptureIdpClaimsWorkflow.ts	New PostAuthentication workflow that extracts OAuth2/OIDC id_token claims, filters noise via an ignore list, ensures a idp_claims user property exists (creates if missing with configurable category), and stores filtered claims plus metadata as JSON in that property.
IdP Claims Injection Workflow captureIdpClaimsToTokens/AddIdpClaimsToTokensWorkflow.ts	New onTokensGeneration workflow that fetches users/{userId}/properties, reads and parses idp_claims JSON, and injects each claim into both access and ID tokens as idp_<claimName> (skips keys starting with _). Includes error handling and logging.
Documentation README.md	Adds an endpoint entry /captureIdpClaimsToTokens and an example pointer "Capture IdP claims to tokens" linking to the new workflows.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Auth as PostAuthentication
    participant API as KindeAPI
    participant Props as UserProperties
    participant TokenGen as TokenGeneration
    participant Tokens as Access/ID Tokens

    User->>Auth: OAuth2/OIDC login (id_token present)
    activate Auth
    Auth->>API: ensure `idp_claims` property exists (GET/POST)
    API->>Props: create or verify property
    Auth->>API: PATCH users/{userId}/properties with filtered idp_claims JSON
    deactivate Auth

    Note over TokenGen,API: On each token generation
    TokenGen->>API: GET users/{userId}/properties
    API->>Props: return properties (including `idp_claims`)
    TokenGen->>TokenGen: parse `idp_claims` JSON
    TokenGen->>Tokens: inject claims as idp\_<claimName> into access & id tokens
    TokenGen-->>User: tokens issued with injected IdP claims

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Files needing extra attention:
  • captureIdpClaimsToTokens/CaptureIdpClaimsWorkflow.ts — claims filtering and property creation flow
  • captureIdpClaimsToTokens/AddIdpClaimsToTokensWorkflow.ts — parsing, claim prefixing, and token binding logic

Possibly related PRs

• feat: adds a workflow for syncing attributes for Entra OAuth2 login #17 — also adds post-auth workflows that extract IdP/OIDC id_token claims and update user properties using the Kinde API.
• feat: add workflow to sync SAML attributes into Kinde user properties #13 — similar work persisting IdP-provided attributes by fetching and PATCHing users/{userId}/properties.
• PR: Add workflow to include billing info in user tokens - B2C case #14 — adds an on-token-generation workflow that injects custom claims into tokens (comparable token-binding and injection patterns).

Suggested reviewers

• DaveOrDead
• onderay

Poem

🐰 I hopped through login, claims in tow,
I stored them safe where user props grow,
Then on token day I stitched with care,
idp_prefixed whispers tucked in there,
A tiny rabbit patching tokens fair.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately and concisely summarizes the main changes: adding two workflows to capture IdP claims and inject them into tokens, which directly aligns with the changeset.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 16d671f and 50552a3.

📒 Files selected for processing (1)

• README.md (2 hunks)

🔇 Additional comments (2)

README.md (2)

29-29: Table entry correctly placed and formatted.

The new endpoint entry follows the established table format and is logically positioned after the related /userTokens endpoint. The description accurately reflects that this is also a token generation workflow.

---

43-43: Example entry is well-documented and properly addresses the contributor request.

The description accurately captures the end-to-end functionality without hardcoding claim names, and the link follows the established pattern of referencing the primary workflow file. The placement among other examples is consistent and logical.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

postUserAuthentication/IdpTokenWorkflow.ts (1)

1-7: Remove unused import.

The idTokenCustomClaims import is not used anywhere in the code. Consider removing it to keep the imports clean.

Apply this diff:

 import {
   onPostAuthenticationEvent,
   WorkflowSettings,
   WorkflowTrigger,
   accessTokenCustomClaims,
-  idTokenCustomClaims,
 } from "@kinde/infrastructure";

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 20c2783 and 88701bf.

📒 Files selected for processing (1)

• postUserAuthentication/IdpTokenWorkflow.ts (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-06-19T06:39:44.342Z

Learnt from: ages96
Repo: kinde-starter-kits/workflow-examples PR: 6
File: postUserAuthentication/impossibleTravelWorkflow.ts:0-0
Timestamp: 2025-06-19T06:39:44.342Z
Learning: In Kinde's postUserAuthentication workflows, after the OTP authentication step, event.context.user consistently returns null for fields like name and email, with only the user ID being available. Therefore, kindeAPI.get() is required to retrieve the full user details including name and email fields.

Applied to files:

• postUserAuthentication/IdpTokenWorkflow.ts

🔇 Additional comments (1)

postUserAuthentication/IdpTokenWorkflow.ts (1)

61-94: LGTM!

The implementation is well-structured with proper defensive checks:

• Validates OAuth2 protocol before processing
• Guards against missing ID token claims
• Clear early returns prevent unnecessary execution
• Type definitions are explicit and the email extraction logic is straightforward

The extensive inline comments make it easy for future developers to extend this workflow with additional claims.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 88701bf and 16d671f.

📒 Files selected for processing (2)

• captureIdpClaimsToTokens/AddIdpClaimsToTokensWorkflow.ts (1 hunks)
• captureIdpClaimsToTokens/CaptureIdpClaimsWorkflow.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

captureIdpClaimsToTokens/AddIdpClaimsToTokensWorkflow.ts (1)

captureIdpClaimsToTokens/CaptureIdpClaimsWorkflow.ts (1)

• workflowSettings (48-59)

captureIdpClaimsToTokens/CaptureIdpClaimsWorkflow.ts (1)

captureIdpClaimsToTokens/AddIdpClaimsToTokensWorkflow.ts (1)

• workflowSettings (52-67)

[pesickaa]

@Koosha-Owji it would be nice if you also updated the readme to include these new examples.