OpenID Connect Advanced Syntax for Claims (ASC) 1.0

6.1. claim

piece of information asserted about an entity¶

[SOURCE: [OpenID], 1.2]¶

6.2. OpenID provider

OAuth 2.0 Authorization Server that is capable of Authenticating the End-User and providing Claims to a Relying Party about the Authentication event and the End-User. Also referred to as OP or identity provider¶

[SOURCE: [OpenID], 1.2]¶

6.3. relying party

OAuth 2.0 Client application requiring End-User Authentication and Claims from an OpenID Provider. Also referred to as RP¶

[SOURCE: [OpenID], 1.2]¶

7.1. Example

The following example illustrates the new syntax introduced by this specification. It shows the contents of the claims request parameter.¶

Example 1:¶

{
   "id_token": {
      "verified_claims": {
         "verification": {
            "trust_framework":null,
            "assurance_level": null
         },
         "claims": {
            "family_name": {
               "value":"nonexistent_family_name"
            },
            "given_name":null,
            "birthdate": null,
            "address":null
         }
      }
   },
   "userinfo": {
      "address":null
   },
   "_asc": {
      "sao": {
         "id_token":[
            {
              "loc":"/verified_claims/verification/assurance_level",
              "method": "simple",
              "value": "example_assurance_level",
              "else":"abort"
            },
            {
               "loc":"/verified_claims/claims",
               "method": "schema",
               "schema": {
                  "$schema":"http://json-schema.org/draft-07/schema#",
                  "type":"object",
                  "properties": {
                     "birthdate": {
                        "type":"string",
                        "const":"1900-01-01"
                     }
                  }
               },
               "else":"omit"
            },
            {
               "loc":"/verified_claims/claims/family_name",
               "method": "simple",
               "value": "nonexistent_family_name",
               "else":"omit",
               "what":[
                  "/verified_claims"
               ]
            }
         ],
         "userinfo":[
            {
               "loc":"/address/postal_code",
               "method": "exists",
               "else":"abort"
            }
         ]
      }
   }
}

Another example for using SAO together with TC is shown below.¶

7.2. Syntax and Processing

To use Advanced Syntax for Claims, the RP adds a new subelement _asc to the root level of the claims JSON structure in the authentication request. Within _asc, the RP adds a new subelement sao that contains the SAO rules. The SAO rules are grouped by delivery type, i.e., id_token and userinfo.¶

Within each delivery type, there is an array of SAO rules, each being an object with the following fields:¶

• loc: REQUIRED. A string containing a JSON Pointer [RFC6901] to the respective element in the ID Token or Userinfo response structure where the rule is to be applied.¶
• method: OPTIONAL string. If provided, MUST be one of simple, schema, or exists. If omitted, defaults to exists. Support for schema is OPTIONAL for OPs and can be discovered using metadata, as described in Section 7.3.¶
• schema: REQUIRED if method is schema, MUST NOT be present otherwise. A JSON schema object as defined in [I-D.bhutton-json-schema] that the respective element in the ID Token or Userinfo response structure must validate against.¶
• value or values: Either value or values is REQUIRED if method is simple; MUST NOT be present otherwise; value and values MUST NOT be used together. For value, a valid claim value MUST be provided which is either a string, a number, or a boolean. For values, an array of such values MUST be provided.¶
• else: REQUIRED. A string, either abort or omit, indicating the action to take if the rule is not fulfilled. If abort is used, the transaction MUST be aborted. If omit is used, one or more elements MUST be omitted from the response, as defined next.¶
• what: OPTIONAL if the value of else is omit, MUST NOT be used otherwise. An array of one or more strings, each containing a JSON Pointer [RFC6901] to the respective element in the ID Token or Userinfo response structure that are to be omitted if the rule is not fulfilled. If what is not defined, the element specified in loc is omitted.¶

The else action MUST be triggered when¶

• the element indicated by loc does not exist,¶
• the element was removed by a previously executed omit rule, or¶
• the user does not consent to the release of the claim.¶

Additionally, depending on the value of method, the following matches MUST be performed:¶

• simple: The value of the claim indicated by loc is matched against value or values provided in the SAO rule. If value is provided, the claim value will be matched to the provided value using exact matching. For values, the claim value must exactly match at least one of the values in the array. In the example above, the assurance_level would be matched against example_assurance_level and family_name would be matched against nonexistent_family_name. The else action MUST be triggered if the value of the claim does not match the requested value or values.¶
• schema: The JSON Schema schema element MUST apply to the JSON structure under the element indicated by loc. In the example above, the schema would be applied to the whole claims object under verified_claims. The else action MUST be triggered if the schema does not apply.¶
• exists: No additional matches are performed.¶

The SAO rules provided MUST be executed first for all id_token rules and then for all userinfo rules. Within each delivery type, the SAO rules MUST be executed in the order they are provided in the request. If an abort action is triggered, the transaction MUST be aborted and remaining SAO rules MUST NOT be executed. If an omit action is triggered, the respective elements MUST be omitted from the response; further SAO rules MUST be executed. Note that omit is scoped to the respective delivery type, i.e., an element that was omitted from the id_token response can still be present in the userinfo response if it was requested for both delivery types.¶

In Example 1, data would be processed as follows:¶

1. If the assurance_level is not available as a verified claim or it does not match the string example_assurance_level, the transaction is aborted.¶
2. If the birthdate claim is not available or the birthdate is not a string with the value 1900-01-01, the verified_claims/claims object is omitted from the response. Since the verified_claims element may not be used without the claims subelement, the whole verified_claims object is omitted.¶
3. If the family_name is not available as a verified claim or it does not match the string nonexistent_family_name, the verified_claims object is omitted from the response.¶
4. If the postal_code is not available in the address object, the transaction is aborted.¶

7.3. OP Metadata

The OP advertises its capabilities with respect to Selective Abort/Omit in its openid-configuration (see [OpenID-Discovery]) using the following new elements:¶

• selective_abort_omit_supported: OPTIONAL. Boolean value indicating OP support for "Selective Abort/Omit". Defaults to false.¶
• selective_abort_omit_schema_supported: OPTIONAL. Boolean value indicating OP support for the method value schema. Defaults to true. If false, the OP MUST abort the transaction with an invalid_request error if a JSON Schema is used in an SAO rule.¶

7.4. Privacy Considerations

Using Selective Abort/Omit can in general lead to more privacy preserving systems, as an RP can instruct an OP not to send incomplete datasets that are not useful to the RP.¶

An RP might be able to derive information from a response even if the response is an error response or claims are omitted. For example, the following request can be used to derive whether or not the user is named Max:¶

{
  "id_token": {
    "given_name": {
      "value": "Max"
    }
  },
  "_asc": {
    "sao": {
      "id_token": [
        {
          "loc": "/given_name",
          "method": "simple",
          "else": "abort"
        }
      ]
    }
  }
}

When the request is aborted, the user is not called Max. In a naive implementation, the abort of the request might happen before the user has consented to the release of the data. In this case, using a series of carefully crafted requests, an RP might be able to derive substantial information about a user even if the user's name is never transferred from the OP to the RP directly. A malicious RP can use this to derive user information without the user's consent or without paying for the data. Note that omit can leak information in a similar way.¶

To avoid leakage of user information through this mechanism without the user's consent, implementations SHOULD in general avoid returning a result before a user has consented to the release of the base data if privacy is a concern in the respective application. In the example above, the user would be asked to confirm the release of the given name data field before the OP aborts the transaction or omits the claim. OPs MAY make exceptions for RPs when a contractual or trust relationship with this RP was established beforehand or there are other mechanisms in place to ensure that misuse is prevented.¶

To the same end, and to avoid relying parties not paying for data, OPs SHOULD additionally consider rate-limiting requests and monitoring requests for anomalies (frequent dynamic changes in request structure, frequent aborts).¶

7.5. Compatibility Considerations

An OP not supporting ASC will ignore the additional _asc key as defined in Section 5.5.1 of [OpenID]. An OP supporting ASC but not SAO MUST ignore the sao key.¶

An RP may receive data from an OP that does not support SAO when aborting the transaction or not delivering the data was requested instead. RPs can avoid this by checking for SAO support in the metadata of the OP before sending the request.¶

8.1. Example: Age Verification

The Claim birthdate, a date, can be transformed into an integer using the function years_ago. This function outputs the number of years between the current date and the input date, rounded down. The resulting integer can be transformed using the function gte with the argument 18. This function evaluates whether the input value is greater than or equal to the given argument. Its output is either true or false. The resulting Transformed Claim, representing whether the End-User is above 18 or not, can be aliased, for example age_18_or_over. This Claim can be used within the OpenID Connect claims parameter instead of or together with the original Claim, birthdate.¶

If data for the original Claim birthdate is unavailable, the new Claim age_18_or_over shall be treated like an unavailable Claim as well.¶

8.2. Defining Transformed Claims

Transformed Claims are defined by the RP in the claims parameter of the Authentication Request. The RP adds a new subelement transformed_claims within the _asc element in the root of the claims JSON structure.¶

transformed_claims is a JSON object in which each key represents a definition for a new Transformed Claim. Each definition consists of an object with the following keys:¶

• claim defines the Claim on which the Transformed Claim is based¶
• fn is the array of functions to apply to the base Claim, in order of application. Each function is either a string, like year_ago to apply the function without further arguments, or an array, like ["gte", 18], to apply the function with arguments.¶

For example, the Transformed Claim for age verification from above could be defined as follows:¶

{
  "_asc": {
    "transformed_claims": {
      "age_18_or_over": {
        "claim": "birthdate",
        "fn": [
          "years_ago",
          [
            "gte",
            18
          ]
        ]
      }
    }
  },
  "id_token": {
    ...
  }
}

Note: There can be multiple Transformed Claims defined on the same base Claim.¶

TODO: Define charset for transformed claim names, shall not start with ':'.¶

{
  "_asc": {
    "transformed_claims": {
      "age_18_or_over": {
        "claim": "birthdate",
        "fn": [
          "years_ago",
          [
            "gte",
            18
          ]
        ]
      }
    }
  },
  "id_token": {
    "given_name": null,
    "family_name": null,
    ":age_18_or_over": null
  }
}

{
  ...
  "id_token": {
    "verified_claims": {
      "claims": {
        "given_name": null,
        "family_name": null,
        ":age_18_or_over": null
      },
      ...
    }
  }
}

{
  ...
  "id_token": {
    "given_name": null,
    "family_name": null,
    ":age_18_or_over": {
      "value": true,
      "essential": true
    }
  }
}

{
  "id_token": {
    "given_name": null,
    "family_name": null,
    ":age_18_or_over": {
      "value": true
    }
  },
  "_asc": {
    "transformed_claims": {
      "age_18_or_over": {
        "claim": "birthdate",
        "fn": [
          "years_ago",
          [
            "gte",
            18
          ]
        ]
      }
    },
    "sao": {
      "id_token": [
        {
          "loc": "/:age_18_or_over",
          "method": "simple",
          "value": true,
          "else": "abort"
        }
      ]
    }
  }
}

8.3. Data Types

Claims defined in [OpenID] and [IDA] have one of the data types 'string', 'boolean', 'number', 'JSON object' or 'array'. For the purpose of this specification, these data types are used as well as the new data type 'date', which applies to Claims representing dates, and 'datetime', which applies to Claims representing date and time. Therefore, birthdate is both of type string and date, and updated_at is both of type number and datetime.¶

Todo: Define input formats for date and datetime.¶

8.4. Transformation Functions

In the following, a base set of transformation functions is defined. OPs supporting Transformed Claims shall support at least one transformation function.¶

In the following, the first function argument Input refers to the value of the base Claim, or, if multiple functions are to be applied, the output of the previous function. For other arguments, the RP defines a constant value in each request. Optional arguments may be omitted.¶

This specification defines the following functions:¶

8.5. Predefined Transformed Claims (PTC)

An OP supporting Transformed Claims shall publish the key transformed_claims_functions_supported containing an array of supported functions (only the function names) in its OP Metadata.¶

Example:¶

...
  "transformed_claims_functions_supported": ["eq", "match", "years_ago"],
...

An RP can use the presence of this key to determine general support for Transformed Claims at the OP.¶

An OP may predefine Transformed Claims. This avoids repetitions in requests and enables RPs to use Transformed Claims without requiring specific software support.¶

To predefine a Transformed Claim, the OP publishes the key transformed_claims_predefined in its OP metadata. Its contents follow the same syntax as transformed_claims in the claims object:¶

...
  "transformed_claims_predefined": {
    "age_18_or_over": {
      "claim": "birthdate",
      "fn": [
        "years_ago",
        [
          "gte",
          18
        ]
      ]
    },
    "age_21_or_over": {
      "claim": "birthdate",
      "fn": [
        "years_ago",
        [
          "gte",
          21
        ]
      ]
    }
  }
...

RPs may use PTCs in a request to the OP as if the respective Transformed Claims were defined in transformed_claims in the request. However, two colons (::) are prepended to distinguish predefined from custom Transformed Claims:¶

{
  "id_token": {
    "given_name": null,
    "family_name": null,
    "::age_18_or_over": {
      "value": true,
      "essential": true
    }
  }
}

An OP may further set the key transformed_claims_max_count to 0 to denote that only PTCs can be used and custom Transformed Claims are not supported.¶

Example:¶

...
  "transformed_claims_functions_supported": ["years_ago", "gte"],
  "transformed_claims_max_count": 0,
  "transformed_claims_predefined": {
    "age_18_or_over": {
      "claim": "birthdate",
      "fn": [
        "years_ago",
        [
          "gte",
          18
        ]
      ]
    }
  },
...

8.6. OP Metadata

The OP advertises its capabilities with respect to Transformed Claims in its openid-configuration (see [OpenID-Discovery]) using the following new elements:¶

transformed_claims_functions_supported: OPTIONAL. JSON array indicating support for Transformed Claims, and containing an array of the supported function names. When present this array must have at least one member.¶

transformed_claims_predefined: OPTIONAL. JSON object containing the definitions of all supported Predefined Transformed Claims following the same syntax as transformed_claims in the claims object. When present this object must contain at least one definition of a Predefined Transformed Claim. If this metadata value is omitted, the OP does not support Predefined Transformed Claims.¶

transformed_claims_max_depth: OPTIONAL. Integer value indicating the maximum number of functions in a chain of functions used to define a transformed claim. If this metadata value is omitted, the OP MUST support chains of functions of any length.¶

transformed_claims_max_count: OPTIONAL. Integer value indicating the maximum number of transformed claims an RP can define, excluding any Predefined Transformed Claims. If this is set to 0, the RP may only use Predefined Transformed Claims. If this metadata value is omitted, the OP MUST support any number of transformed claims.¶

8.7. Error Conditions

The following error conditions MUST be checked by an OP, in this order:¶

1. If the definition of a transformed claim provided by an RP uses more than transformed_claims_max_depth function applications or the number of custom transformed claims exceeds transformed_claims_max_count, the OP MUST abort the transaction with an invalid_request error. The error_description provided by the OP SHOULD indicate the location and nature of the error.¶
2. If an RP uses, in a definition for a transformed claim, a function not supported by the OP and therefore not listed in transformed_claims_functions_supported, or the wrong number of arguments, or a wrong type of argument, the OP MUST abort the transaction with an invalid_request error. The error_description provided by the OP SHOULD indicate the location and nature of the error.¶
3. Each transformed claim is based on a single base claim, as expressed by the claim key in the definition of the transformed claim. In case this base claim is not known to the OP, or data is not available for this claim, or similar conditions, the transformed claim MUST be treated the same as the base claim. For example, if the base claim is unknown to the OP, the transformed claim is handled as if it were an unknown claim as well. If an End-User choses not to release the base claim, or the base claim is not released to the RP for some other reason, the transformed claim MUST NOT be released as well.¶

In general, if an RP references an undefined transformed claim in the claims parameter, the claim MUST be treated like a claim unknown to the OP.¶

8.8. UX and Privacy Considerations

The consent of the End-User is typically required before data can be released by the OP to the RP. An OP cannot be expected to automatically parse and understand all potential combinations of transformation functions and their arguments in order to create a detailed consent prompt for the End-User.¶

OPs can use a number of strategies to ensure that End-User consent is always given in a meaningful way and to provide a good user experience (UX):¶

• Simple cases, for example the combination of years_ago and gte(x) applied to birthdate shown above, can be translated into a statement like "The RP wants to know that you are above age x". OPs can prepare a number of patterns to match against the RP's request for common use cases in their ecosystem.¶
• Since PTCs are predefined by the OP, the OP shall be able to provide a meaningful consent text for all its PTCs.¶
• In all other cases, the OP can ask the End-User for their consent to release the full information of the base Claim, e.g., to ask for the consent to release the birthdate instead of verification of age. This is a safe overapproximation due to the guidelines for transformation functions described above.¶

8.9. Compatibility Considerations

An OP not supporting Transformed Claims will ignore the additional element in the claims parameter as defined in Section 5.5 of [OpenID]. All Transformed Claims requested by RPs are therefore unknown to the OP and treated like other unknown claims, i.e., they will typically be ignored.¶

8.10. Examples

The following example shows two custom Transformed Claims being defined and used. Note: Features from Selective Abort/Omit defined above are used as well.¶

{
    "transformed_claims": {
        "company_email": {
            "claim": "email",
            "fn": [
                [
                    "match",
                    "@company\\.com$"
                ]
            ]
        },
        "nationality_usa": {
            "claim": "nationalities",
            "fn": [
                [
                    "eq",
                    "USA"
                ],
                "any"
            ]
        }
    },
    "id_token": {
        "given_name": null,
        "family_name": null,
        ":company_email": {
            "value": true,
            "if_different": "abort"
        },
        "email_verified": {
            "value": true,
            "if_different": "abort"
        },
        "verified_claims": {
            "claims": {
                ":nationality_usa": {
                    "value": true,
                    "if_different": "abort"
                }
            },
            "verification": {
                "trust_framework": null
            }
        }
    }
}

9.1. Integrity Protection of the Authentication Request

For a secure operation of the mechanisms defined in this specification, it is important to protect the claims parameter against modifications. Otherwise, a malicious End-User or attacker could create situations where the RP receives misleading data.¶

Moreover, some features in this specification are particularly suited for use cases of OpenID Connect where the RP pays for data received. In such use cases, integrity protection of the claims parameter can be advised to avoid having the RP pay for data not requested.¶

As an example for a malicious modification, when an RP defines a transformed claim :age_18_or_over as shown above, an End-User that is only 12 years old could modify the definition of the Claim from¶

    "age_18_or_over": {
      "claim": "birthdate",
      "fn": [
        "years_ago",
        [
          "gte",
          18
        ]
      ]
    }

to¶

    "age_18_or_over": {
      "claim": "birthdate",
      "fn": [
        "years_ago",
        [
          "gte",
          12
        ]
      ]
    }

and pass the age verification check. When using Selective Abort/Omit, a user could create situations where a flow continues instead of being aborted due to a mismatch in the End-User's data.¶

Therefore, the following rules apply:¶

• Authentication requests using features from Selective Abort/Omit SHOULD only be accepted by an OP if they are integrity-protected and authenticated.¶
• Authentication requests using Transformed Claims MUST only be accepted by an OP if they are integrity-protected, unless transformed_claims_max_count is set to 0 in which case the OP MAY accept authentication requests without integrity protection and authentication. Since Predefined Transformed Claims are defined by the OP, integrity protection and authentication is not required for their use.¶

Integrity protection and authentication of authentication requests can be achieved in particular by¶

• using Pushed Authorization Requests [RFC9126] to send requests server-to-server with authentication of the RP, or¶
• using JWT-Secured Authorization Requests [RFC9101] to sign the authentication request parameters.¶

Using a suitable security profile for OpenID Connect that includes authentication and integrity protection for the authentication request is RECOMMENDED, as this helps to ensure that the protection cannot be circumvented.¶

9.2. Safe Execution of Transformation Functions

OPs MUST ensure that all possible combinations of transformation functions and their respective arguments can be executed securely and without undesired side effects. In particular, for any function supported by the OP, the OP MUST ensure that time and memory limits apply to avoid Denial-of-Service Attacks. For many functions, for example, comparison functions, this is usually inherent to the function itself. For other functions, execution time and complexity limits SHOULD be considered. For example, when applying regular expressions, Regular Expression DoS attacks (ReDoS) are a concern.¶

OPs therefore MAY limit the range of valid input arguments and valid combinations of functions to ensure a secure operation.¶

OPs SHOULD consider setting transformed_claims_max_depth and transformed_claims_max_count to reasonable values to avoid Denial-of-Service attacks.¶