OpenID Connect request mapping for authorization context
Based on the configuration, the OAuth or Open ID Connect flows in IBM® Security Verify can perform authorization actions.
The flows can include these actions.
- Evaluate the access policy.
- Calculate claim values that are stored in the authorization grant and used to build ID tokens and the introspection response.
The context request mapping rule provides a mechanism to augment the context that is collected
from the authorization request. For example, the authorization request might contain a custom
request parameter called contextID
. The custom rule can include the
contextID
in an HTTP request to an external endpoint. The result of this HTTP
request is an object that can be unpacked and added to the requestContext
that is
used during access policy evaluation and grant enrichment. 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
- 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
are described in the "HTTP Request Context" section of Attribute functions.For access, certain values are pre-computed in therequestContext
. Theclaims
request parameter is typically represented as a JSON file like the following example.{ "id_token": { "claim_name": { "essential": false, "value": "some_value" } }, "userinfo": { "claim_name": { "essential": false, "value": "some_value" } } }
This format can be cumbersome to access. The key that is used in the
requestContext
is in the formatclaims_claimType_claimName
. TheclaimType
is eitheruserinfo
oridtoken
(notice the missing underscore). Thus, by using the preceding example, theclaim_name
value can be obtained by usingrequestContext.getValue('claims_idtoken_claim_name')
.Similarly,
scope
is split by the space separator 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,
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 Attribute functions.
Return object
This custom rule is expected to return a JSON object and the value of each JSON property is expected to be a string array.
{
"ageRange": ["toddler"],
"interests": ["sleeping", "other_misc_activities"]
}
This return value is processed and can later be accessed in advanced rule attributes by
using requestContext.ageRange
and requestContext.interests
.
Advanced rule attributes can be used in access policies such as {{requestContext.ageRange[0]
!= 'toddler'}}
or to map attributes in the authorization grant
requestContext.interests
.Example - Add hobbies to the ID token
hobbies
to the ID token.
statements:
- context: "contextData := hc.getAsJSON('https://jke.com/users/' + idsuser.getValue('uid'), { 'Authorization': 'apikey supersecretkey' })"
- return: >-
{
"hobbies": request.Context.interests.filter(x, x != 'other')
}
In this example, the rule is calling out to an external users endpoint to get
additional information about the user. It uses the idsuser
object, which represents
the user's authenticated session on Verify. Finally, the rule
extracts hobbies
from the response.hobbies
can be accessed by the following methods.- Creating an advanced rule attribute that is named
my_hobbies
with a custom rule defined asrequestContext.hobbies
. The data type for this attribute is multi-valued string. - Adding an attribute mapping for this attribute. See OpenID Connect introspect, ID token, and user info mapping.