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