OAuth2Error (OpenAM Server Only 6.5.5 Documentation)

java.lang.Object
- org.forgerock.http.oauth2.OAuth2Error

```
public final class OAuth2Error
extends Object
```
Describes an error which occurred during an OAuth 2.0 authorization request or when performing an authorized request. More specifically, errors are communicated:
- as query parameters in a failed authorization call-back. These errors are defined in RFC 6749 # 4.1.2 and comprise of an error code, optional error description, and optional error URI
- as JSON encoded content in a failed access token request or failed refresh token request. These errors are defined in RFC 6749 # 5.2 and comprise of an error code, optional error description, and optional error URI
- using the WWW-Authenticate response header in response to a failed attempt to access an OAuth 2.0 protected resource on a resource server. These errors are defined in RFC 6750 # 3.1 and comprise of an optional error code, optional error description, optional error URI, optional list of required scopes, and optional realm.
See Also:

RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, RFC 6749 # 5.2 - The OAuth 2.0 Authorization Framework, RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`E_ACCESS_DENIED` The resource owner or authorization server denied the request.
`static String`	`E_INSUFFICIENT_SCOPE` The request requires higher privileges than provided by the access token.
`static String`	`E_INVALID_CLIENT` Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
`static String`	`E_INVALID_GRANT` The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
`static String`	`E_INVALID_REQUEST` The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
`static String`	`E_INVALID_SCOPE` The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
`static String`	`E_INVALID_TOKEN` The access token provided is expired, revoked, malformed, or invalid for other reasons.
`static String`	`E_SERVER_ERROR` The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
`static String`	`E_TEMPORARILY_UNAVAILABLE` The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
`static String`	`E_UNAUTHORIZED_CLIENT` The authenticated client is not authorized to use this authorization grant type.
`static String`	`E_UNSUPPORTED_GRANT_TYPE` The authorization grant type is not supported by the authorization server.
`static String`	`E_UNSUPPORTED_RESPONSE_TYPE` The authorization server does not support obtaining an authorization code using this method.
`static String`	`F_ERROR` The name of the field which communicates the error code.
`static String`	`F_ERROR_DESCRIPTION` The name of the field which communicates the error description.
`static String`	`F_ERROR_URI` The name of the field which communicates the error uri.
`static String`	`F_REALM` The name of the field which communicates the realm.
`static String`	`F_SCOPE` The name of the field which communicates the scope.
`static String`	`H_BEARER` The WWW-Authenticate header prefix, 'Bearer'.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`WwwAuthenticateHeader`	`asWwwAuthenticateHeader()` Returns a representation of this error as a `WWW-Authenticate` header.
`static OAuth2Error`	`bestEffortResourceServerError(Status status, OAuth2Error incomplete)` Returns an OAuth 2.0 resource server error whose values are determined on a best-effort basis from the provided incomplete error and HTTP status code.
`boolean`	`equals(Object obj)`
`String`	`getError()` Returns the error code specifying the cause of the failure.
`String`	`getErrorDescription()` Returns the human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred.
`String`	`getErrorUri()` Returns a URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
`String`	`getRealm()` Returns the scope of protection required to access the protected resource.
`List<String>`	`getScope()` Returns the required scope of the access token for accessing the requested resource.
`int`	`hashCode()`
`boolean`	`is(String error)` Returns `true` if this error includes an error code and it matches the provided error code.
`static OAuth2Error`	`newAuthorizationServerError(String error, String errorDescription)` Returns an OAuth 2.0 error suitable for inclusion in authorization call-back responses and access token and refresh token responses.
`static OAuth2Error`	`newAuthorizationServerError(String error, String errorDescription, String errorUri)` Returns an OAuth 2.0 error suitable for inclusion in authorization call-back responses and access token and refresh token responses.
`static OAuth2Error`	`newResourceServerError(String realm, List<String> scope, String error, String errorDescription, String errorUri)` Returns an OAuth 2.0 error suitable for inclusion in resource server WWW-Authenticate response headers.
`Form`	`toForm()` Returns the form representation of this error suitable for inclusion in an authorization call-back query.
`Map<String,Object>`	`toJsonContent()` Returns the JSON representation of this error formatted as an access token error response.
`String`	`toString()`
`String`	`toWWWAuthenticateHeader()` Deprecated. Use `OAuth2Error.asWwwAuthenticateHeader()` instead.
`static OAuth2Error`	`valueOf(String s)` Parses the provided `OAuth2Error.toString()` representation as an OAuth 2.0 error.
`static OAuth2Error`	`valueOfForm(Form form)` Parses the Form representation of an authorization call-back error as an OAuth 2.0 error.
`static OAuth2Error`	`valueOfJsonContent(Map<String,Object> json)` Parses the JSON representation of an access token error response as an OAuth 2.0 error.
`static OAuth2Error`	`valueOfWWWAuthenticateHeader(String s)` Parses the provided WWW-Authenticate header content as an OAuth 2.0 error.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - E_ACCESS_DENIED
```
public static final String E_ACCESS_DENIED
```
    The resource owner or authorization server denied the request.
    
    See Also:
    
    RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_INSUFFICIENT_SCOPE
```
public static final String E_INSUFFICIENT_SCOPE
```
    The request requires higher privileges than provided by the access token. The resource server SHOULD respond with the HTTP 403 (Forbidden) status code and MAY include the "scope" attribute with the scope necessary to access the protected resource.
    
    See Also:
    
    RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage, Constant Field Values
  - E_INVALID_CLIENT
```
public static final String E_INVALID_CLIENT
```
    Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.
    
    See Also:
    
    RFC 6749 # 5.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_INVALID_GRANT
```
public static final String E_INVALID_GRANT
```
    The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
    
    See Also:
    
    RFC 6749 # 5.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_INVALID_REQUEST
```
public static final String E_INVALID_REQUEST
```
    The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. The resource server SHOULD respond with the HTTP 400 (Bad Request) status code.
    
    See Also:
    
    RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, RFC 6749 # 5.2 - The OAuth 2.0 Authorization Framework, RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage, Constant Field Values
  - E_INVALID_SCOPE
```
public static final String E_INVALID_SCOPE
```
    The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
    
    See Also:
    
    RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, RFC 6749 # 5.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_INVALID_TOKEN
```
public static final String E_INVALID_TOKEN
```
    The access token provided is expired, revoked, malformed, or invalid for other reasons. The resource SHOULD respond with the HTTP 401 (Unauthorized) status code. The client MAY request a new access token and retry the protected resource request.
    
    See Also:
    
    RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage, Constant Field Values
  - E_SERVER_ERROR
```
public static final String E_SERVER_ERROR
```
    The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
    
    See Also:
    
    RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_TEMPORARILY_UNAVAILABLE
```
public static final String E_TEMPORARILY_UNAVAILABLE
```
    The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)
    
    See Also:
    
    RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_UNAUTHORIZED_CLIENT
```
public static final String E_UNAUTHORIZED_CLIENT
```
    The authenticated client is not authorized to use this authorization grant type.
    
    See Also:
    
    RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, RFC 6749 # 5.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_UNSUPPORTED_GRANT_TYPE
```
public static final String E_UNSUPPORTED_GRANT_TYPE
```
    The authorization grant type is not supported by the authorization server.
    
    See Also:
    
    RFC 6749 # 5.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - E_UNSUPPORTED_RESPONSE_TYPE
```
public static final String E_UNSUPPORTED_RESPONSE_TYPE
```
    The authorization server does not support obtaining an authorization code using this method.
    
    See Also:
    
    RFC 6749 # 4.1.2 - The OAuth 2.0 Authorization Framework, Constant Field Values
  - F_ERROR
```
public static final String F_ERROR
```
    The name of the field which communicates the error code.
    
    See Also:
    
    Constant Field Values
  - F_ERROR_DESCRIPTION
```
public static final String F_ERROR_DESCRIPTION
```
    The name of the field which communicates the error description.
    
    See Also:
    
    Constant Field Values
  - F_ERROR_URI
```
public static final String F_ERROR_URI
```
    The name of the field which communicates the error uri.
    
    See Also:
    
    Constant Field Values
  - F_REALM
```
public static final String F_REALM
```
    The name of the field which communicates the realm.
    
    See Also:
    
    Constant Field Values
  - F_SCOPE
```
public static final String F_SCOPE
```
    The name of the field which communicates the scope.
    
    See Also:
    
    Constant Field Values
  - H_BEARER
```
public static final String H_BEARER
```
    The WWW-Authenticate header prefix, 'Bearer'.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - bestEffortResourceServerError
```
public static OAuth2Error bestEffortResourceServerError(Status status,
                                                        OAuth2Error incomplete)
```
    Returns an OAuth 2.0 resource server error whose values are determined on a best-effort basis from the provided incomplete error and HTTP status code.
    
    Parameters:
    
    status - The HTTP status code.
    
    incomplete - The incomplete and possibly null error.
    
    Returns:
    
    A non-null error whose error code has been determined from the HTTP status code.
  - newAuthorizationServerError
```
public static OAuth2Error newAuthorizationServerError(String error,
                                                      String errorDescription)
```
    Returns an OAuth 2.0 error suitable for inclusion in authorization call-back responses and access token and refresh token responses.
    
    Parameters:
    
    error - The error code specifying the cause of the failure.
    
    errorDescription - The human-readable ASCII text providing additional information, or null.
    
    Returns:
    
    The OAuth 2.0 error.
    
    Throws:
    
    NullPointerException - If error was null.
  - newAuthorizationServerError
```
public static OAuth2Error newAuthorizationServerError(String error,
                                                      String errorDescription,
                                                      String errorUri)
```
    Returns an OAuth 2.0 error suitable for inclusion in authorization call-back responses and access token and refresh token responses.
    
    Parameters:
    
    error - The error code specifying the cause of the failure.
    
    errorDescription - The human-readable ASCII text providing additional information, or null.
    
    errorUri - A URI identifying a human-readable web page with information about the error, or null.
    
    Returns:
    
    The OAuth 2.0 error.
    
    Throws:
    
    NullPointerException - If error was null.
  - newResourceServerError
```
public static OAuth2Error newResourceServerError(String realm,
                                                 List<String> scope,
                                                 String error,
                                                 String errorDescription,
                                                 String errorUri)
```
    Returns an OAuth 2.0 error suitable for inclusion in resource server WWW-Authenticate response headers.
    
    Parameters:
    
    realm - The scope of protection required to access the protected resource, or null.
    
    scope - The required scope(s) of the access token for accessing the requested resource, or null.
    
    error - The error code specifying the cause of the failure, or null.
    
    errorDescription - The human-readable ASCII text providing additional information, or null.
    
    errorUri - A URI identifying a human-readable web page with information about the error, or null.
    
    Returns:
    
    The OAuth 2.0 error.
  - valueOf
```
public static OAuth2Error valueOf(String s)
```
    Parses the provided OAuth2Error.toString() representation as an OAuth 2.0 error.
    
    Parameters:
    
    s - The string to parse.
    
    Returns:
    
    The parsed OAuth 2.0 error.
  - valueOfForm
```
public static OAuth2Error valueOfForm(Form form)
```
    Parses the Form representation of an authorization call-back error as an OAuth 2.0 error. Only the error, error description, and error URI fields will be included.
    
    Parameters:
    
    form - The Form representation of an authorization call-back error.
    
    Returns:
    
    The parsed OAuth 2.0 error.
  - valueOfJsonContent
```
public static OAuth2Error valueOfJsonContent(Map<String,Object> json)
```
    Parses the JSON representation of an access token error response as an OAuth 2.0 error. Only the error, error description, and error URI fields will be included.
    
    Parameters:
    
    json - The JSON representation of an access token error response.
    
    Returns:
    
    The parsed OAuth 2.0 error.
    
    Throws:
    
    IllegalArgumentException - If the JSON content was malformed.
  - valueOfWWWAuthenticateHeader
```
public static OAuth2Error valueOfWWWAuthenticateHeader(String s)
```
    Parses the provided WWW-Authenticate header content as an OAuth 2.0 error.
    
    Parameters:
    
    s - The string containing the WWW-Authenticate header content.
    
    Returns:
    
    The parsed OAuth 2.0 error.
    
    Throws:
    
    IllegalArgumentException - If the header value was malformed.
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - getError
```
public String getError()
```
    Returns the error code specifying the cause of the failure.
    
    Returns:
    
    The error code specifying the cause of the failure, or null if no error code was provided (which may be the case for WWW-Authenticate headers).
  - getErrorDescription
```
public String getErrorDescription()
```
    Returns the human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred.
    
    Returns:
    
    The human-readable ASCII text providing additional information, or null if no description was provided.
  - getErrorUri
```
public String getErrorUri()
```
    Returns a URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    
    Returns:
    
    A URI identifying a human-readable web page with information about the error, or null if no error URI was provided.
  - getRealm
```
public String getRealm()
```
    Returns the scope of protection required to access the protected resource. The realm is only included with WWW-Authenticate headers in response to a failure to access a protected resource.
    
    Returns:
    
    The scope of protection required to access the protected resource, or null if no realm was provided (which will always be the case for authorization call-back failures and access/refresh token requests).
  - getScope
```
public List<String> getScope()
```
    Returns the required scope of the access token for accessing the requested resource. The scope is only included with WWW-Authenticate headers in response to a failure to access a protected resource.
    
    Returns:
    
    The required scope of the access token for accessing the requested resource, which may be empty (never null) if no scope was provided (which will always be the case for authorization call-back failures and access/refresh token requests).
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - is
```
public boolean is(String error)
```
    Returns true if this error includes an error code and it matches the provided error code.
    
    Parameters:
    
    error - The error code.
    
    Returns:
    
    true if this error includes an error code and it matches the provided error code.
  - toForm
```
public Form toForm()
```
    Returns the form representation of this error suitable for inclusion in an authorization call-back query. Only the error, error description, and error URI fields will be included.
    
    Returns:
    
    The form representation of this error suitable for inclusion in an authorization call-back query.
  - toJsonContent
```
public Map<String,Object> toJsonContent()
```
    Returns the JSON representation of this error formatted as an access token error response. Only the error, error description, and error URI fields will be included.
    
    Returns:
    
    The JSON representation of this error formatted as an access token error response.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - toWWWAuthenticateHeader
```
@Deprecated
public String toWWWAuthenticateHeader()
```
    Deprecated. Use OAuth2Error.asWwwAuthenticateHeader() instead.
    
    Returns the string representation of this error formatted as a WWW-Authenticate header.
    
    Returns:
    
    The string representation of this error formatted as a WWW-Authenticate header.
  - asWwwAuthenticateHeader
```
public WwwAuthenticateHeader asWwwAuthenticateHeader()
```
    Returns a representation of this error as a WWW-Authenticate header.
    
    Returns:
    
    The representation of this error as a WWW-Authenticate header.

Class OAuth2Error

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

E_ACCESS_DENIED

E_INSUFFICIENT_SCOPE

E_INVALID_CLIENT

E_INVALID_GRANT

E_INVALID_REQUEST

E_INVALID_SCOPE

E_INVALID_TOKEN

E_SERVER_ERROR

E_TEMPORARILY_UNAVAILABLE

E_UNAUTHORIZED_CLIENT

E_UNSUPPORTED_GRANT_TYPE

E_UNSUPPORTED_RESPONSE_TYPE

F_ERROR

F_ERROR_DESCRIPTION

F_ERROR_URI

F_REALM

F_SCOPE

H_BEARER

Method Detail

bestEffortResourceServerError

newAuthorizationServerError

newAuthorizationServerError

newResourceServerError

valueOf

valueOfForm

valueOfJsonContent

valueOfWWWAuthenticateHeader

equals

getError

getErrorDescription

getErrorUri

getRealm

getScope

hashCode

is

toForm

toJsonContent

toString

toWWWAuthenticateHeader

asWwwAuthenticateHeader