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

Because the 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 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 and scope, are available in this requestContext. The general structure and use of requestContext are described in the "HTTP Request Context" section of Attribute functions.
For access, certain values are pre-computed in the requestContext. The claims 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 format claims_claimType_claimName. The claimType is either userinfo or idtoken (notice the missing underscore). Thus, by using the preceding example, the claim_name value can be obtained by using requestContext.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,

{
  "realmName": ["cloudIdentityRealm"],
  "displayName": ["Jessica J. Hill"],
  "phone": ["+12324321234"]
}
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 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.

The following example is a return object.

{
   "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

The following code is an example of the custom rule for request mapping that adds 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.
Note: This rule does not do any form of validation and is not ready for production use.
hobbies can be accessed by the following methods.