Package com.nimbusds.oauth2.sdk.token

Class DPoPTokenError

  • @Immutable
public class DPoPTokenError
extends ErrorObject
    OAuth 2.0 DPoP token error. Used to indicate that access to a resource protected by a DPoP access token is denied, due to the request, token or DPoP proof being invalid, or due to the access token having insufficient scope.

    Standard DPoP access token errors:

    Example HTTP response: 

     HTTP/1.1 401 Unauthorized
 WWW-Authenticate: DPoP realm="example.com",
                   error="invalid_token",
                   error_description="The access token expired"

    Related specifications:

    • OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) (draft-ietf-oauth-dpop-03), section 7.1.
    • Hypertext Transfer Protocol (HTTP/1.1): Authentication (RFC 7235), section 4.1.

    • Field Detail

      • MISSING_TOKEN

        public static final DPoPTokenError MISSING_TOKEN
        The request does not contain an access token. No error code or description is specified for this error, just the HTTP status code is set to 401 (Unauthorized).

        Example: 

         HTTP/1.1 401 Unauthorized
 WWW-Authenticate: DPoP

      • INVALID_REQUEST

        public static final DPoPTokenError INVALID_REQUEST
        The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed. The HTTP status code is set to 400 (Bad Request).

      • INVALID_TOKEN

        public static final DPoPTokenError INVALID_TOKEN
        The access token provided is expired, revoked, malformed, or invalid for other reasons. The HTTP status code is set to 401 (Unauthorized).

      • INSUFFICIENT_SCOPE

        public static final DPoPTokenError INSUFFICIENT_SCOPE
        The request requires higher privileges than provided by the access token. The HTTP status code is set to 403 (Forbidden).

      • INVALID_DPOP_PROOF

        public static final DPoPTokenError INVALID_DPOP_PROOF
        The request has a DPoP proof that is invalid. The HTTP status code is set to 401 (Unauthorized).

    • Constructor Detail

      • DPoPTokenError

        public DPoPTokenError​(String code,
                      String description)
        Creates a new OAuth 2.0 DPoP token error with the specified code and description.
        Parameters:
        code - The error code, null if not specified.
        description - The error description, null if not specified.

      • DPoPTokenError

        public DPoPTokenError​(String code,
                      String description,
                      int httpStatusCode)
        Creates a new OAuth 2.0 DPoP token error with the specified code, description and HTTP status code.
        Parameters:
        code - The error code, null if not specified.
        description - The error description, null if not specified.
        httpStatusCode - The HTTP status code, zero if not specified.

      • DPoPTokenError

        public DPoPTokenError​(String code,
                      String description,
                      int httpStatusCode,
                      URI uri,
                      String realm,
                      Scope scope)
        Creates a new OAuth 2.0 DPoP token error with the specified code, description, HTTP status code, page URI, realm and scope.
        Parameters:
        code - The error code, null if not specified.
        description - The error description, null if not specified.
        httpStatusCode - The HTTP status code, zero if not specified.
        uri - The error page URI, null if not specified.
        realm - The realm, null if not specified.
        scope - The required scope, null if not specified.

      • DPoPTokenError

        public DPoPTokenError​(String code,
                      String description,
                      int httpStatusCode,
                      URI uri,
                      String realm,
                      Scope scope,
                      Set<com.nimbusds.jose.JWSAlgorithm> jwsAlgs)
        Creates a new OAuth 2.0 DPoP token error with the specified code, description, HTTP status code, page URI, realm and scope.
        Parameters:
        code - The error code, null if not specified.
        description - The error description, null if not specified.
        httpStatusCode - The HTTP status code, zero if not specified.
        uri - The error page URI, null if not specified.
        realm - The realm, null if not specified.
        scope - The required scope, null if not specified.
        jwsAlgs - The acceptable JWS algorithms, null if not specified.

    • Method Detail

      • setDescription

        public DPoPTokenError setDescription​(String description)
        Description copied from class: ErrorObject
        Sets the error description.
        Parameters:
        description - The error description, null if not specified.
        Returns:
        A copy of this error with the specified description.

      • appendDescription

        public DPoPTokenError appendDescription​(String text)
        Description copied from class: ErrorObject
        Appends the specified text to the error description.
        Parameters:
        text - The text to append to the error description, null if not specified.
        Returns:
        A copy of this error with the specified appended description.

      • setHTTPStatusCode

        public DPoPTokenError setHTTPStatusCode​(int httpStatusCode)
        Description copied from class: ErrorObject
        Sets the HTTP status code.
        Parameters:
        httpStatusCode - The HTTP status code, zero if not specified.
        Returns:
        A copy of this error with the specified HTTP status code.

      • setURI

        public DPoPTokenError setURI​(URI uri)
        Description copied from class: ErrorObject
        Sets the error page URI.
        Parameters:
        uri - The error page URI, null if not specified.
        Returns:
        A copy of this error with the specified page URI.

      • setRealm

        public DPoPTokenError setRealm​(String realm)
        Sets the realm.
        Parameters:
        realm - realm, null if not specified.
        Returns:
        A copy of this error with the specified realm.

      • setScope

        public DPoPTokenError setScope​(Scope scope)
        Sets the required scope.
        Parameters:
        scope - The required scope, null if not specified.
        Returns:
        A copy of this error with the specified required scope.

      • getJWSAlgorithms

        public Set<com.nimbusds.jose.JWSAlgorithm> getJWSAlgorithms()
        Returns the acceptable JWS algorithms.
        Returns:
        The acceptable JWS algorithms, null if not specified.

      • setJWSAlgorithms

        public DPoPTokenError setJWSAlgorithms​(Set<com.nimbusds.jose.JWSAlgorithm> jwsAlgs)
        Sets the acceptable JWS algorithms.
        Parameters:
        jwsAlgs - The acceptable JWS algorithms, null if not specified.
        Returns:
        A copy of this error with the specified acceptable JWS algorithms.

      • toWWWAuthenticateHeader

        public String toWWWAuthenticateHeader()
        Returns the WWW-Authenticate HTTP response header code for this DPoP access token error response.

        Example: 

         DPoP realm="example.com", error="invalid_token", error_description="Invalid access token"
        Returns:
        The Www-Authenticate header value.

      • parse

        public static DPoPTokenError parse​(String wwwAuth)
                            throws ParseException
        Parses an OAuth 2.0 DPoP token error from the specified HTTP response WWW-Authenticate header.
        Parameters:
        wwwAuth - The WWW-Authenticate header value to parse. Must not be null.
        Returns:
        The DPoP token error.
        Throws:
        ParseException - If the WWW-Authenticate header value couldn't be parsed to a DPoP token error.

      • isScopeWithValidChars

        public static boolean isScopeWithValidChars​(Scope scope)
        Returns true if the specified scope consists of valid characters. Values for the "scope" attributes must not include characters outside the [0x20, 0x21] | [0x23 - 0x5B] | [0x5D - 0x7E] range. See RFC 6750, section 3.
        Parameters:
        scope - The scope.
        Returns:
        true if the scope contains valid characters, else false.
        See Also:
        ErrorObject.isLegal(String)

      • getScheme

        public AccessTokenType getScheme()
        Returns the token scheme.
        Returns:
        The token scheme.

      • getRealm

        public String getRealm()
        Returns the realm.
        Returns:
        The realm, null if not specified.

      • getScope

        public Scope getScope()
        Returns the required scope.
        Returns:
        The required scope, null if not specified.