OpenID Connect request mapping for consent requests

The OAuth and Open ID Connect authorization flow might present users with a consent prompt that requests authorization.

The authorization flows can request authorization to perform the following actions.

Share data from the user's profile, such as the email address. This request might optionally be supplemented with information that indicates the purpose for which the data is being shared.
Perform actions on behalf of the user, such as starting the user's vehicle and heat during a cold day or initiating a payment.

Typically, applications request the action in the form of the scope parameter. However, sometimes, the request might need to be modified. For example,

Always check user authorization status for the user license agreement.
Filter out specific scope values based on the user's authentication session.
Add more context that indicates why data is being requested, whether that is either encoded within the scope (example, email_for_billing) or is available as part of another request parameter (such as authorization_details).

This type of modification can be achieved by using the consent request parameter's custom rule. See Attribute functions. The rule can be written by using a simple single-line expression language or as a more advanced multi-line YAML-based document. See Multi-line rule executor.

Available input objects

Because this custom rule is run after authentication but before authorization, the information that is available does not include all possible domain objects. They are limited to the following types.

HTTP request context

When a user logs in to Verify, the incoming HTTP request context can be accessed in the request-mapping rule. All OAuth request parameters, such as claims and scope, are available in this requestContext. The general structure and use of requestContext is described in the "HTTP Request Context" section of the Attribute functions.

For simplicity of access, certain values are precomputed in the requestContext. The claims request parameter is represented as a JSON like the following example.

{
    "id_token": { 
        "claim_name": { 
            "essential": false, 
            "value": "some_value"
        }
    },
    "userinfo": {
        "claim_name": { 
            "essential": false, 
            "value": "some_value"
        }
    }
}

This JSON can be cumbersome to access and so the key that is used in the requestContext is in the format claims_claimType_claimName. The claimType is either userinfo or idtoken. Note the missing underscore. Thus, with the previous example, the claim_name value can be obtained by using requestContext.getValue('claims_idtoken_claim_name').

Similarly, scope is computed and split by a space to build a string array.

Identity source credential

When a user logs in to Verify, the identity source credential attributes are added into the login session and can be accessed in the request-mapping rule.

The idsuser domain object is available as a map with a string key and a string array value. For example,

{
  "realmName": ["cloudIdentityRealm"],
  "displayName": ["Jessica J. Hill"],
  "phone": ["+12324321234"]
}

For more information, see Attribute functions.

Other functions and operators

Standard operators and functions are available in the mapping rule. The HTTP client is also available to make outbound requests. Other supported functions include hashing and timestamps. See the relevant sections in the Attribute functions.

Return object

The custom rule is expected to return an array that contains strings or objects. The strings are scopes, while the objects are scopes with additional information to associate them to a privacy purpose. See Managing privacy purposes.

The following code is an example of a return object. When the user consents to the first request object, a consent is created to the email attribute for marketing. In addition, the personal:email scope is granted and the personal_email_allowed claim is added to the ID token.


[
	{
		"purpose": "marketing",
		"attribute": "email",
		"accessType": "read",
		"value": "jhill@ibm.com",
		"custom": {
			"type": "personal"
		},
		"claims": {
			"personal_email_allowed": true
		},
		"scope": "personal:email"
	},
    {
        "purpose": "defaultEULA"
    },
	"profile",
	"email"
] + requestContext.scope

Note:

The list here completely replaces the requested scopes and is used to build the consent page. See Modify single sign-on for OpenID pages. If the intent is to ask the user for more consent, you must append requestScope.scope as shown in the adding and removing scopes example.

In the example, the array can take two types - OAuth scope as a string and an object that has more context and results in a finer-grained consent authorization record. These properties are the properties that are allowed in the object.

Property	Type	Required?	Description
`purpose`	String	Yes	Managing privacy purposes
`attribute`	String	Depends on purpose	Managing attributes
`accessType`	String	Depends on purpose	Access type is configured with the data privacy purpose. It defaults to `default` if not provided.
`value`	String	No	Indicates a more specific consent request. For example, consent for a specific email.
`custom`	JSON object. JSON property value type is string.	No	Any additional context information to be added to the consent. This property is available to be displayed in the consent page in the form of template macros.
`claim`	JSON object. JSON property value type is string.	No	If the request is authorized, corresponding claims are added to the ID token issued.
`scope`	String	No	If the request is authorized, this value is added to the granted scopes.
`required`	Boolean	No	If `required` is set to true, then the user must respond with an assent. This assent is not required, if the privacy policy decision indicates that the consent can never be accepted.
`autoGrant`	Boolean	No	If `autoGrant` is set to true, then the user is not prompted to consent and the consent item is automatically authorized.
`global`	Boolean	No	If `global` is set to true, then the recorded consent is global across all applications. This property is relevant for consent items, such as Terms documents that the user accepts only once.
`audience`	String	No	If the request is authorized, this value is added to the granted audiences along with the list of audiences that is configured in the application, and the default client ID.

Example for adding and removing scopes

In this example, a new consent request object is added and a scope is removed.

[
   {
       "purpose": "defaultEula",
       "scope": "eula:default"
   }
] + requestContext.scope.filter(x, x != "badscope")

This rule grants the scope eula:default on authorization and associates it with the EULA consent. It also filters out badscope from the requested scopes.

The consent page can be customized to display details of the consent request that were added through this mapping rule. An example is provided in OpenID Connect request mapping Open Banking intent ID.