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>, where the T is the message type described in the following table.

(Pushed) authorization/authentication requests

By default, the OP plugin uses the existence of the openid scope-parameter to determine whether the incoming authorization request is an OIDC authentication request or a plain OAuth2 authorization request. This behaviour may be customised via idp.oauth2.authorizationRequestTypeValidationStrategy -property. The bean type is Predicate<ProfileRequestContext>.

The request object (request and request_uri -parameters) handling logic is different between the request message types as OIDC core specification specifies a different logic from the JAR-spec (RFC 9101), which is applied for the plain OAuth2 requests since version 4.2. In short, in the OIDC-case the parameters from the request object may be merged with the other request parameters, as in the JAR-case solely the request object parameters are used if the request object is specified. In the PAR endpoint, the JAR-logic is always applied ,as specified by RFC 9126. This also means that whenever PAR is used for the OIDC authentication messages, the JAR-logic is applied.

The properties idp.oauth2.par.useOnlyRequestObject (for PAR-endpoint) and idp.oauth2.authorize.useOnlyRequestObject(for authorize-endpoint) can be used for customizing the request object handling. The bean type is BiPredicate<Pair<AuthorizationRequest,Boolean>,String>. The first parameter (Pair) contains the authorization request object and a flag that indicate whether the request object has been built via PAR endpoint. Obviously in the PAR-endpoint itself this flag is always false. The second parameter (String) contains the parameter name.

In the authorize endpoint, the property idp.oidc.LoginHintLookupStrategy is also available for customizing the function for reading the login_hint parameter value. Its type is Function<ProfileRequestContext,String>.

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: com.nimbusds.oauth2.sdk (Nimbus OAuth 2.0 SDK with OpenID Connect 1.0 extensions v11.11)

• OIDC: com.nimbusds.openid.connect.sdk (Nimbus OAuth 2.0 SDK with OpenID Connect 1.0 extensions v11.11)

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.