Package com.nimbusds.oauth2.sdk

Class AuthorizationRequest

  • All Implemented Interfaces:
    Message, Request
    Direct Known Subclasses:
    AuthenticationRequest
    @Immutable
public class AuthorizationRequest
extends AbstractRequest
    Authorisation request. Used to authenticate an end-user and request the end-user's consent to grant the client access to a protected resource. Supports custom request parameters.

    Extending classes may define additional request parameters as well as enforce tighter requirements on the base parameters.

    Example HTTP request: 

     https://server.example.com/authorize?
 response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

    Related specifications:

    • OAuth 2.0 (RFC 6749), sections 4.1.1 and 4.2.1.
    • OAuth 2.0 Multiple Response Type Encoding Practices 1.0.
    • OAuth 2.0 Form Post Response Mode 1.0.
    • Proof Key for Code Exchange by OAuth Public Clients (RFC 7636).
    • OAuth 2.0 Rich Authorization Requests (RFC 9396).
    • Resource Indicators for OAuth 2.0 (RFC 8707)
    • OAuth 2.0 Incremental Authorization (draft-ietf-oauth-incremental-authz-04)
    • The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR) (RFC 9101)
    • Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)
    • OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) (RFC 9449).
    • OpenID Connect Federation 1.0, section 10.1.

    • Field Detail

      • prompt

        protected final Prompt prompt
        The requested prompt (optional).

    • Constructor Detail

      • AuthorizationRequest

        public AuthorizationRequest​(URI uri,
                            ResponseType rt,
                            ResponseMode rm,
                            ClientID clientID,
                            URI redirectURI,
                            Scope scope,
                            State state)
        Creates a new authorisation request.
        Parameters:
        uri - The URI of the authorisation endpoint. May be null if the toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        rt - The response type. Corresponds to the response_type parameter. Must not be null.
        rm - The response mode. Corresponds to the optional response_mode parameter. Use of this parameter is not recommended unless a non-default response mode is requested (e.g. form_post).
        clientID - The client identifier. Corresponds to the client_id parameter. Must not be null.
        redirectURI - The redirection URI. Corresponds to the optional redirect_uri parameter. null if not specified.
        scope - The request scope. Corresponds to the optional scope parameter. null if not specified.
        state - The state. Corresponds to the recommended state parameter. null if not specified.

      • AuthorizationRequest

        @Deprecated
public AuthorizationRequest​(URI uri,
                            ResponseType rt,
                            ResponseMode rm,
                            ClientID clientID,
                            URI redirectURI,
                            Scope scope,
                            State state,
                            CodeChallenge codeChallenge,
                            CodeChallengeMethod codeChallengeMethod,
                            List<URI> resources,
                            boolean includeGrantedScopes,
                            com.nimbusds.jwt.JWT requestObject,
                            URI requestURI,
                            Prompt prompt,
                            Map<String,​List<String>> customParams)
        Deprecated.
        Creates a new authorisation request with extension and custom parameters.
        Parameters:
        uri - The URI of the authorisation endpoint. May be null if the toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        rt - The response type. Corresponds to the response_type parameter. Must not be null, unless a request object or URI is specified.
        rm - The response mode. Corresponds to the optional response_mode parameter. Use of this parameter is not recommended unless a non-default response mode is requested (e.g. form_post).
        clientID - The client identifier. Corresponds to the client_id parameter. Must not be null, unless a request object or URI is specified.
        redirectURI - The redirection URI. Corresponds to the optional redirect_uri parameter. null if not specified.
        scope - The request scope. Corresponds to the optional scope parameter. null if not specified.
        state - The state. Corresponds to the recommended state parameter. null if not specified.
        codeChallenge - The code challenge for PKCE, null if not specified.
        codeChallengeMethod - The code challenge method for PKCE, null if not specified.
        resources - The resource URI(s), null if not specified.
        includeGrantedScopes - true to request incremental authorisation.
        requestObject - The request object. Corresponds to the optional request parameter. Must not be specified together with a request object URI. null if not specified.
        requestURI - The request object URI. Corresponds to the optional request_uri parameter. Must not be specified together with a request object. null if not specified.
        prompt - The requested prompt. Corresponds to the optional prompt parameter.
        customParams - Custom parameters, empty map or null if none.

      • AuthorizationRequest

        @Deprecated
public AuthorizationRequest​(URI uri,
                            ResponseType rt,
                            ResponseMode rm,
                            ClientID clientID,
                            URI redirectURI,
                            Scope scope,
                            State state,
                            CodeChallenge codeChallenge,
                            CodeChallengeMethod codeChallengeMethod,
                            List<URI> resources,
                            boolean includeGrantedScopes,
                            com.nimbusds.jwt.JWT requestObject,
                            URI requestURI,
                            Prompt prompt,
                            JWKThumbprintConfirmation dpopJKT,
                            Map<String,​List<String>> customParams)
        Deprecated.
        Creates a new authorisation request with extension and custom parameters.
        Parameters:
        uri - The URI of the authorisation endpoint. May be null if the toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        rt - The response type. Corresponds to the response_type parameter. Must not be null, unless a request object or URI is specified.
        rm - The response mode. Corresponds to the optional response_mode parameter. Use of this parameter is not recommended unless a non-default response mode is requested (e.g. form_post).
        clientID - The client identifier. Corresponds to the client_id parameter. Must not be null, unless a request object or URI is specified.
        redirectURI - The redirection URI. Corresponds to the optional redirect_uri parameter. null if not specified.
        scope - The request scope. Corresponds to the optional scope parameter. null if not specified.
        state - The state. Corresponds to the recommended state parameter. null if not specified.
        codeChallenge - The code challenge for PKCE, null if not specified.
        codeChallengeMethod - The code challenge method for PKCE, null if not specified.
        resources - The resource URI(s), null if not specified.
        includeGrantedScopes - true to request incremental authorisation.
        requestObject - The request object. Corresponds to the optional request parameter. Must not be specified together with a request object URI. null if not specified.
        requestURI - The request object URI. Corresponds to the optional request_uri parameter. Must not be specified together with a request object. null if not specified.
        prompt - The requested prompt. Corresponds to the optional prompt parameter.
        dpopJKT - The DPoP JWK SHA-256 thumbprint, null if not specified.
        customParams - Custom parameters, empty map or null if none.

      • AuthorizationRequest

        @Deprecated
public AuthorizationRequest​(URI uri,
                            ResponseType rt,
                            ResponseMode rm,
                            ClientID clientID,
                            URI redirectURI,
                            Scope scope,
                            State state,
                            CodeChallenge codeChallenge,
                            CodeChallengeMethod codeChallengeMethod,
                            List<URI> resources,
                            boolean includeGrantedScopes,
                            com.nimbusds.jwt.JWT requestObject,
                            URI requestURI,
                            Prompt prompt,
                            JWKThumbprintConfirmation dpopJKT,
                            TrustChain trustChain,
                            Map<String,​List<String>> customParams)
        Deprecated.
        Creates a new authorisation request with extension and custom parameters.
        Parameters:
        uri - The URI of the authorisation endpoint. May be null if the toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        rt - The response type. Corresponds to the response_type parameter. Must not be null, unless a request a request object or URI is specified.
        rm - The response mode. Corresponds to the optional response_mode parameter. Use of this parameter is not recommended unless a non-default response mode is requested (e.g. form_post).
        clientID - The client identifier. Corresponds to the client_id parameter. Must not be null, unless a request object or URI is specified.
        redirectURI - The redirection URI. Corresponds to the optional redirect_uri parameter. null if not specified.
        scope - The request scope. Corresponds to the optional scope parameter. null if not specified.
        state - The state. Corresponds to the recommended state parameter. null if not specified.
        codeChallenge - The code challenge for PKCE, null if not specified.
        codeChallengeMethod - The code challenge method for PKCE, null if not specified.
        resources - The resource URI(s), null if not specified.
        includeGrantedScopes - true to request incremental authorisation.
        requestObject - The request object. Corresponds to the optional request parameter. Must not be specified together with a request object URI. null if not specified.
        requestURI - The request object URI. Corresponds to the optional request_uri parameter. Must not be specified together with a request object. null if not specified.
        prompt - The requested prompt. Corresponds to the optional prompt parameter.
        dpopJKT - The DPoP JWK SHA-256 thumbprint, null if not specified.
        trustChain - The OpenID Connect Federation 1.0 trust chain, null if not specified.
        customParams - Custom parameters, empty map or null if none.

      • AuthorizationRequest

        public AuthorizationRequest​(URI uri,
                            ResponseType rt,
                            ResponseMode rm,
                            ClientID clientID,
                            URI redirectURI,
                            Scope scope,
                            State state,
                            CodeChallenge codeChallenge,
                            CodeChallengeMethod codeChallengeMethod,
                            List<AuthorizationDetail> authorizationDetails,
                            List<URI> resources,
                            boolean includeGrantedScopes,
                            com.nimbusds.jwt.JWT requestObject,
                            URI requestURI,
                            Prompt prompt,
                            JWKThumbprintConfirmation dpopJKT,
                            TrustChain trustChain,
                            Map<String,​List<String>> customParams)
        Creates a new authorisation request with extension and custom parameters.
        Parameters:
        uri - The URI of the authorisation endpoint. May be null if the toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        rt - The response type. Corresponds to the response_type parameter. Must not be null, unless a request object or URI is specified.
        rm - The response mode. Corresponds to the optional response_mode parameter. Use of this parameter is not recommended unless a non-default response mode is requested (e.g. form_post).
        clientID - The client identifier. Corresponds to the client_id parameter. Must not be null, unless a request object or URI is specified.
        redirectURI - The redirection URI. Corresponds to the optional redirect_uri parameter. null if not specified.
        scope - The request scope. Corresponds to the optional scope parameter. null if not specified.
        state - The state. Corresponds to the recommended state parameter. null if not specified.
        codeChallenge - The code challenge for PKCE, null if not specified.
        codeChallengeMethod - The code challenge method for PKCE, null if not specified.
        authorizationDetails - The Rich Authorisation Request (RAR) details, null if not specified.
        resources - The resource URI(s), null if not specified.
        includeGrantedScopes - true to request incremental authorisation.
        requestObject - The request object. Corresponds to the optional request parameter. Must not be specified together with a request object URI. null if not specified.
        requestURI - The request object URI. Corresponds to the optional request_uri parameter. Must not be specified together with a request object. null if not specified.
        prompt - The requested prompt. Corresponds to the optional prompt parameter.
        dpopJKT - The DPoP JWK SHA-256 thumbprint, null if not specified.
        trustChain - The OpenID Connect Federation 1.0 trust chain, null if not specified.
        customParams - Custom parameters, empty map or null if none.

    • Method Detail

      • getRegisteredParameterNames

        public static Set<String> getRegisteredParameterNames()
        Returns the registered (standard) OAuth 2.0 authorisation request parameter names.
        Returns:
        The registered OAuth 2.0 authorisation request parameter names, as a unmodifiable set.

      • getResponseMode

        public ResponseMode getResponseMode()
        Returns the optional response mode. Corresponds to the optional response_mode parameter.
        Returns:
        The response mode, null if not specified.

      • impliedResponseMode

        public ResponseMode impliedResponseMode()
        Returns the implied response mode, determined by the optional response_mode parameter, and if that isn't specified, by the response_type.

        If the jwt response mode shortcut from JARM is explicitly requested expands it to query.jwt or fragment.jwt depending on the response type (response_type).

        Returns:
        The implied response mode.

      • getClientID

        public ClientID getClientID()
        Returns the client identifier. Corresponds to the client_id parameter.
        Returns:
        The client identifier.

      • getRedirectionURI

        public URI getRedirectionURI()
        Returns the redirection URI. Corresponds to the optional redirection_uri parameter.
        Returns:
        The redirection URI, null if not specified.

      • getScope

        public Scope getScope()
        Returns the scope. Corresponds to the optional scope parameter.
        Returns:
        The scope, null if not specified.

      • getState

        public State getState()
        Returns the state. Corresponds to the recommended state parameter.
        Returns:
        The state, null if not specified.

      • getCodeChallenge

        public CodeChallenge getCodeChallenge()
        Returns the code challenge for PKCE.
        Returns:
        The code challenge, null if not specified.

      • getResources

        public List<URI> getResources()
        Returns the resource server URI.
        Returns:
        The resource URI(s), null if not specified.

      • includeGrantedScopes

        public boolean includeGrantedScopes()
        Returns true if incremental authorisation is requested.
        Returns:
        true if incremental authorisation is requested, else false.

      • getRequestObject

        public com.nimbusds.jwt.JWT getRequestObject()
        Returns the request object. Corresponds to the optional request parameter.
        Returns:
        The request object, null if not specified.

      • getRequestURI

        public URI getRequestURI()
        Returns the request object URI. Corresponds to the optional request_uri parameter.
        Returns:
        The request object URI, null if not specified.

      • specifiesRequestObject

        public boolean specifiesRequestObject()
        Returns true if this is a JWT secured authentication request.
        Returns:
        true if a request object via a request or request_uri parameter is specified, else false.

      • getPrompt

        public Prompt getPrompt()
        Returns the requested prompt. Corresponds to the optional prompt parameter.
        Returns:
        The requested prompt, null if not specified.

      • getTrustChain

        public TrustChain getTrustChain()
        Returns the OpenID Connect Federation 1.0 trust chain.
        Returns:
        The trust chain, null if not specified.

      • getCustomParameters

        public Map<String,​List<String>> getCustomParameters()
        Returns the additional custom parameters.
        Returns:
        The additional custom parameters as a unmodifiable map, empty map if none.

      • getCustomParameter

        public List<String> getCustomParameter​(String name)
        Returns the specified custom parameter.
        Parameters:
        name - The parameter name. Must not be null.
        Returns:
        The parameter value(s), null if not specified.

      • toParameters

        public Map<String,​List<String>> toParameters()
        Returns the URI query parameters for this authorisation request. Query parameters which are part of the authorisation endpoint are not included.

        Example parameters: 

         response_type = code
 client_id     = s6BhdRkqt3
 state         = xyz
 redirect_uri  = https://client.example.com/cb
        Returns:
        The parameters.

      • toJWTClaimsSet

        public com.nimbusds.jwt.JWTClaimsSet toJWTClaimsSet()
        Returns the parameters for this authorisation request as a JSON Web Token (JWT) claims set. Intended for creating a request object.
        Returns:
        The parameters as JWT claim set.

      • toQueryString

        public String toQueryString()
        Returns the URI query string for this authorisation request.

        Note that the '?' character preceding the query string in a URI is not included in the returned string.

        Example URI query string: 

         response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
        Returns:
        The URI query string.

      • toURI

        public URI toURI()
        Returns the complete URI representation for this authorisation request, consisting of the authorization endpoint URI with the query string appended.

        Example URI: 

         https://server.example.com/authorize?
 response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
        Returns:
        The URI representation.

      • toHTTPRequest

        public HTTPRequest toHTTPRequest​(HTTPRequest.Method method)
        Returns the matching HTTP request.
        Parameters:
        method - The HTTP request method which can be GET or POST. Must not be null.
        Returns:
        The HTTP request.

      • toHTTPRequest

        public HTTPRequest toHTTPRequest()
        Description copied from interface: Request
        Returns the matching HTTP request.
        Returns:
        The HTTP request.

      • parse

        public static AuthorizationRequest parse​(Map<String,​List<String>> params)
                                  throws ParseException
        Parses an authorisation request from the specified URI query parameters.

        Example parameters: 

         response_type = code
 client_id     = s6BhdRkqt3
 state         = xyz
 redirect_uri  = https://client.example.com/cb
        Parameters:
        params - The parameters. Must not be null.
        Returns:
        The authorisation request.
        Throws:
        ParseException - If the parameters couldn't be parsed to an authorisation request.

      • parse

        public static AuthorizationRequest parse​(URI uri,
                                         Map<String,​List<String>> params)
                                  throws ParseException
        Parses an authorisation request from the specified URI and query parameters.

        Example parameters: 

         response_type = code
 client_id     = s6BhdRkqt3
 state         = xyz
 redirect_uri  = https://client.example.com/cb
        Parameters:
        uri - The URI of the authorisation endpoint. May be null if the toHTTPRequest() method will not be used.
        params - The parameters. Must not be null.
        Returns:
        The authorisation request.
        Throws:
        ParseException - If the parameters couldn't be parsed to an authorisation request.

      • parse

        public static AuthorizationRequest parse​(String query)
                                  throws ParseException
        Parses an authorisation request from the specified URI query string.

        Example URI query string: 

         response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
        Parameters:
        query - The URI query string. Must not be null.
        Returns:
        The authorisation request.
        Throws:
        ParseException - If the query string couldn't be parsed to an authorisation request.

      • parse

        public static AuthorizationRequest parse​(URI uri,
                                         String query)
                                  throws ParseException
        Parses an authorisation request from the specified URI and query string.

        Example URI query string: 

         response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
        Parameters:
        uri - The URI of the authorisation endpoint. May be null if the toHTTPRequest() method will not be used.
        query - The URI query string. Must not be null.
        Returns:
        The authorisation request.
        Throws:
        ParseException - If the query string couldn't be parsed to an authorisation request.

      • parse

        public static AuthorizationRequest parse​(URI uri)
                                  throws ParseException
        Parses an authorisation request from the specified URI.

        Example URI: 

         https://server.example.com/authorize?
 response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
        Parameters:
        uri - The URI. Must not be null.
        Returns:
        The authorisation request.
        Throws:
        ParseException - If the URI couldn't be parsed to an authorisation request.

      • parse

        public static AuthorizationRequest parse​(HTTPRequest httpRequest)
                                  throws ParseException
        Parses an authorisation request from the specified HTTP request.

        Example HTTP request (GET): 

         https://server.example.com/authorize?
 response_type=code
 &client_id=s6BhdRkqt3
 &state=xyz
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
        Parameters:
        httpRequest - The HTTP request. Must not be null.
        Returns:
        The authorisation request.
        Throws:
        ParseException - If the HTTP request couldn't be parsed to an authorisation request.