Package com.nimbusds.oauth2.sdk

Class AuthorizationRequest

java.lang.Object
com.nimbusds.oauth2.sdk.AbstractRequest
com.nimbusds.oauth2.sdk.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).
  • 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) (draft-ietf-oauth-dpop-11).

  • Field Details

    • prompt

      protected final Prompt prompt
      The requested prompt (optional).

  • Constructor Details

    • AuthorizationRequest

      public AuthorizationRequest(URI uri, ResponseType rt, ClientID clientID)
      Creates a new minimal 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.
      clientID - The client identifier. Corresponds to the client_id parameter. Must not be null.

    • 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 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

      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)
      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.
      customParams - Custom parameters, empty map or null if none.

  • Method Details

    • 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.

    • getResponseType

      public ResponseType getResponseType()
      Returns the response type. Corresponds to the response_type parameter.
      Returns:
      The response type, may be null for a JWT secured authorisation request with a request or request_uri parameter.

    • 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.

    • getCodeChallengeMethod

      public CodeChallengeMethod getCodeChallengeMethod()
      Returns the code challenge method for PKCE.
      Returns:
      The code challenge method, 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.

    • getDPoPJWKThumbprintConfirmation

      public JWKThumbprintConfirmation getDPoPJWKThumbprintConfirmation()
      Returns the DPoP JWK SHA-256 thumbprint.
      Returns:
      The DPoP JWK SHA-256 thumbprint, 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 an 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.