001package com.nimbusds.openid.connect.provider.spi.par;
002
003
004import net.jcip.annotations.ThreadSafe;
005
006import com.nimbusds.oauth2.sdk.AuthorizationRequest;
007import com.nimbusds.oauth2.sdk.GeneralException;
008
009
010/**
011 * Service Provider Interface (SPI) for performing additional validation of
012 * Pushed Authorisation Requests (PAR).
013 *
014 * <p>The {@link #validatePushedAuthorizationRequest} method will be called
015 * after the Connect2id server has performed standard validation of the OAuth
016 * 2.0 authorisation / OpenID authentication request, such as such as checking
017 * the {@code client_id} and ensuring the client is authorised to use the OAuth
018 * 2.0 grant. JWT-secured authorisation requests (JAR) will be unwrapped /
019 * resolved before that.
020 *
021 * <p>The validated request can be returned modified. Modifications should be
022 * limited to optional parameters. Parameters such as {@code client_id},
023 * {@code response_type}, {@code redirect_uri} and {@code state} must not be
024 * modified.
025 *
026 * <p>The {@link #validatePushedAuthorizationRequest} method can reject the
027 * request by throwing an {@link InvalidPushedAuthorizationRequestException}
028 * with an appropriate HTTP status code and error code. The exception message
029 * will be logged and not output to the client.
030 *
031 * <p>Example:
032 *
033 * <pre>
034 * throw new InvalidPARException("Scope not accepted scope", // will be logged
035 *      OAuth2Error.INVALID_SCOPE
036 *      .setHTTPStatusCode(400)
037 *      .setDescription("Scope not accepted: some_scope"));
038 * </pre>
039 *
040 * The resulting HTTP response:
041 *
042 * <pre>
043 * HTTP/1.1 400 Bad Request
044 * Content-Type: application/json;charset=UTF-8
045 * Cache-Control: no-store
046 * Pragma: no-cache
047 *
048 * {
049 *   "error"             : "invalid_scope",
050 *   "error_description" : "Scope not accepted: some_scope"
051 * }
052 * </pre>
053 *
054 * <p>Implementations must be thread-safe.
055 */
056@ThreadSafe
057public interface PARValidator {
058        
059        
060        /**
061         * Validates the specified OAuth 2.0 authorisation / OpenID
062         * authentication request.
063         *
064         * <p>Deprecated, use {@link #validatePushedAuthorizationRequest}
065         * instead.
066         *
067         * @param authzRequest The request to perform additional validation on.
068         *                     Can be cast to
069         *                     {@link com.nimbusds.openid.connect.sdk.AuthenticationRequest}
070         *                     for an instance of an OpenID authentication
071         *                     request.
072         *                     Not {@code null}.
073         * @param validatorCtx The PAR validator context. Not {@code null}.
074         *
075         * @throws GeneralException If the request is rejected. Should include
076         *                          an appropriate HTTP status and error code.
077         */
078        @Deprecated
079        default void validate(final AuthorizationRequest authzRequest, final ValidatorContext validatorCtx)
080                throws GeneralException {
081                
082                try {
083                        validatePushedAuthorizationRequest(authzRequest, validatorCtx);
084                } catch (InvalidPushedAuthorizationRequestException e) {
085                        throw new GeneralException(e.getMessage(), e.getErrorObject());
086                }
087        }
088        
089        
090        /**
091         * Validates the specified OAuth 2.0 authorisation / OpenID
092         * authentication request.
093         *
094         * @param authzRequest The request to perform additional validation on.
095         *                     Can be cast to
096         *                     {@link com.nimbusds.openid.connect.sdk.AuthenticationRequest}
097         *                     for an instance of an OpenID authentication
098         *                     request.
099         *                     Not {@code null}.
100         * @param validatorCtx The PAR validator context. Not {@code null}.
101         *
102         * @return The validated OAuth 2.0 authorisation / OpenID
103         * authentication request. It may be modified. Must not be
104         * {@code null}.
105         *
106         * @throws InvalidPushedAuthorizationRequestException If the request is
107         *                                                    rejected.
108         */
109        default AuthorizationRequest validatePushedAuthorizationRequest(final AuthorizationRequest authzRequest,
110                                                                        final ValidatorContext validatorCtx)
111                throws InvalidPushedAuthorizationRequestException {
112                
113                try {
114                        validate(authzRequest, validatorCtx);
115                } catch (GeneralException e) {
116                        throw new InvalidPushedAuthorizationRequestException(e.getMessage(), e.getErrorObject());
117                }
118                return authzRequest;
119        }
120}