OPMessageHandling

File(s): conf/relying-party.xml, conf/global.xml
Format: Native Spring

Overview

In addition to the IdP’s profile interception, the OP plugin offers some additional hooks for customising the default behaviour. They are described in the following subsections.

Since version 4.2, each OAuth2/OIDC profile can also be configured with messageHandler (of type Function<MessageContext,Exception>) that can be used for manipulating request or response messages. The same hook serves both directions, so the function must detect the direction itself.

Request messages

The default method for parsing incoming request messages is to exploit Nimbus’s message object (see table below) specific parse(HTTPRequest) method. In the authorize-endpoint, the AuthenticationRequest parser is used if the incoming message contains openid scope: otherwise the AuthorizationRequest parser is used. The parsed message is stored in the inbound message context.

Since version 4.2, the following properties may be used for customising the parsing function per flow/endpoint. The corresponding beans are expected the be of type CustomNimbusRequestParser<T> (TODO: Javadoc-link), where the T is the message type described in the following table.

Response messages

The outbound interceptor flow and message handlers can access the outbound response message via outbound message context before the message is encoded into the HTTP response.

The success and error response message objects may be found from the following Nimbus packages:

• OAuth2: https://www.javadoc.io/static/com.nimbusds/oauth2-oidc-sdk/11.11/com/nimbusds/oauth2/sdk/package-summary.html

• OIDC: https://www.javadoc.io/static/com.nimbusds/oauth2-oidc-sdk/11.11/com/nimbusds/openid/connect/sdk/package-summary.html

Error handling

Similarly to SAML, conf/errors.xml and its shibboleth.LocalEventMap bean can be used for configuring whether a specific event is handled locally or relied back to RP as an error response. In the latter case, the following beans may be used to override the default logic for building the error messages. The bean is expected to be a map of event ID strings to Nimbus ErrorObjects, which allows customisation on per-event basis.

The default behaviour for non-mapped events is to use the invalid_request error type with the error event string as the error description.