docs: explain that form data is merged with oidc data (#394)

Closes #127
ory · May 6, 2020 · b0dbec4 · b0dbec4
1 parent 647ced3
commit b0dbec4
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 1 deletion.
diff --git a/docs/docs/concepts/credentials/openid-connect-oidc-oauth2.mdx b/docs/docs/concepts/credentials/openid-connect-oidc-oauth2.mdx
@@ -3,6 +3,8 @@ id: openid-connect-oidc-oauth2
 title: Social Sign In, OpenID Connect, and OAuth2
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 The `oidc` method uses OpenID Connect, or OAuth2 where OpenID Connect is not
 supported, to authenticate identities using a third-party identity provider,
 such as Google, Microsoft, GitHub - or any other OAuth2 / OpenID Connect
@@ -245,3 +247,35 @@ type Claims struct {
 	UpdatedAt           int64  `json:"updated_at,omitempty"`
 }
 ```
+
+## Identity Traits Validation and Data Completion
+
+Sometimes the data provided by OpenID Connect or OAuth2 Providers is not enough.
+A common example is asking the user to consent to the terms of service. No
+OpenID Connect or OAuth2 provider will be able to give you this information
+because these are your terms. Another example would be a user not agreeing to
+share his/her email address with you when authorizing your OAuth2 app.
+
+If such a validation error occurs, the user will be redirected to the
+Registration UI. The Registration Request includes all the valid and invalid
+fields:
+
+<img
+  alt="Missing website field in OpenID Connect / OAuth2 provider claims"
+  src={useBaseUrl('img/docs/oidc-missing.png')}
+/>
+
+When submitting the form again, the data provided by the user and the data
+coming from the OpenID Connect / OAuth2 provider will be merged. This process
+repeats itself
+
+<img
+  alt="Invalid website field in OpenID Connect / OAuth2 provider claims"
+  src={useBaseUrl('img/docs/oidc-incomplete.png')}
+/>
+
+until the identity's traits are valid against the defined JSON Schema.
+
+For more information on this flow (network flow, examples, UI, ...) head over to
+the
+[OpenID Connect and OAuth2 Self-Service Strategy Documentation](../../self-service/strategies/openid-connect-social-sign-in-oauth2.md).
diff --git a/docs/docs/debug/csrf.md b/docs/docs/debug/csrf.md
@@ -3,7 +3,7 @@ id: csrf
 title: Common Cookie and CSRF Pitfalls
 ---
 
-import useBaseUrl from '@docusaurus/useBaseUrl';
+import useBaseUrl from '@docusaurus/useBaseUrl'
 
 Because ORY Kratos is not just an API, but instead talks to your users' browsers
 directly, several security measures have been implemented in ORY Kratos. One of

diff --git a/docs/static/img/docs/oidc-incomplete.png b/docs/static/img/docs/oidc-incomplete.png
diff --git a/docs/static/img/docs/oidc-missing.png b/docs/static/img/docs/oidc-missing.png