feat(oidc): claims parameter support (#8081)

This adds formal support for the claims parameter.

Closes #2868

Signed-off-by: James Elliott <james-d-elliott@users.noreply.github.com>

12 files changed, 483 insertions, 150 deletions

diff --git a/docs/content/configuration/definitions/_index.md b/docs/content/configuration/definitions/_index.md
index 156068ab3..0cb428617 100644
--- a/docs/content/configuration/definitions/_index.md
+++ b/docs/content/configuration/definitions/_index.md
@@ -2,7 +2,7 @@
 title: "Definitions"
 description: "Definitions Configuration"
 summary: ""
-date: 2025-02-18T09:38:36+00:00
+date: 2024-11-12T22:08:06+11:00
 draft: false
 images: []
 weight: 198000
diff --git a/docs/content/configuration/definitions/introduction.md b/docs/content/configuration/definitions/introduction.md
index 5ea06d53c..a96b8ce7d 100644
--- a/docs/content/configuration/definitions/introduction.md
+++ b/docs/content/configuration/definitions/introduction.md
@@ -2,7 +2,7 @@
 title: "Definitions"
 description: "Definitions Configuration"
 summary: "Authelia allows configuring reusable definitions."
-date: 2025-02-18T09:38:36+00:00
+date: 2024-11-12T22:08:06+11:00
 draft: false
 images: []
 weight: 199100
diff --git a/docs/content/configuration/definitions/network.md b/docs/content/configuration/definitions/network.md
index 5c203340b..224824342 100644
--- a/docs/content/configuration/definitions/network.md
+++ b/docs/content/configuration/definitions/network.md
@@ -2,7 +2,7 @@
 title: "Network"
 description: "Network Definitions Configuration"
 summary: "Authelia allows configuring reusable network definitions."
-date: 2025-02-18T09:38:36+00:00
+date: 2024-11-12T22:08:06+11:00
 draft: false
 images: []
 weight: 199100
diff --git a/docs/content/configuration/definitions/user-attributes.md b/docs/content/configuration/definitions/user-attributes.md
index e64f515e5..c9aeaf06a 100644
--- a/docs/content/configuration/definitions/user-attributes.md
+++ b/docs/content/configuration/definitions/user-attributes.md
@@ -2,7 +2,7 @@
 title: "User Attributes"
 description: "User Attributes Definitions Configuration"
 summary: "Authelia allows configuring reusable user attribute definitions."
-date: 2025-02-22T16:18:09+11:00
+date: 2024-11-12T22:11:32+11:00
 draft: false
 images: []
 weight: 199100
@@ -17,7 +17,7 @@ seo:
 The user attributes section allows you to define custom attributes for your users using Common Expression Language (CEL).
 These attributes can be used at the current time to:
 
-- Enhance OpenID Connect claims with dynamic values
+- Enhance [OpenID Connect 1.0 claims](../../integration/openid-connect/openid-connect-1.0-claims.md) with dynamic values
 
 ## Configuration
 
diff --git a/docs/content/configuration/identity-providers/openid-connect/clients.md b/docs/content/configuration/identity-providers/openid-connect/clients.md
index 3a853c863..df9a43233 100644
--- a/docs/content/configuration/identity-providers/openid-connect/clients.md
+++ b/docs/content/configuration/identity-providers/openid-connect/clients.md
@@ -64,6 +64,7 @@ identity_providers:
           - 'fragment'
         authorization_policy: 'two_factor'
         lifespan: ''
+        claims_policy: ''
         requested_audience_mode: 'explicit'
         consent_mode: 'explicit'
         pre_configured_consent_duration: '1 week'
@@ -329,6 +330,13 @@ identity_providers:
 The name of the custom lifespan that this client uses. A custom lifespan is named and configured globally via the
 [custom](provider.md#custom) section within [lifespans](provider.md#lifespans).
 
+### claims_policy
+
+{{< confkey type="string" default="" required="no" >}}
+
+The name of the claims policy that this client uses. A claims policy is named and configured globally via the
+[claims_policies](provider.md#claims_policies) for the OpenID Connect 1.0 Provider.
+
 ### requested_audience_mode
 
 {{< confkey type="string" default="explicit" required="no" >}}
diff --git a/docs/content/configuration/identity-providers/openid-connect/provider.md b/docs/content/configuration/identity-providers/openid-connect/provider.md
index 7d6d4068b..e1752d9cb 100644
--- a/docs/content/configuration/identity-providers/openid-connect/provider.md
+++ b/docs/content/configuration/identity-providers/openid-connect/provider.md
@@ -84,6 +84,16 @@ identity_providers:
       authorize_code: '1m'
       id_token: '1h'
       refresh_token: '90m'
+    claims_policies:
+      policy_name:
+        id_token: []
+        access_token: []
+        custom_claims:
+          claim_name:
+            attribute: 'attribute_name'
+    scopes:
+      scope_name:
+        claims: []
     cors:
       endpoints:
         - 'authorization'
@@ -554,6 +564,64 @@ identity_providers:
               refresh_token: '90m'
 ```
 
+### claims_policies
+
+{{< confkey type="string" syntax="dictionary" common="dictionary-reference" required="no" >}}
+
+The claims policies are policies which allow customizing the behaviour of claims and the available claims for a
+particular client.
+
+The keys under `claims_policies` is an arbitrary value that can be used in the
+[OpenID Connect 1.0 Client](clients.md#claims_policy) as the [claims_policy](clients.md#claims_policy) value.
+
+#### id_token
+
+{{< confkey type="list(string)" required="no" >}}
+
+The list of claims automatically copied to the ID Token in addition to the standard ID Token claims provided the
+relevant scope was granted.
+
+#### access_token
+
+{{< confkey type="list(string)" required="no" >}}
+
+The list of claims automatically copied to the Access Token in addition to the standard JWT Profile claims provided the
+relevant scope was granted.
+
+#### custom_claims
+
+{{< confkey type="string" syntax="dictionary" common="dictionary-reference" required="no" >}}
+
+The list of claims available in this policy in addition to the standard claims. These claims are anchored to attributes
+which can either be concrete attributes from the [first factor](../../first-factor/introduction.md) backend or can be
+those defined via [definitions](../../definitions/user-attributes.md).
+
+The keys under `custom_claims` are arbitrary values which are the names of the claims.
+
+##### attribute
+
+{{< confkey type="string" required="no" >}}
+
+The attribute name that this claim returns. By default it's the same as the claim name.
+
+### scopes
+
+{{< confkey type="string" syntax="dictionary" common="dictionary-reference" required="no" >}}
+
+A list of scope definitions available in addition to the standard ones.
+
+The keys under `scopes` are arbitrary values which are the names of the scopes.
+
+#### claims
+
+{{< confkey type="list(string)" required="no" >}}
+
+The claims to be available to this scope.
+
+If the scope is configured in a [OpenID Connect 1.0 Client](clients.md#scopes) in the [scopes](clients.md#scopes) then
+every claim available in this list must either be a Standard Claim or must be fulfilled by the
+[claims_policy](clients.md#claims_policy).
+
 ### cors
 
 Some [OpenID Connect 1.0] Endpoints need to allow cross-origin resource sharing; however, some are optional. This section allows
diff --git a/docs/content/integration/openid-connect/expressjs/index.md b/docs/content/integration/openid-connect/expressjs/index.md
index 19a6f0eef..6c25df4d1 100644
--- a/docs/content/integration/openid-connect/expressjs/index.md
+++ b/docs/content/integration/openid-connect/expressjs/index.md
@@ -118,9 +118,11 @@ app.get('/', requiresAuth(), (req, res) => {
         accessToken: req.oidc.accessToken,
         refreshToken: req.oidc.refreshToken,
         idToken: req.oidc.idToken,
-        claims: req.oidc.idTokenClaims,
+        claims: {
+          id_token: req.oidc.idToken,
+          userinfo: userInfo,
+        },
         scopes: req.oidc.scope,
-        userInfo,
       }, null, 2);
 
     res.send(`<html lang='en'><body><pre><code>${data}</code></pre></body></html>`);
diff --git a/docs/content/integration/openid-connect/introduction.md b/docs/content/integration/openid-connect/introduction.md
index eb5807080..27f655fda 100644
--- a/docs/content/integration/openid-connect/introduction.md
+++ b/docs/content/integration/openid-connect/introduction.md
@@ -52,106 +52,6 @@ the Authorization Flow.
 For more information about the opaque [Access Token] default see
 [Why isn't the Access Token a JSON Web Token? (Frequently Asked Questions)](./frequently-asked-questions.md#why-isnt-the-access-token-a-json-web-token).
 
-## Scope Definitions
-
-The following scope definitions describe each scope supported and the associated effects including the individual claims
-returned by granting this scope. By default, we do not issue any claims which reveal the users identity which allows
-administrators semi-granular control over which claims the client is entitled to.
-
-### openid
-
-This is the default scope for [OpenID Connect 1.0]. This field is forced on every client by the configuration validation
-that Authelia does.
-
-{{< callout context="caution" title="Important Note" icon="outline/alert-triangle" >}}
-The combination of the issuer (i.e. `iss`) [Claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) and
-subject (i.e. `sub`) [Claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) are utilized to uniquely
-identify a
-user and per the specification the only reliable way to do so as they are guaranteed to be a unique combination. As such
-this is the supported method for linking an account to Authelia. The `preferred_username` and `email` claims from the
-`profile` and `email` scopes respectively should only be utilized for provisioning a new account.
-
-In addition, the `sub` [Claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) utilizes
-a [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122) UUID V4 to identify the individual user as per the
-[Subject Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) section of
-the [OpenID Connect 1.0](https://openid.net/connect/) specification.
-{{< /callout >}}
-
-|  [Claim]  |   JWT Type    | Authelia Attribute |                         Description                         |
-|:---------:|:-------------:|:------------------:|:-----------------------------------------------------------:|
-|    iss    |    string     |      hostname      |             The issuer name, determined by URL              |
-|    jti    | string(uuid)  |       *N/A*        |     A [RFC4122] UUID V4 representing the JWT Identifier     |
-|    rat    |    number     |       *N/A*        |            The time when the token was requested            |
-|    exp    |    number     |       *N/A*        |                           Expires                           |
-|    iat    |    number     |       *N/A*        |             The time when the token was issued              |
-| auth_time |    number     |       *N/A*        |        The time the user authenticated with Authelia        |
-|    sub    | string(uuid)  |     opaque id      |    A [RFC4122] UUID V4 linked to the user who logged in     |
-|   scope   |    string     |       scopes       |              Granted scopes (space delimited)               |
-|    scp    | array[string] |       scopes       |                       Granted scopes                        |
-|    aud    | array[string] |       *N/A*        |                          Audience                           |
-|    amr    | array[string] |       *N/A*        | An [RFC8176] list of authentication method reference values |
-|    azp    |    string     |    id (client)     |                    The authorized party                     |
-| client_id |    string     |    id (client)     |                        The client id                        |
-
-### offline_access
-
-This scope is a special scope designed to allow applications to obtain a [Refresh Token] which allows extended access to
-an application on behalf of a user. A [Refresh Token] is a special [Access Token] that allows refreshing previously
-issued token credentials, effectively it allows the Relying Party to obtain new tokens periodically.
-
-As per [OpenID Connect 1.0] Section 11 [Offline Access] can only be granted during the [Authorization Code Flow] or a
-[Hybrid Flow]. The [Refresh Token] will only ever be returned at the [Token Endpoint] when the client is exchanging
-their [OAuth 2.0 Authorization Code].
-
-Generally unless an application supports this and actively requests this scope they should not be granted this scope via
-the client configuration.
-
-It is also important to note that we treat a [Refresh Token] as single use and reissue a new [Refresh Token] during the
-refresh flow.
-
-### groups
-
-This scope includes the groups the authentication backend reports the user is a member of in the [Claims] of the
-[ID Token].
-
-| [Claim] |   JWT Type    | Authelia Attribute |                                               Description                                               |
-|:-------:|:-------------:|:------------------:|:-------------------------------------------------------------------------------------------------------:|
-| groups  | array[string] |       groups       | List of user's groups discovered via [authentication](../../configuration/first-factor/introduction.md) |
-
-### email
-
-This scope includes the email information the authentication backend reports about the user in the [Claims] of the
-[ID Token].
-
-|     Claim      |   JWT Type    | Authelia Attribute |                        Description                        |
-|:--------------:|:-------------:|:------------------:|:---------------------------------------------------------:|
-|     email      |    string     |      email[0]      |       The first email address in the list of emails       |
-| email_verified |     bool      |       *N/A*        | If the email is verified, assumed true for the time being |
-|   alt_emails   | array[string] |     email[1:]      |  All email addresses that are not in the email JWT field  |
-
-### profile
-
-This scope includes the profile information the authentication backend reports about the user in the [Claims] of the
-[ID Token].
-
-|       Claim        | JWT Type | Authelia Attribute |               Description                |
-|:------------------:|:--------:|:------------------:|:----------------------------------------:|
-| preferred_username |  string  |      username      | The username the user used to login with |
-|        name        |  string  |    display_name    |          The users display name          |
-
-### Special Scopes
-
-The following scopes represent special permissions granted to a specific token.
-
-#### authelia.bearer.authz
-
-This scope allows the granted access token to be utilized with the bearer authorization scheme on endpoints protected
-via Authelia.
-
-The specifics about this scope are discussed in the
-[OAuth 2.0 Bearer Token Usage for Authorization Endpoints](oauth-2.0-bearer-token-usage.md#authorization-endpoints)
-guide.
-
 ## Signing and Encryption Algorithms
 
 [OpenID Connect 1.0] and OAuth 2.0 support a wide variety of signature and encryption algorithms. Authelia supports
@@ -177,21 +77,21 @@ Authelia's response objects can have the following signature algorithms:
 
 Authelia accepts a wide variety of request object types. The below table describes these request objects.
 
-| Algorithm |      Key Type      | Hashing Algorithm |    Use    |                       Notes                        |
-|:---------:|:------------------:|:-----------------:|:---------:|:--------------------------------------------------:|
-|   none    |        None        |       None        |    N/A    |                        N/A                         |
-|   HS256   | HMAC Shared Secret |      SHA-256      | Signature | [Client Authentication Method] `client_secret_jwt` |
-|   HS384   | HMAC Shared Secret |      SHA-384      | Signature | [Client Authentication Method] `client_secret_jwt` |
-|   HS512   | HMAC Shared Secret |      SHA-512      | Signature | [Client Authentication Method] `client_secret_jwt` |
-|   RS256   |        RSA         |      SHA-256      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   RS384   |        RSA         |      SHA-384      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   RS512   |        RSA         |      SHA-512      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   ES256   |    ECDSA P-256     |      SHA-256      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   ES384   |    ECDSA P-384     |      SHA-384      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   ES512   |    ECDSA P-521     |      SHA-512      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   PS256   |     RSA (MFG1)     |      SHA-256      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   PS384   |     RSA (MFG1)     |      SHA-384      | Signature |  [Client Authentication Method] `private_key_jwt`  |
-|   PS512   |     RSA (MFG1)     |      SHA-512      | Signature |  [Client Authentication Method] `private_key_jwt`  |
+| Algorithm |      Key Type      | Hashing Algorithm |    Use    | [Client Authentication Method] |
+|:---------:|:------------------:|:-----------------:|:---------:|:------------------------------:|
+|   none    |        None        |       None        |    N/A    |              N/A               |
+|   HS256   | HMAC Shared Secret |      SHA-256      | Signature |      `client_secret_jwt`       |
+|   HS384   | HMAC Shared Secret |      SHA-384      | Signature |      `client_secret_jwt`       |
+|   HS512   | HMAC Shared Secret |      SHA-512      | Signature |      `client_secret_jwt`       |
+|   RS256   |        RSA         |      SHA-256      | Signature |       `private_key_jwt`        |
+|   RS384   |        RSA         |      SHA-384      | Signature |       `private_key_jwt`        |
+|   RS512   |        RSA         |      SHA-512      | Signature |       `private_key_jwt`        |
+|   ES256   |    ECDSA P-256     |      SHA-256      | Signature |       `private_key_jwt`        |
+|   ES384   |    ECDSA P-384     |      SHA-384      | Signature |       `private_key_jwt`        |
+|   ES512   |    ECDSA P-521     |      SHA-512      | Signature |       `private_key_jwt`        |
+|   PS256   |     RSA (MGF1)     |      SHA-256      | Signature |       `private_key_jwt`        |
+|   PS384   |     RSA (MGF1)     |      SHA-384      | Signature |       `private_key_jwt`        |
+|   PS512   |     RSA (MGF1)     |      SHA-512      | Signature |       `private_key_jwt`        |
 
 [Client Authentication Method]: #client-authentication-method
 
@@ -303,31 +203,6 @@ Per the [RFC7523 Section 3: JWT Format and Processing Requirements](https://data
 this claim must be compared using [RFC3987 Section 6.2.1: Simple String Comparison] and to assist with making this
 predictable for implementers we ensure the comparison is done against the lowercase form of this URL.
 
-## Authentication Method References
-
-Authelia currently supports adding the `amr` [Claim] to the [ID Token] utilizing the [RFC8176] Authentication Method
-Reference values.
-
-The values this [Claim] has, are not strictly defined by the [OpenID Connect 1.0] specification. As such, some backends
-may
-expect a specification other than [RFC8176] for this purpose. If you have such an application and wish for us to support
-it then you're encouraged to create a [feature request](https://www.authelia.com/l/fr).
-
-Below is a list of the potential values we place in the [Claim] and their meaning:
-
-| Value |                            Description                            | Factor | Channel  |
-|:-----:|:-----------------------------------------------------------------:|:------:|:--------:|
-|  mfa  |      User used multiple factors to login (see factor column)      |  N/A   |   N/A    |
-|  mca  |     User used multiple channels to login (see channel column)     |  N/A   |   N/A    |
-| user  |  User confirmed they were present when using their hardware key   |  N/A   |   N/A    |
-|  pin  | User confirmed they are the owner of the hardware key with a pin  |  N/A   |   N/A    |
-|  pwd  |            User used a username and password to login             |  Know  | Browser  |
-|  otp  |                      User used TOTP to login                      |  Have  | Browser  |
-|  pop  | User used a software or hardware proof-of-possession key to login |  Have  | Browser  |
-|  hwk  |       User used a hardware proof-of-possession key to login       |  Have  | Browser  |
-|  swk  |       User used a software proof-of-possession key to login       |  Have  | Browser  |
-|  sms  |                      User used Duo to login                       |  Have  | External |
-
 ## Introspection Signing Algorithm
 
 The following table describes the response from the [Introspection] endpoint depending on the
@@ -521,7 +396,6 @@ The advantages of this approach are as follows:
 
 [RFC4122]: https://datatracker.ietf.org/doc/html/rfc4122
 [RFC7636]: https://datatracker.ietf.org/doc/html/rfc7636
-[RFC8176]: https://datatracker.ietf.org/doc/html/rfc8176
 [RFC9126]: https://datatracker.ietf.org/doc/html/rfc9126
 [RFC7519]: https://datatracker.ietf.org/doc/html/rfc7519
 [RFC9068]: https://datatracker.ietf.org/doc/html/rfc9068
diff --git a/docs/content/integration/openid-connect/nextcloud/index.md b/docs/content/integration/openid-connect/nextcloud/index.md
index 773971f36..0eb2dd29e 100644
--- a/docs/content/integration/openid-connect/nextcloud/index.md
+++ b/docs/content/integration/openid-connect/nextcloud/index.md
@@ -109,7 +109,7 @@ $CONFIG = array (
     'oidc_login_end_session_redirect' => false,
     'oidc_login_button_text' => 'Log in with Authelia',
     'oidc_login_hide_password_form' => false,
-    'oidc_login_use_id_token' => true,
+    'oidc_login_use_id_token' => false,
     'oidc_login_attributes' => array (
         'id' => 'preferred_username',
         'name' => 'name',
diff --git a/docs/content/integration/openid-connect/openid-connect-1.0-claims.md b/docs/content/integration/openid-connect/openid-connect-1.0-claims.md
new file mode 100644
index 000000000..2f3d8a1ec
--- /dev/null
+++ b/docs/content/integration/openid-connect/openid-connect-1.0-claims.md
@@ -0,0 +1,297 @@
+---
+title: "OpenID Connect 1.0 Claims"
+description: "An introduction into utilizing the Authelia OpenID Connect 1.0 Claims functionality"
+summary: "An introduction into utilizing the Authelia OpenID Connect 1.0 Claims functionality."
+date: 2024-03-05T19:11:16+10:00
+draft: false
+images: []
+weight: 611
+toc: true
+seo:
+  title: "" # custom title (optional)
+  description: "" # custom description (recommended)
+  canonical: "" # custom canonical URL (optional)
+  noindex: false # false (default) or true
+---
+
+## Claims
+
+The [OAuth 2.0] and [OpenID Connect 1.0] effectively names the individual content of a token as a [Claim]. Each [Claim]
+can either be granted individually via:
+
+1. The requested and granted [Scope] which generally makes the associated [Claim] values available at the [UserInfo]
+   endpoint, **_not_** within the [ID Token].
+2. The [Claims Parameter] which can request the authorization server explicitly
+   include a [Claim] in the [ID Token] and/or [UserInfo] endpoint.
+
+Authelia supports several claims related features:
+
+1. The availability of the [Standard Claims] using the appropriate [scopes](#scope-definitions):
+   * These claims come from the standard attributes available in the authentication backends, usually with the attribute
+   of the same name.
+2. The availability of creating your own [custom claims](#custom-claims) and [custom scopes](#custom-scopes).
+3. The ability to create [Custom Attributes] to bolster the [custom claims](#custom-claims) functionality.
+4. The ability to request individual claims by clients with the [Claims Parameter] assuming the client is allowed to
+   request the specified claim.
+
+Because Authelia supports the [Claims Parameter] the [ID Token] only returns claims in a way that is privacy and
+security focused, resulting in a minimal [ID Token] which solely proves authorization occurred. This allows various
+flows which require the relying party to share the [ID Token] with another party to prove they have been authorized, and
+relies on the [Access Token] which should be kept completely private to request the additional granted claims from the
+[UserInfo] endpoint.
+
+The [Scope Definitions] indicate the default locations for a specific claim depending on the granted [Scope] when the
+[Claims Parameter] is not used and the default behaviour is not overridden by the registered client configuration.
+
+[Scope Definitions]: #scope-definitions
+[Scope]: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims
+[Claims Parameter]: https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter
+
+### Authentication Method References
+
+Authelia currently supports adding the `amr` [Claim] to the [ID Token] utilizing the [RFC8176] Authentication Method
+Reference values.
+
+The values this [Claim] has, are not strictly defined by the [OpenID Connect 1.0] specification. As such, some backends
+may
+expect a specification other than [RFC8176] for this purpose. If you have such an application and wish for us to support
+it then you're encouraged to create a [feature request](https://www.authelia.com/l/fr).
+
+Below is a list of the potential values we place in the [Claim] and their meaning:
+
+| Value |                            Description                            | Factor | Channel  |
+|:-----:|:-----------------------------------------------------------------:|:------:|:--------:|
+|  mfa  |      User used multiple factors to login (see factor column)      |  N/A   |   N/A    |
+|  mca  |     User used multiple channels to login (see channel column)     |  N/A   |   N/A    |
+| user  |  User confirmed they were present when using their hardware key   |  N/A   |   N/A    |
+|  pin  | User confirmed they are the owner of the hardware key with a pin  |  N/A   |   N/A    |
+|  pwd  |            User used a username and password to login             |  Know  | Browser  |
+|  otp  |                      User used TOTP to login                      |  Have  | Browser  |
+|  pop  | User used a software or hardware proof-of-possession key to login |  Have  | Browser  |
+|  hwk  |       User used a hardware proof-of-possession key to login       |  Have  | Browser  |
+|  swk  |       User used a software proof-of-possession key to login       |  Have  | Browser  |
+|  sms  |                      User used Duo to login                       |  Have  | External |
+
+### Custom Claims
+
+Authelia supports methods to define your own claims. These can either come from [Standard Attributes] or
+[Custom Attributes]. These claims are delivered to provided via a claims policy which describes which claims are
+available to specific scopes.
+
+In the example below we configure a claims policy named `custom_claims_policy` which provides a claim named `claim_name`
+which comes from the attribute named `attribute_name`. The claim `claim_name` is then made available via the scope named
+`scope_name`.
+
+This policy and scope is then configured within the client with client id `client_example_id`. The client can then
+either request the claim via the `claims` parameter or via the `scope` parameter.
+
+```yaml
+identity_providers:
+  oidc:
+    claims_policies:
+      custom_claims_policy:
+        custom_claims:
+          claim_name:
+            attribute: 'attribute_name'
+    scopes:
+      scope_name:
+        claims:
+          - 'claim_name'
+    clients:
+      - client_id: 'client_example_id'
+        claims_policy: 'custom_claims_policy'
+        scopes:
+          - 'scope_name'
+```
+
+### Restore Functionality Prior to Claims Parameter
+
+The introduction of the claims parameter has removed most claims from the [ID Token]. This may not work for some clients
+which do not make requests to the user information endpoint which contains all of these claims, and they may not support
+the claims parameter.
+
+The following example is a claims policy which restores that behaviour for those clients. Users may choose to expand
+on this on their own as they desire. This example also shows how to apply this policy to a client using the
+`claims_policy` option.
+
+We strongly recommend implementers use the standard process for obtaining the extra claims not generally intended to be
+included in the [ID Token] by using the [Access Token] to obtain them from the [UserInfo Endpoint]. This process is
+considered significantly more stable and forms the basis for the future guarantee. This option only exists as a
+break-glass measure and is only offered on a best-effort basis.
+
+```yaml
+identity_providers:
+  oidc:
+    claims_policies:
+      default:
+        id_token: ['groups', 'email', 'email_verified', 'alt_emails', 'preferred_username', 'name']
+    clients:
+      - client_id: 'client_example_id'
+        claims_policy: 'default'
+```
+
+## Scope Definitions
+
+The following scope definitions describe each scope supported and the associated effects including the individual claims
+returned by granting this scope. By default, we do not issue any claims which reveal the users identity which allows
+administrators semi-granular control over which claims the client is entitled to.
+
+### openid
+
+This is the default scope for [OpenID Connect 1.0]. This field is forced on every client by the configuration validation
+that Authelia does.
+
+{{< callout context="caution" title="Important Note" icon="outline/alert-triangle" >}}
+The combination of the issuer (i.e. `iss`) [Claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) and
+subject (i.e. `sub`) [Claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) are utilized to uniquely
+identify a
+user and per the specification the only reliable way to do so as they are guaranteed to be a unique combination. As such
+this is the supported method for linking an account to Authelia. The `preferred_username` and `email` claims from the
+`profile` and `email` scopes respectively should only be utilized for provisioning a new account.
+
+In addition, the `sub` [Claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) utilizes
+a [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122) UUID V4 to identify the individual user as per the
+[Subject Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) section of
+the [OpenID Connect 1.0](https://openid.net/connect/) specification.
+{{< /callout >}}
+
+|  [Claim]  |   JWT Type    | Authelia Attribute | Default Location |                         Description                         |
+|:---------:|:-------------:|:------------------:|:----------------:|:-----------------------------------------------------------:|
+|    iss    |    string     |      hostname      |    [ID Token]    |             The issuer name, determined by URL              |
+|    jti    | string(uuid)  |       *N/A*        |    [ID Token]    |     A [RFC4122] UUID V4 representing the JWT Identifier     |
+|    sub    | string(uuid)  |     opaque id      |    [ID Token]    |    A [RFC4122] UUID V4 linked to the user who logged in     |
+|    aud    | array[string] |       *N/A*        |    [ID Token]    |                          Audience                           |
+|    exp    |    number     |       *N/A*        |    [ID Token]    |                           Expires                           |
+|    iat    |    number     |       *N/A*        |    [ID Token]    |             The time when the token was issued              |
+| auth_time |    number     |       *N/A*        |    [ID Token]    |        The time the user authenticated with Authelia        |
+|    rat    |    number     |       *N/A*        |    [ID Token]    |            The time when the token was requested            |
+|   nonce   |    string     |       *N/A*        |    [ID Token]    |        The time the user authenticated with Authelia        |
+|    amr    | array[string] |       *N/A*        |    [ID Token]    | An [RFC8176] list of authentication method reference values |
+|    azp    |    string     |    id (client)     |    [ID Token]    |                    The authorized party                     |
+|   scope   |    string     |       scopes       |    [UserInfo]    |              Granted scopes (space delimited)               |
+|    scp    | array[string] |       scopes       |    [UserInfo]    |                       Granted scopes                        |
+| client_id |    string     |    id (client)     |    [UserInfo]    |                        The client id                        |
+
+### offline_access
+
+This scope is a special scope designed to allow applications to obtain a [Refresh Token] which allows extended access to
+an application on behalf of a user. A [Refresh Token] is a special [Access Token] that allows refreshing previously
+issued token credentials, effectively it allows the Relying Party to obtain new tokens periodically.
+
+As per [OpenID Connect 1.0] Section 11 [Offline Access] can only be granted during the [Authorization Code Flow] or a
+[Hybrid Flow]. The [Refresh Token] will only ever be returned at the [Token Endpoint] when the client is exchanging
+their [OAuth 2.0 Authorization Code].
+
+Generally unless an application supports this and actively requests this scope they should not be granted this scope via
+the client configuration.
+
+It is also important to note that we treat a [Refresh Token] as single use and reissue a new [Refresh Token] during the
+refresh flow.
+
+### profile
+
+This scope allows the client to access the profile information the authentication backend reports about the user.
+
+|      [Claim]       | JWT Type | Authelia Attribute | Default Location |               Description                |
+|:------------------:|:--------:|:------------------:|:----------------:|:----------------------------------------:|
+|        name        |  string  |    display_name    |    [UserInfo]    |          The users display name          |
+|    family_name     |  string  |    family_name     |    [UserInfo]    |          The users family name           |
+|     given_name     |  string  |     given_name     |    [UserInfo]    |           The users given name           |
+|    	middle_name    |  string  |    	middle_name    |    [UserInfo]    |          The users middle name           |
+|      nickname      |  string  |      nickname      |    [UserInfo]    |            The users nickname            |
+| preferred_username |  string  |      username      |    [UserInfo]    | The username the user used to login with |
+|      profile       |  string  |      profile       |    [UserInfo]    |          The users profile URL           |
+|      picture       |  string  |      picture       |    [UserInfo]    |          The users picture URL           |
+|      website       |  string  |      website       |    [UserInfo]    |          The users website URL           |
+|       gender       |  string  |       gender       |    [UserInfo]    |             The users gender             |
+|     birthdate      |  string  |     birthdate      |    [UserInfo]    |           The users birthdate            |
+|      zoneinfo      |  string  |      zoneinfo      |    [UserInfo]    |            The users zoneinfo            |
+|       locale       |  string  |       locale       |    [UserInfo]    |             The users locale             |
+
+### email
+
+This scope allows the client to access the email information the authentication backend reports about the user.
+
+|    [Claim]     |   JWT Type    | Authelia Attribute | Default Location |                        Description                        |
+|:--------------:|:-------------:|:------------------:|:----------------:|:---------------------------------------------------------:|
+|     email      |    string     |      email[0]      |    [UserInfo]    |       The first email address in the list of emails       |
+| email_verified |     bool      |       *N/A*        |    [UserInfo]    | If the email is verified, assumed true for the time being |
+|   alt_emails   | array[string] |     email[1:]      |    [UserInfo]    |  All email addresses that are not in the email JWT field  |
+
+### address
+
+This scope allows the client to access the address information the authentication backend reports about the user. See
+the [Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) definition for information on
+the format of this claim.
+
+| [Claim] | JWT Type | Authelia Attribute | Default Location |          Description          |
+|:-------:|:--------:|:------------------:|:----------------:|:-----------------------------:|
+| address |  object  |      various       |    [UserInfo]    | The users address information |
+
+The following table indicates the various sub-claims within the address claim.
+
+|    [Claim]     | JWT Type | Authelia Attribute |                       Description                       |
+|:--------------:|:--------:|:------------------:|:-------------------------------------------------------:|
+| street_address |  string  |   street_address   |                The users street address                 |
+|    locality    |  string  |      locality      |             The users locality such as city             |
+|     region     |  string  |       region       | The users region such as state, province, or prefecture |
+|  postal_code   |  string  |    postal_code     |                   The users postcode                    |
+|    country     |  string  |      country       |                    The users country                    |
+
+### phone
+
+This scope allows the client to access the address information the authentication backend reports about the user.
+
+|        [Claim]        | JWT Type |       Authelia Attribute       | Default Location |                                              Description                                              |
+|:---------------------:|:--------:|:------------------------------:|:----------------:|:-----------------------------------------------------------------------------------------------------:|
+|     phone_number      |  string  | phone_number + phone_extension |    [UserInfo]    | The combination of the users phone number and extension in the format specified in OpenID Connect 1.0 |
+| phone_number_verified | boolean  |              N/A               |    [UserInfo]    |                        Currently returns true if the phone number has a value.                        |
+
+### groups
+
+This scope includes the groups the authentication backend reports the user is a member of in the [Claims] of the
+[ID Token].
+
+| [Claim] |   JWT Type    | Authelia Attribute | Default Location |                                               Description                                               |
+|:-------:|:-------------:|:------------------:|:----------------:|:-------------------------------------------------------------------------------------------------------:|
+| groups  | array[string] |       groups       |    [UserInfo]    | List of user's groups discovered via [authentication](../../configuration/first-factor/introduction.md) |
+
+### Special Scopes
+
+The following scopes represent special permissions granted to a specific token.
+
+#### authelia.bearer.authz
+
+This scope allows the granted access token to be utilized with the bearer authorization scheme on endpoints protected
+via Authelia.
+
+The specifics about this scope are discussed in the
+[OAuth 2.0 Bearer Token Usage for Authorization Endpoints](oauth-2.0-bearer-token-usage.md#authorization-endpoints)
+guide.
+
+[OAuth 2.0]: https://oauth.net/2/
+[OpenID Connect 1.0]: https://openid.net/connect/
+
+[ID Token]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken
+[Access Token]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.4
+[Refresh Token]: https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens
+
+[Claims]: https://openid.net/specs/openid-connect-core-1_0.html#Claims
+[Standard Claims]: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
+[Claim]: https://openid.net/specs/openid-connect-core-1_0.html#Claims
+[Offline Access]: https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess
+[UserInfo Endpoint]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
+
+[Standard Attributes]: ../../reference/guides/attributes.md#standard-attributes
+[Custom Attributes]: ../../reference/guides/attributes.md#custom-attributes
+
+[Authorization Code Flow]: https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
+[Hybrid Flow]: https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth
+
+[Token Endpoint]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint
+[UserInfo]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
+
+[RFC4122]: https://datatracker.ietf.org/doc/html/rfc4122
+[RFC8176]: https://datatracker.ietf.org/doc/html/rfc8176
+
+[OAuth 2.0 Authorization Code]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1
diff --git a/docs/data/languages.json b/docs/data/languages.json
index e87aebd9c..e5bc05e1c 100644
--- a/docs/data/languages.json
+++ b/docs/data/languages.json
@@ -8,13 +8,15 @@
     },
     "namespaces": [
         "portal",
-        "settings"
+        "settings",
+        "consent"
     ],
     "languages": [
         {
             "display": "English",
             "locale": "en",
             "namespaces": [
+                "consent",
                 "portal",
                 "settings"
             ],
diff --git a/docs/static/schemas/v4.39/json-schema/configuration.json b/docs/static/schemas/v4.39/json-schema/configuration.json
index 222c83387..24e8968a8 100644
--- a/docs/static/schemas/v4.39/json-schema/configuration.json
+++ b/docs/static/schemas/v4.39/json-schema/configuration.json
@@ -1305,6 +1305,26 @@
           "title": "Lifespans",
           "description": "Token lifespans configuration."
         },
+        "claims_policies": {
+          "patternProperties": {
+            ".*": {
+              "$ref": "#/$defs/IdentityProvidersOpenIDConnectClaimsPolicy"
+            }
+          },
+          "type": "object",
+          "title": "Claims Policies",
+          "description": "The dictionary of claims policies which can be applied to clients."
+        },
+        "scopes": {
+          "patternProperties": {
+            ".*": {
+              "$ref": "#/$defs/IdentityProvidersOpenIDConnectScope"
+            }
+          },
+          "type": "object",
+          "title": "Scopes",
+          "description": "List of custom scopes."
+        },
         "issuer_certificate_chain": {
           "$ref": "#/$defs/X509CertificateChain",
           "title": "Issuer Certificate Chain",
@@ -1362,6 +1382,38 @@
       "type": "object",
       "description": "IdentityProvidersOpenIDConnectCORS represents an OpenID Connect 1.0 CORS config."
     },
+    "IdentityProvidersOpenIDConnectClaimsPolicy": {
+      "properties": {
+        "id_token": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array",
+          "title": "ID Token",
+          "description": "The list of claims to automatically apply to an ID Token in addition to the specified ID Token Claims."
+        },
+        "access_token": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array",
+          "title": "Access Token",
+          "description": "The list of claims to automatically apply to an Access Token in addition to the specified Access Token Claims."
+        },
+        "custom_claims": {
+          "patternProperties": {
+            ".*": {
+              "$ref": "#/$defs/IdentityProvidersOpenIDConnectCustomClaim"
+            }
+          },
+          "type": "object",
+          "title": "Custom Claims",
+          "description": "The custom claims available in this policy in addition to the Standard Claims."
+        }
+      },
+      "additionalProperties": false,
+      "type": "object"
+    },
     "IdentityProvidersOpenIDConnectClient": {
       "properties": {
         "client_id": {
@@ -1489,6 +1541,11 @@
           "title": "Lifespan Name",
           "description": "The name of the custom lifespan to utilize for this client."
         },
+        "claims_policy": {
+          "type": "string",
+          "title": "Claims Policy",
+          "description": "The claims policy to apply to this client."
+        },
         "requested_audience_mode": {
           "type": "string",
           "enum": [
@@ -1749,6 +1806,17 @@
         }
       ]
     },
+    "IdentityProvidersOpenIDConnectCustomClaim": {
+      "properties": {
+        "attribute": {
+          "type": "string",
+          "title": "Attribute",
+          "description": "The attribute that populates this claim."
+        }
+      },
+      "additionalProperties": false,
+      "type": "object"
+    },
     "IdentityProvidersOpenIDConnectLifespan": {
       "properties": {
         "access_token": {
@@ -2060,6 +2128,20 @@
       "type": "object",
       "description": "IdentityProvidersOpenIDConnectPolicyRule configuration for OpenID Connect 1.0 authorization policies rules."
     },
+    "IdentityProvidersOpenIDConnectScope": {
+      "properties": {
+        "claims": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array",
+          "title": "Claims",
+          "description": "The list of claims that this scope includes. When this scope is used by a client the clients claim policy must satisfy every claim."
+        }
+      },
+      "additionalProperties": false,
+      "type": "object"
+    },
     "IdentityValidation": {
       "properties": {
         "reset_password": {