From 39318be2dc36c9f6c409047410dd46f505ac7cde Mon Sep 17 00:00:00 2001 From: vinckr Date: Wed, 16 Apr 2025 16:20:34 -0300 Subject: [PATCH] docs: claims mapping debug + move old oidc troubleshooting doc --- .../01_oidc-redirect-url-cname.mdx | 42 ------- docs/troubleshooting/25_social-sign-in.mdx | 112 +++++++++++++----- vercel.json | 4 + 3 files changed, 87 insertions(+), 71 deletions(-) delete mode 100644 docs/troubleshooting/01_oidc-redirect-url-cname.mdx diff --git a/docs/troubleshooting/01_oidc-redirect-url-cname.mdx b/docs/troubleshooting/01_oidc-redirect-url-cname.mdx deleted file mode 100644 index 327937a40..000000000 --- a/docs/troubleshooting/01_oidc-redirect-url-cname.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: oidc-redirect-url-cname-OTA-092022-01 -title: Social sign-in `redirect_uri_mismatch` error (OTA-092022-01) ---- - -This problem affects projects created before September 2022 that use a custom domain. For newly added social sign-in providers, -social sign-in flows can fail with the following message: - -```text -Unable to complete OpenID Connect flow because the OpenID Provider returned error "redirect_uri_mismatch": The redirect_uri MUST match the registered callback URL for this application. -``` - -:::info - -If you get this error in projects created after September 2022, read [Social sign-in troubleshooting](./25_social-sign-in.mdx) for -more information. - -::: - -## Mitigation - -To fix the problem, remove the `/selfservice/methods/oidc/config/base_redirect_uri` configuration entry. Run this Ory CLI command: - -```shell -## List all available workspaces -ory list workspaces - -## List all available projects -ory list projects --workspace - -## Remove the configuration entry -ory patch identity-config \ - --remove '/selfservice/methods/oidc/config/base_redirect_uri' -``` - -:::caution - -Removing the `base_redirect_uri` can break previously existing and functional social sign-in connections. To fix a broken -connection, choose the provider you want to fix from the section and copy the -redirect URI. Use the value you copied to update the callback URL configuration of the social sign-in provider. - -::: diff --git a/docs/troubleshooting/25_social-sign-in.mdx b/docs/troubleshooting/25_social-sign-in.mdx index 4c239f4b7..d1a4b4529 100644 --- a/docs/troubleshooting/25_social-sign-in.mdx +++ b/docs/troubleshooting/25_social-sign-in.mdx @@ -6,23 +6,63 @@ sidebar_label: Social sign-in troubleshooting # Social sign-in troubleshooting -## 'redirect_uri' mismatch +## Redirect loops after registration -Ensure that the `redirect_uri` query parameter in the URL matches the authorized redirect URI added to the social sign-in -provider. +Ory redirects users back to the registration page after a successful OIDC flow when some identity traits, for example a phone +number, couldn't be mapped using the data received from the social sign-in provider and require manual input from the user. -``` -https://{provider}/o/oauth2/v2/auth?client_id=(...)& -redirect_uri=https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/{provider}& -response_type=code&scope=email+profile+openid -``` +However, when the Jsonnet configuration for the social sign-in provider is incorrect and Ory can't map the data correctly, the +user sees no input fields and the registration page gets stuck in a redirect loop. + +To understand how to fix the problem, let's look at how Ory handles the OIDC registration flow. There are 5 steps that the system +performs when users register with a social sign-in provider: -:::info +1. Redirect to the social sign-in provider. +2. Redirect back to Ory with a `code` query parameter. +3. Ory exchanges the `code` for an access token and retrieves the user information. +4. Ory maps the user information to the [Identity Schema traits](../kratos/manage-identities/identity-schema). +5. (optional) Ory redirects back to the registration page, requiring the user to provide the values for the missing traits. -If you get a `redirect_uri` mismatch error in a project created before September 2022 that uses a custom domain, -[refer to this document](./oidc-redirect-url-cname-OTA-092022-01) for troubleshooting information. +When step 4 fails, Ory becomes stuck in a redirect loop. To fix the redirect loop, adjust the Jsonnet configuration for the social +sign-in provider so that the data from the provider gets mapped correctly to the Identity Schema. Read +[Map and merge profile data](../kratos/social-signin/data-mapping) to learn more. + +### Debug Jsonnet claims mapping + +When the registration flow gets stuck in a redirect loop, it's often because the Jsonnet snippet fails to map the incoming claims +from the social sign-in provider to your Identity Schema traits. To debug this, it can help to see the actual claims data Ory +receives from the provider and how it's structured. + +1. To ensure the registration process can complete simplify the `identity.traits` section in your Jsonnet, perhaps only mapping + one non-essential field or even leaving it empty `{}`. +2. To capture the full claims object add a field to `identity.metadata_public`. Or `identity.metadata_admin` if the claims contain + sensitive data you don't want exposed to the user. + +Here's an example of a minimal Jsonnet configuration for debugging purposes: + +```jsonnet +local claims = std.extVar('claims'); +{ + identity: { + traits: { + // Minimal traits mapping - adjust as needed + [if 'email' in claims && claims.email_verified then 'email' else null]: claims.email, + // You might even use traits: {} temporarily if no traits are strictly required + }, + metadata_public: { + // Store all received claims + debug_claims: claims + } + }, +} +``` -::: +1. Apply temporary Jsonnet configuration to your social sign-in provider settings. +2. Attempt the registration flow again with the social provider. The registration should now succeed. +3. Inspect the identity created in Ory. You can use the Ory Console, Ory CLI, or the API. +4. Analyze the `debug_claims`. This shows what data your Jsonnet has access to via the claims variable. +5. Fix your original Jsonnet traits mapping logic so it references only available claims. +6. Once your primary Jsonnet mapping is fixed, remove the temporary `debug_claims` field from the metadata. ## 'oryapis.com' doesn't work as authorized redirect URI @@ -42,28 +82,42 @@ Ensure that the custom domain is added to the social sign-in provider as an auth ::: -## Redirect loops after successful registration +## 'redirect_uri' mismatch -Ory redirects users back to the registration page after a successful OIDC flow when some identity traits, for example a phone -number, couldn't be mapped using the data received from the social sign-in provider and require manual input from the user. +Ensure that the `redirect_uri` query parameter in the URL matches the authorized redirect URI added to the social sign-in +provider. -However, when the Jsonnet configuration for the social sign-in provider is incorrect and Ory can't map the data correctly, the -user sees no input fields and the registration page gets stuck in a redirect loop. +``` +https://{provider}/o/oauth2/v2/auth?client_id=(...)& +redirect_uri=https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/{provider}& +response_type=code&scope=email+profile+openid +``` -To understand how to fix the problem, let's look at how Ory handles the OIDC registration flow. There are 5 steps that the system -performs when users register with a social sign-in provider: +### Social sign-in `redirect_uri_mismatch` error (OTA-092022-01) -1. Redirect to the social sign-in provider. -2. Redirect back to Ory with a `code` query parameter. -3. Ory exchanges the `code` for an access token and retrieves the user information. -4. Ory maps the user information to the [Identity Schema traits](../kratos/manage-identities/identity-schema). -5. (optional) Ory redirects back to the registration page, requiring the user to provide the values for the missing traits. +This affects only projects created before September 2022 that use a custom domain. For newly added social sign-in providers, +social sign-in flows can fail with the following message: -When step 4 fails, Ory becomes stuck in a redirect loop. To fix the redirect loop, adjust the Jsonnet configuration for the social -sign-in provider so that the data from the provider gets mapped correctly to the Identity Schema. +```text +Unable to complete OpenID Connect flow because the OpenID Provider returned error "redirect_uri_mismatch": The redirect_uri MUST match the registered callback URL for this application. +``` -:::tip +#### Mitigation OTA-092022-01 -Read [Map and merge profile data](../kratos/social-signin/data-mapping) to learn more. +To fix the problem, remove the `/selfservice/methods/oidc/config/base_redirect_uri` configuration entry. Run this Ory CLI command: -::: +```shell +## List all available workspaces +ory list workspaces + +## List all available projects +ory list projects --workspace + +## Remove the configuration entry +ory patch identity-config \ + --remove '/selfservice/methods/oidc/config/base_redirect_uri' +``` + +Removing the `base_redirect_uri` can break previously existing and functional social sign-in connections. To fix a broken +connection, choose the provider you want to fix from the section and copy the +redirect URI. Use the value you copied to update the callback URL configuration of the social sign-in provider. diff --git a/vercel.json b/vercel.json index c8b5180d3..795dac661 100644 --- a/vercel.json +++ b/vercel.json @@ -1192,6 +1192,10 @@ { "source": "/docs/guides/master/oathkeeper/1-overview/1-rules", "destination": "/docs/oathkeeper/api-access-rules" + }, + { + "source": "/docs/troubleshooting/oidc-redirect-url-cname-OTA-092022-01", + "destination": "/docs/troubleshooting/troubleshooting-social-sign-in" } ] }