From b4e205c6014d649e4901e3514859d5e5674bb1c7 Mon Sep 17 00:00:00 2001
From: Rajat Singh <17253992+rajatcing@users.noreply.github.com>
Date: Wed, 1 Jul 2026 14:35:06 +0200
Subject: [PATCH] docs: add IdP claim mapping troubleshooting to Actions V2
 response manipulation guide (#12339)

# Which Problems Are Solved

- The documentation had no guidance for debugging auto-user-creation
failures caused by unexpected or missing claims from an external IdP,
leaving users without a path forward when they see a
`SetHumanProfile.GivenName` validation error during OIDC login.

# How the Problems Are Solved

- Adds a troubleshooting section to the Actions V2 response manipulation
guide explaining how to use the `RetrieveIdentityProviderIntent` webhook
to inspect `rawInformation` and identify claim key mismatches from the
external IdP.

# Additional Changes

- None

Signed-off-by: Rajat Singh <rajat@zitadel.com>
Co-authored-by: Rajat Singh <rajat@zitadel.com>
---
 .../actions/testing-response-manipulation.mdx   | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/apps/docs/content/guides/integrate/actions/testing-response-manipulation.mdx b/apps/docs/content/guides/integrate/actions/testing-response-manipulation.mdx
index 358c51128..30d4b026c 100644
--- a/apps/docs/content/guides/integrate/actions/testing-response-manipulation.mdx
+++ b/apps/docs/content/guides/integrate/actions/testing-response-manipulation.mdx
@@ -292,6 +292,23 @@ the [Sent information Response](./usage#sent-information-response) payload descr
 }
 ```
 
+## Debugging claim mapping issues with external IdPs
+
+The same `RetrieveIdentityProviderIntent` webhook is useful for diagnosing auto-user-creation failures caused by unexpected or missing claims from an external IdP.
+
+A common symptom is an error like:
+
+```
+invalid AddHumanUserRequest.Profile: embedded message failed validation |
+caused by: invalid SetHumanProfile.GivenName: value length must be between 1 and 200 runes, inclusive
+```
+
+This means ZITADEL received an empty value for `givenName` during auto-creation. The IdP may be sending the claim under a different key than ZITADEL expects (e.g. `Givenname`, `firstname`, or a provider-specific claim name).
+
+**To inspect the raw claims ZITADEL receives from your IdP**, point the execution at a logging endpoint (such as [Webhook.site](./webhook-site-setup)) instead of a manipulation handler. Trigger a login with the external IdP and look at the `rawInformation` field in the payload — this contains the unmodified claims exactly as ZITADEL received them.
+
+Compare the claim keys in `rawInformation` against what ZITADEL maps to standard profile fields. If the IdP uses a non-standard key, you can remap it in the same webhook by setting `addHumanUser.profile.givenName` from the correct source field before returning the response.
+
 ## Conclusion
 
 You have successfully set up a target and execution to manipulate API responses in your ZITADEL instance.