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

    • getAuthorizationDetails

      public List<AuthorizationDetail> getAuthorizationDetails()
      Returns the Rich Authorisation Request (RAR) details.
      Returns:
      The authorisation details, 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.

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