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.
- 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.
scope
parameter. However, in some cases, the request might need to be modified. For example,- Always check user authorization status for the end 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 asauthorization_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
andscope
, are available in thisrequestContext
. The general structure and use ofrequestContext
is described in the "HTTP Request Context" section of the Attribute functions.For simplicity of access, certain values are precomputed in therequestContext
. Theclaims
request parameter is generally 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 formatclaims_claimType_claimName
. TheclaimType
is eitheruserinfo
oridtoken
. Note the missing underscore. Thus, with the previous example, theclaim_name
value can be obtained by usingrequestContext.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.
Theidsuser
domain object is available as a map with a string key and a string array value. For example,
For more information, see Attribute functions.{ "realmName": ["cloudIdentityRealm"], "displayName": ["Jessica J. Hill"], "phone": ["+12324321234"] }
- 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.
email
attribute for the purpose of
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
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 are only
accepted once by the user. |
- 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.