Package com.nimbusds.openid.connect.sdk

Class AuthenticationRequest

  • All Implemented Interfaces:
    Message, Request
    @Immutable
public class AuthenticationRequest
extends AuthorizationRequest
    OpenID Connect authentication request. Intended to authenticate an end-user and request the end-user's authorisation to release information to the client. Supports custom request parameters.

    Example HTTP request (code flow): 

     https://server.example.com/op/authorize?
 response_type=code%20id_token
 &client_id=s6BhdRkqt3
 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
 &scope=openid
 &nonce=n-0S6_WzA2Mj
 &state=af0ifjsldkj

    Related specifications:

    • OpenID Connect Core 1.0, section 3.1.2.1.
    • Proof Key for Code Exchange by OAuth Public Clients (RFC 7636).
    • Resource Indicators for OAuth 2.0 (RFC 8707)
    • The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR) draft-ietf-oauth-jwsreq-21
    • Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)
    • OpenID Connect for Identity Assurance 1.0, section 8.

    • Constructor Detail

      • AuthenticationRequest

        public AuthenticationRequest​(URI uri,
                             ResponseType rt,
                             Scope scope,
                             ClientID clientID,
                             URI redirectURI,
                             State state,
                             Nonce nonce)
        Creates a new minimal OpenID Connect authentication request.
        Parameters:
        uri - The URI of the OAuth 2.0 authorisation endpoint. May be null if the AuthorizationRequest.toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        rt - The response type. Corresponds to the response_type parameter. Must specify a valid OpenID Connect response type. Must not be null.
        scope - The request scope. Corresponds to the scope parameter. Must contain an openid value. Must not be null.
        clientID - The client identifier. Corresponds to the client_id parameter. Must not be null.
        redirectURI - The redirection URI. Corresponds to the redirect_uri parameter. Must not be null.
        state - The state. Corresponds to the state parameter. May be null.
        nonce - The nonce. Corresponds to the nonce parameter. May be null for code flow.

      • AuthenticationRequest

        public AuthenticationRequest​(URI uri,
                             ResponseType rt,
                             ResponseMode rm,
                             Scope scope,
                             ClientID clientID,
                             URI redirectURI,
                             State state,
                             Nonce nonce,
                             Display display,
                             Prompt prompt,
                             int maxAge,
                             List<com.nimbusds.langtag.LangTag> uiLocales,
                             List<com.nimbusds.langtag.LangTag> claimsLocales,
                             com.nimbusds.jwt.JWT idTokenHint,
                             String loginHint,
                             List<ACR> acrValues,
                             ClaimsRequest claims,
                             String purpose,
                             com.nimbusds.jwt.JWT requestObject,
                             URI requestURI,
                             CodeChallenge codeChallenge,
                             CodeChallengeMethod codeChallengeMethod,
                             List<URI> resources,
                             boolean includeGrantedScopes,
                             Map<String,​List<String>> customParams)
        Creates a new OpenID Connect authentication request with extension and custom parameters.
        Parameters:
        uri - The URI of the OAuth 2.0 authorisation endpoint. May be null if the AuthorizationRequest.toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        rt - The response type set. Corresponds to the response_type parameter. Must specify a valid OpenID Connect response type. 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).
        scope - The request scope. Corresponds to the scope parameter. Must contain an openid value. Must not be null.
        clientID - The client identifier. Corresponds to the client_id parameter. Must not be null.
        redirectURI - The redirection URI. Corresponds to the redirect_uri parameter. Must not be null unless set by means of the optional request_object / request_uri parameter.
        state - The state. Corresponds to the recommended state parameter. null if not specified.
        nonce - The nonce. Corresponds to the nonce parameter. May be null for code flow.
        display - The requested display type. Corresponds to the optional display parameter. null if not specified.
        prompt - The requested prompt. Corresponds to the optional prompt parameter. null if not specified.
        maxAge - The required maximum authentication age, in seconds. Corresponds to the optional max_age parameter. -1 if not specified, zero implies prompt=login.
        uiLocales - The preferred languages and scripts for the user interface. Corresponds to the optional ui_locales parameter. null if not specified.
        claimsLocales - The preferred languages and scripts for claims being returned. Corresponds to the optional claims_locales parameter. null if not specified.
        idTokenHint - The ID Token hint. Corresponds to the optional id_token_hint parameter. null if not specified.
        loginHint - The login hint. Corresponds to the optional login_hint parameter. null if not specified.
        acrValues - The requested Authentication Context Class Reference values. Corresponds to the optional acr_values parameter. null if not specified.
        claims - The individual claims to be returned. Corresponds to the optional claims parameter. null if not specified.
        purpose - The transaction specific purpose, null if not specified.
        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.
        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.
        customParams - Additional custom parameters, empty map or null if none.

    • Method Detail

      • getRegisteredParameterNames

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

      • getNonce

        public Nonce getNonce()
        Gets the nonce. Corresponds to the conditionally optional nonce parameter.
        Returns:
        The nonce, null if not specified.

      • getDisplay

        public Display getDisplay()
        Gets the requested display type. Corresponds to the optional display parameter.
        Returns:
        The requested display type, null if not specified.

      • getMaxAge

        public int getMaxAge()
        Gets the required maximum authentication age. Corresponds to the optional max_age parameter.
        Returns:
        The maximum authentication age, in seconds; -1 if not specified, zero implies prompt=login.

      • getUILocales

        public List<com.nimbusds.langtag.LangTag> getUILocales()
        Gets the end-user's preferred languages and scripts for the user interface, ordered by preference. Corresponds to the optional ui_locales parameter.
        Returns:
        The preferred UI locales, null if not specified.

      • getClaimsLocales

        public List<com.nimbusds.langtag.LangTag> getClaimsLocales()
        Gets the end-user's preferred languages and scripts for the claims being returned, ordered by preference. Corresponds to the optional claims_locales parameter.
        Returns:
        The preferred claims locales, null if not specified.

      • getIDTokenHint

        public com.nimbusds.jwt.JWT getIDTokenHint()
        Gets the ID Token hint. Corresponds to the conditionally optional id_token_hint parameter.
        Returns:
        The ID Token hint, null if not specified.

      • getLoginHint

        public String getLoginHint()
        Gets the login hint. Corresponds to the optional login_hint parameter.
        Returns:
        The login hint, null if not specified.

      • getACRValues

        public List<ACR> getACRValues()
        Gets the requested Authentication Context Class Reference values. Corresponds to the optional acr_values parameter.
        Returns:
        The requested ACR values, null if not specified.

      • getClaims

        public ClaimsRequest getClaims()
        Gets the individual claims to be returned. Corresponds to the optional claims parameter.
        Returns:
        The individual claims to be returned, null if not specified.

      • getPurpose

        public String getPurpose()
        Gets the transaction specific purpose. Corresponds to the optional purpose parameter.
        Returns:
        The purpose, null if not specified.

      • toParameters

        public Map<String,​List<String>> toParameters()
        Description copied from class: AuthorizationRequest
        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
        Overrides:
        toParameters in class AuthorizationRequest
        Returns:
        The parameters.

      • toJWTClaimsSet

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

      • parse

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

        Example parameters: 

         response_type = token id_token
 client_id     = s6BhdRkqt3
 redirect_uri  = https://client.example.com/cb
 scope         = openid profile
 state         = af0ifjsldkj
 nonce         = -0S6_WzA2Mj
        Parameters:
        params - The parameters. Must not be null.
        Returns:
        The OpenID Connect authentication request.
        Throws:
        ParseException - If the parameters couldn't be parsed to an OpenID Connect authentication request.

      • parse

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

        Example parameters: 

         response_type = token id_token
 client_id     = s6BhdRkqt3
 redirect_uri  = https://client.example.com/cb
 scope         = openid profile
 state         = af0ifjsldkj
 nonce         = -0S6_WzA2Mj
        Parameters:
        uri - The URI of the OAuth 2.0 authorisation endpoint. May be null if the AuthorizationRequest.toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        params - The parameters. Must not be null.
        Returns:
        The OpenID Connect authentication request.
        Throws:
        ParseException - If the parameters couldn't be parsed to an OpenID Connect authentication request.

      • parse

        public static AuthenticationRequest parse​(String query)
                                   throws ParseException
        Parses an OpenID Connect authentication request from the specified URI query string.

        Example URI query string: 

         response_type=token%20id_token
 &client_id=s6BhdRkqt3
 &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
 &scope=openid%20profile
 &state=af0ifjsldkj
 &nonce=n-0S6_WzA2Mj
        Parameters:
        query - The URI query string. Must not be null.
        Returns:
        The OpenID Connect authentication request.
        Throws:
        ParseException - If the query string couldn't be parsed to an OpenID Connect authentication request.

      • parse

        public static AuthenticationRequest parse​(URI uri,
                                          String query)
                                   throws ParseException
        Parses an OpenID Connect authentication request from the specified URI query string.

        Example URI query string: 

         response_type=token%20id_token
 &client_id=s6BhdRkqt3
 &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
 &scope=openid%20profile
 &state=af0ifjsldkj
 &nonce=n-0S6_WzA2Mj
        Parameters:
        uri - The URI of the OAuth 2.0 authorisation endpoint. May be null if the AuthorizationRequest.toHTTPRequest(com.nimbusds.oauth2.sdk.http.HTTPRequest.Method) method will not be used.
        query - The URI query string. Must not be null.
        Returns:
        The OpenID Connect authentication request.
        Throws:
        ParseException - If the query string couldn't be parsed to an OpenID Connect authentication request.

      • parse

        public static AuthenticationRequest parse​(URI uri)
                                   throws ParseException
        Parses an OpenID Connect authentication request from the specified URI.

        Example URI: 

         https://server.example.com/authorize?
 response_type=token%20id_token
 &client_id=s6BhdRkqt3
 &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
 &scope=openid%20profile
 &state=af0ifjsldkj
 &nonce=n-0S6_WzA2Mj
        Parameters:
        uri - The URI. Must not be null.
        Returns:
        The OpenID Connect authentication request.
        Throws:
        ParseException - If the query string couldn't be parsed to an OpenID Connect authentication request.

      • parse

        public static AuthenticationRequest parse​(HTTPRequest httpRequest)
                                   throws ParseException
        Parses an authentication request from the specified HTTP GET or HTTP POST request.

        Example HTTP request (GET): 

         https://server.example.com/op/authorize?
 response_type=code%20id_token
 &client_id=s6BhdRkqt3
 &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
 &scope=openid
 &nonce=n-0S6_WzA2Mj
 &state=af0ifjsldkj
        Parameters:
        httpRequest - The HTTP request. Must not be null.
        Returns:
        The OpenID Connect authentication request.
        Throws:
        ParseException - If the HTTP request couldn't be parsed to an OpenID Connect authentication request.