001package com.nimbusds.openid.connect.provider.spi.authz;
002
003
004import net.jcip.annotations.ThreadSafe;
005
006import com.nimbusds.oauth2.sdk.AuthorizationRequest;
007
008
009/**
010 * Service Provider Interface (SPI) for performing additional validation of
011 * OAuth 2.0 authorisation / OpenID authentication requests.
012 *
013 * <p>The {@link #validateRequest} method will be called after the Connect2id
014 * server has performed standard validation of the OAuth 2.0 authorisation /
015 * OpenID authentication request, such as such as checking the
016 * {@code client_id} and {@code redirect_uri}. JWT-secured authorisation
017 * requests (JAR) will be unwrapped / resolved before that.
018 *
019 * <p>The validated request can be returned modified. Modifications should be
020 * limited to optional parameters. Parameters such as {@code client_id},
021 * {@code response_type}, {@code redirect_uri} and {@code state} must not be
022 * modified.
023 *
024 * <p>The {@link #validateRequest} method can reject the request by throwing a
025 * {@link InvalidAuthorizationRequestException} with an appropriate error code
026 * and optional description. When the request is rejected the redirection back
027 * to the OAuth 2.0 client can also optionally be disabled.
028 *
029 * <p>Example:
030 *
031 * <pre>
032 * throw new InvalidAuthorizationRequestException(
033 *      "Scope not accepted", // will be logged
034 *      OAuth2Error.INVALID_SCOPE.setDescription("Scope not accepted: some_scope"),
035 *      false // redirection not disabled
036 * );
037 * </pre>
038 *
039 * <p>Example resulting response:
040 *
041 * <pre>
042 * HTTP/1.1 302 Found
043 * Location: https://client.example.com/cb?
044 *  error=invalid_scope
045 *  &error_description=Scope%20not%20accepted%3A%20some_scope
046 *  &state=UeFi0Eu3siPaJahl
047 * </pre>
048 *
049 * <p>Implementations must be thread-safe.
050 */
051@ThreadSafe
052public interface AuthorizationRequestValidator {
053        
054        
055        /**
056         * Validates the specified OAuth 2.0 authorisation / OpenID
057         * authentication request.
058         *
059         * @param authzRequest The request to perform additional validation on.
060         *                     Can be cast to
061         *                     {@link com.nimbusds.openid.connect.sdk.AuthenticationRequest}
062         *                     for an instance of an OpenID authentication
063         *                     request.
064         *                     Not {@code null}.
065         * @param validatorCtx The authorisation request validator context. Not
066         *                     {@code null}.
067         *
068         * @return The validated OAuth 2.0 authorisation / OpenID
069         * authentication request. It may be modified. Must not be
070         * {@code null}.
071         *
072         * @throws InvalidAuthorizationRequestException If the request is
073         *                                              rejected.
074         */
075        AuthorizationRequest validateRequest(final AuthorizationRequest authzRequest,
076                                             final ValidatorContext validatorCtx)
077                throws InvalidAuthorizationRequestException;
078}