Relying party advanced configuration

We can use advanced configuration to customize requests that are made by the Relying Party.

Advanced configuration consists of a JavaScript mapping rule, which we can configure on a per partner or per federation basis. The JavaScript mapping rule is invoked at the following points during the Relying Party (RP) single sign-on flow.

• Before the redirect to /authorize
• Before the request to /token

  This invocation point also allows the modification of the request to /userinfo.

The goal of the mapping rule is to add, augment, or remove parameters from the request that is about to be made. This request is achieved through a 302 redirect sent to the user agent.

Potential uses of the advanced mapping rule before the redirect from the OpenID Connect Provider (OP):

• Execution of an HTTP callout to a remote service.

• Modification of the request parameters for the request to /authorize that is about to be made. This modification can include changes to request_type, redirect_uri, state, nonce, scope, and any other parameters the RP configuration includes.

• Addition of any new parameters. For example, if you are federating to Microsoft Azure, we might want to include a resource parameter. Common or standardized parameters include a claims, prompt, or acr_values.
• Removal of unwanted parameters, such as removing response_mode=form_post. For example, if the OP does not support nonce on authorization code flows, use this mechanism to remove it.

The RP uses the STSUniversalUser (STSUU) to represent the authentication request or response in its processing. The STSUU is passed into advanced mapping. HTTP parameters are included in the context attributes. JWT claims and the response from /userinfo are included in the attribute list, as they pertain to a users identity.

The processing flow before and after invocation of the rule is as follows:

1. An incoming single sign-on request is received, either as part of a single sign-on kickoff, or as a redirect from the OpenID Connect Provider (OP).
2. The request is unpacked into an STSUU structure.
3. The mapping rule adds, to the STSUU, any values configured in the RP that need to be sent as part of this authorize request. For example, scope, client_id, and response_types.
4. The advanced configuration rule is invoked, and changes are made to the STSUU.
5. When the rule is successfully run, the STSUU is converted into an HTTP request.

Supported scenarios:

• Augmentation of a single sign-on request at run time. This request is to /authorize.

  By unpacking the incoming single sign-on request at the /kickoff delegate, we can build an RP that tailors its functions based on the incoming request. Because the request parameters to /kickoff are included in the STSUU, we can modify the request to /authorize, based on the initial request to /kickoff. For example, a different scope might be requested, or a decision made against the use of an implicit flow. This mapping rule allows those values to be added, changed, or removed at run time.

• Allowance for OPs that do not fully conform to the OpenID Connect 1.0 specification.

  Some OPs might place extra requirements on incoming request parameters, or might support alternative parameter values. Some OPs might reject some of the specification-compliant values due to their own limitations.

• A similar scenario applies to requests to /token. A client might be required to present another parameter to /token, to use an additional feature that is supported or required by the OP.

Since the same rule runs at both points, authors of rules must include logic to extract the current request type, and run the logic only where appropriate. This requirement is similar to the OAuth concept request_type. Because of this requirement, the operation parameter in the STSUU can be used.

In your mapping rule, use the attribute operation, of type urn:ibm:SAM:oidc:rp:operation to execute the mapping rule code for the STSUU operation for the intended entry point. We can then specify attributes of the necessary attribute type, based on the operation value.

For information, see:

• Relying Party attribute types
• Use of STSUU for the Relying Party
• Security Token Service Universal User document

Example rule

The Security Verify Access distribution includes an example advanced configuration mapping rule for Relying Party. This example demonstrates a simple way to include an example claims parameter. To view it:

1. Log in to the local management interface.
2. Select Federation > Global Settings > Mapping Rules.
3. Select OIDCRP_ADV Category OIDC, and use the Edit function to view the contents.

Parent topic: Authentication with OpenID Connect Relying Party