From f773fdb01bfdad98e6aba342863df559808cb45e Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Mon, 10 Jul 2023 11:43:06 +0200
Subject: [PATCH 1/2] docs: explain default claims mapping

Closes https://github.com/ory-corp/cloud/issues/4857
---
 docs/oauth2-oidc/claims-scope.mdx | 40 +++++++++++++++++++++++++++++++
 src/sidebar.js                    |  1 +
 2 files changed, 41 insertions(+)
 create mode 100644 docs/oauth2-oidc/claims-scope.mdx

diff --git a/docs/oauth2-oidc/claims-scope.mdx b/docs/oauth2-oidc/claims-scope.mdx
new file mode 100644
index 000000000..a92746408
--- /dev/null
+++ b/docs/oauth2-oidc/claims-scope.mdx
@@ -0,0 +1,40 @@
+---
+id: claims-scope
+slug: openid-connect-claims-scope-custom
+title: Customize OpenID Connect scope and claims
+sidebar_label: Scope and claims customization
+---
+
+Let's talk about how OpenID Connect scope and claims work with Ory OAuth2 and OpenID Connect. We'll also cover the default setup
+of Ory, which uses Ory Identities for logging in and the Ory Account Experience for getting user consent. This setup supports the
+`email` and `profile` OpenID Connect scopes.
+
+## The default setup of Ory OAuth2 and OpenID Connect
+
+By default, Ory OAuth2 and OpenID Connect use Ory Identities to handle login. It also uses the Ory Account Experience to ask for
+user consent. This setup supports the `email` and `profile` scopes as defined by OpenID Connect.
+
+### How the `email` scope works
+
+For the `email` scope, the system uses the verifiable addresses of a user. The first verifiable email is used to include the email
+in the ID token claims. This means that both `email_verified` and `email` claims get set.
+
+### How the `profile` scope works
+
+For the `profile` scope, the system uses traits associated with a user. Here's how they map:
+
+- `identity.traits.username` is used for the `username` claim.
+- `identity.traits.website` is used for the `website` claim.
+- `identity.updated_at` is used for the `updated_at` claim.
+
+Also, the name field can be a string or an object:
+
+- If `identity.traits.name` is a string, it is used for the `name` claim.
+- If `identity.traits.name` is an object, `traits.name.first` and `traits.name.last` are used for the `given_name` and
+  `family_name` traits.
+
+## Making Custom Scopes and Claims
+
+Ory allows you to customize scopes and claims. To do this, you can set up a custom consent UI. This way, you can adjust your
+identity management process to fit your needs. For more information, check out our
+[Ory Consent UI Documentation](./custom-login-consent/flow.mdx).
diff --git a/src/sidebar.js b/src/sidebar.js
index ea304a2ae..df50b935f 100644
--- a/src/sidebar.js
+++ b/src/sidebar.js
@@ -208,6 +208,7 @@ module.exports = {
         "hydra/guides/oauth2-token-introspection",
         "hydra/guides/client-token-expiration",
         "oauth2-oidc/userinfo-oidc",
+        "oauth2-oidc/claims-scope",
         "hydra/jwks",
         "hydra/guides/openid",
         "hydra/guides/audiences",

From f6a55d330c18554a6ee68a905f2f9bc6148bf889 Mon Sep 17 00:00:00 2001
From: Vincent Kraus <mail@vinckr.com>
Date: Mon, 10 Jul 2023 12:06:35 +0200
Subject: [PATCH 2/2] docs: avoid we

---
 docs/oauth2-oidc/claims-scope.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/oauth2-oidc/claims-scope.mdx b/docs/oauth2-oidc/claims-scope.mdx
index a92746408..f9f37b251 100644
--- a/docs/oauth2-oidc/claims-scope.mdx
+++ b/docs/oauth2-oidc/claims-scope.mdx
@@ -5,9 +5,9 @@ title: Customize OpenID Connect scope and claims
 sidebar_label: Scope and claims customization
 ---
 
-Let's talk about how OpenID Connect scope and claims work with Ory OAuth2 and OpenID Connect. We'll also cover the default setup
-of Ory, which uses Ory Identities for logging in and the Ory Account Experience for getting user consent. This setup supports the
-`email` and `profile` OpenID Connect scopes.
+In this document you will learn how OpenID Connect scope and claims work with Ory OAuth2 and OpenID Connect. It will also cover
+the default setup of Ory, which uses Ory Identities for logging in and the Ory Account Experience for getting user consent. This
+setup supports the `email` and `profile` OpenID Connect scopes.
 
 ## The default setup of Ory OAuth2 and OpenID Connect
 
@@ -36,5 +36,5 @@ Also, the name field can be a string or an object:
 ## Making Custom Scopes and Claims
 
 Ory allows you to customize scopes and claims. To do this, you can set up a custom consent UI. This way, you can adjust your
-identity management process to fit your needs. For more information, check out our
+identity management process to fit your needs. For more information, check out the
 [Ory Consent UI Documentation](./custom-login-consent/flow.mdx).