Package com.nimbusds.oauth2.sdk.token

Class BearerTokenError

java.lang.Object

com.nimbusds.oauth2.sdk.ErrorObject

com.nimbusds.oauth2.sdk.token.BearerTokenError

@Immutable
public class BearerTokenError
extends ErrorObject

OAuth 2.0 bearer token error. Used to indicate that access to a resource protected by a Bearer access token is denied, due to the request or token being invalid, or due to the access token having insufficient scope.

Standard bearer access token errors:

• MISSING_TOKEN
• INVALID_REQUEST
• INVALID_TOKEN
• INSUFFICIENT_SCOPE

Example HTTP response:

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

Related specifications:

• OAuth 2.0 Bearer Token Usage (RFC 6750), section 3.1.
• Hypertext Transfer Protocol (HTTP/1.1): Authentication (RFC 7235), section 4.1.

Field Summary

Fields

Modifier and Type	Field	Description
static BearerTokenError	INSUFFICIENT_SCOPE	The request requires higher privileges than provided by the access token.
static BearerTokenError	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.
static BearerTokenError	INVALID_TOKEN	The access token provided is expired, revoked, malformed, or invalid for other reasons.
static BearerTokenError	MISSING_TOKEN	The request does not contain an access token.

Constructor Summary

Constructors

Constructor	Description
BearerTokenError(String code, String description)	Creates a new OAuth 2.0 bearer token error with the specified code and description.
BearerTokenError(String code, String description, int httpStatusCode)	Creates a new OAuth 2.0 bearer token error with the specified code, description and HTTP status code.
BearerTokenError(String code, String description, int httpStatusCode, URI uri, String realm, Scope scope)	Creates a new OAuth 2.0 bearer token error with the specified code, description, HTTP status code, page URI, realm and scope.

Method Summary

Modifier and Type	Method	Description
BearerTokenError	appendDescription(String text)	Appends the specified text to the error description.
String	getRealm()	Gets the realm.
Scope	getScope()	Gets the required scope.
static boolean	isCodeWithValidChars(String errorCode)	Returns true if the specified error code consists of valid characters.
static boolean	isDescriptionWithValidChars(String errorDescription)	Returns true if the specified error description consists of valid characters.
static boolean	isScopeWithValidChars(Scope scope)	Returns true if the specified scope consists of valid characters.
static BearerTokenError	parse(String wwwAuth)	Parses an OAuth 2.0 bearer token error from the specified HTTP response WWW-Authenticate header.
BearerTokenError	setDescription(String description)	Sets the error description.
BearerTokenError	setHTTPStatusCode(int httpStatusCode)	Sets the HTTP status code.
BearerTokenError	setRealm(String realm)	Sets the realm.
BearerTokenError	setScope(Scope scope)	Sets the required scope.
BearerTokenError	setURI(URI uri)	Sets the error page URI.
String	toWWWAuthenticateHeader()	Returns the WWW-Authenticate HTTP response header code for this bearer access token error response.

Methods inherited from class com.nimbusds.oauth2.sdk.ErrorObject

equals, getCode, getDescription, getHTTPStatusCode, getURI, hashCode, parse, parse, toJSONObject, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MISSING_TOKEN

public static final BearerTokenError 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: Bearer
 

INVALID_REQUEST

public static final BearerTokenError 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 BearerTokenError 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 BearerTokenError INSUFFICIENT_SCOPE

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

Constructor Detail

BearerTokenError

public BearerTokenError(String code,
                        String description)

Creates a new OAuth 2.0 bearer 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.

BearerTokenError

public BearerTokenError(String code,
                        String description,
                        int httpStatusCode)

Creates a new OAuth 2.0 bearer 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.

BearerTokenError

public BearerTokenError(String code,
                        String description,
                        int httpStatusCode,
                        URI uri,
                        String realm,
                        Scope scope)

Creates a new OAuth 2.0 bearer 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.

Method Detail

isCodeWithValidChars

public static boolean isCodeWithValidChars(String errorCode)

Returns true if the specified error code consists of valid characters. Values for the "error" and "error_description" attributes must not include characters outside the set %x20-21 / %x23-5B / %x5D-7E. See RFC 6750, section 3.

Parameters:

errorCode - The error code string.

Returns:

true if the error code string contains valid characters, else false.

isDescriptionWithValidChars

public static boolean isDescriptionWithValidChars(String errorDescription)

Returns true if the specified error description consists of valid characters. Values for the "error" and "error_description" attributes must not include characters outside the set %x20-21 / %x23-5B / %x5D-7E. See RFC 6750, section 3.

Parameters:

errorDescription - The error description string.

Returns:

true if the error description string contains valid characters, else false.

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 set %x21 / %x23-5B / %x5D-7E. See RFC 6750, section 3.

Parameters:

scope - The scope.

Returns:

true if the scope contains valid characters, else false.

setDescription

public BearerTokenError setDescription(String description)

Description copied from class: ErrorObject

Sets the error description.

Overrides:

setDescription in class ErrorObject

Parameters:

description - The error description, null if not specified.

Returns:

A copy of this error with the specified description.

appendDescription

public BearerTokenError appendDescription(String text)

Description copied from class: ErrorObject

Appends the specified text to the error description.

Overrides:

appendDescription in class ErrorObject

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 BearerTokenError setHTTPStatusCode(int httpStatusCode)

Description copied from class: ErrorObject

Sets the HTTP status code.

Overrides:

setHTTPStatusCode in class ErrorObject

Parameters:

httpStatusCode - The HTTP status code, zero if not specified.

Returns:

A copy of this error with the specified HTTP status code.

setURI

public BearerTokenError setURI(URI uri)

Description copied from class: ErrorObject

Sets the error page URI.

Overrides:

setURI in class ErrorObject

Parameters:

uri - The error page URI, null if not specified.

Returns:

A copy of this error with the specified page URI.

getRealm

public String getRealm()

Gets the realm.

Returns:

The realm, null if not specified.

setRealm

public BearerTokenError setRealm(String realm)

Sets the realm.

Parameters:

realm - realm, null if not specified.

Returns:

A copy of this error with the specified realm.

getScope

public Scope getScope()

Gets the required scope.

Returns:

The required scope, null if not specified.

setScope

public BearerTokenError 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.

toWWWAuthenticateHeader

public String toWWWAuthenticateHeader()

Returns the WWW-Authenticate HTTP response header code for this bearer access token error response.

Example:

 Bearer realm="example.com", error="invalid_token", error_description="Invalid access token"
 

Returns:

The Www-Authenticate header value.

parse

public static BearerTokenError parse(String wwwAuth)
                              throws ParseException

Parses an OAuth 2.0 bearer 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 bearer token error.

Throws:

ParseException - If the WWW-Authenticate header value couldn't be parsed to a Bearer token error.