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