Authorisation request interceptor SPI

1. Capture and optional modification of incoming authorisation requests

This plugin interface (SPI) enables interception and optional modification of authorisation requests, before they are processed by the Connect2id server.

Both regular and pushed (PAR) requests can be intercepted. This makes the SPI suitable for request normalisation, compatibility fixes and early diagnostic logging that must occur before request parsing, validation, JAR handling or client lookup.

Typical uses include:

• Translating legacy comma-separated scope values to the standard space-delimited form.
• Mapping non-standard parameters to their deployment-specific equivalents.
• Normalising parameter values for older clients.
• Capturing redacted diagnostic logs of received or transformed request parameters.

The SPI is available since v19.12.

Note that the authorisation request validator and the PAR validator also support validation and optional modification of requests, but they are invoked after the Connect2id server has performed initial processing and validation. The authorisation request interceptor is intended for use cases that must run before this processing takes place.

2. Authorisation request interceptor SPI

To plug in an interceptor implement the AuthorizationRequestInterceptor SPI defined in the Connect2id server toolkit:

Features of the authorisation request interceptor SPI:

• Suitable for request normalisation, compatibility fixes and early diagnostic logging that must occur before the Connect2id server processes the request.
• Invoked for both regular authorisation requests and pushed authorisation requests (PAR).
• For PAR, the interceptor is invoked only at the PAR endpoint. When the pushed request is later continued at the authorisation endpoint with a PAR request_uri, the interceptor is not invoked again.

If the Connect2id server detects an SPI implementation it will log its loading under OP2116.

INFO main MAIN - [OP2116] Loaded AuthorizationRequestInterceptor: class=com.nimbusds.openid.connect.provider.spi.authz.impl.SampleAuthzInterceptor enabled=true

3. Example

Sample plugin to translate legacy comma-separated scope values to the standard space-delimited form:

import com.nimbusds.oauth2.sdk.util.*;
import com.nimbusds.openid.connect.provider.spi.authz.*;

public class LegacyScopeRectifier implements AuthorizationRequestInterceptor {
             
    @Override
    public Map<String, List<String>> interceptRequest(final Map<String, List<String>> params,
                                                      final boolean isPAR,
                                                      final InterceptorContext interceptorCtx) {
    
        String scopeString = MultivaluedMapUtils.getFirstValue(params, "scope");
        if (StringUtils.isEmpty(scopeString)) {
            // Scope parameter not specified
            return params;
        }
        if (! scopeString.contains(",")) {
            // Legacy comma not detected
            return params;
        }
        String rectifiedScopeString = StringUtils.replace(scopeString, ",", " ");
    
        Map<String, List<String>> rectifiedParams = new HashMap<>(params);
        rectifiedParams.put("scope", List.of(rectifiedScopeString));
        return rectifiedParams;
    }
}