Package org.forgerock.http.oauth2

Class OAuth2Error

java.lang.Object
org.forgerock.http.oauth2.OAuth2Error
All Implemented Interfaces:
Serializable
public final class OAuth2Error extends Object implements Serializable
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:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    E_ACCESS_DENIED
    The resource owner or authorization server denied the request.
    static final String
    E_INSUFFICIENT_SCOPE
    The request requires higher privileges than provided by the access token.
    static final String
    E_INVALID_CLIENT
    Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
    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.
    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.
    static final String
    E_INVALID_SCOPE
    The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
    static final String
    E_INVALID_TOKEN
    The access token provided is expired, revoked, malformed, or invalid for other reasons.
    static final String
    E_SERVER_ERROR
    The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
    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.
    static final String
    E_UNAUTHORIZED_CLIENT
    The authenticated client is not authorized to use this authorization grant type.
    static final String
    E_UNSUPPORTED_GRANT_TYPE
    The authorization grant type is not supported by the authorization server.
    static final String
    E_UNSUPPORTED_RESPONSE_TYPE
    The authorization server does not support obtaining an authorization code using this method.
    static final String
    F_ERROR
    The name of the field which communicates the error code.
    static final String
    F_ERROR_DESCRIPTION
    The name of the field which communicates the error description.
    static final String
    F_ERROR_URI
    The name of the field which communicates the error uri.
    static final String
    F_REALM
    The name of the field which communicates the realm.
    static final String
    F_SCOPE
    The name of the field which communicates the scope.
    static final String
    H_BEARER
    The WWW-Authenticate header prefix, 'Bearer'.

  • Method Summary

    Modifier and Type
    Method
    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 asWwwAuthenticateHeader() instead.
    static OAuth2Error
    valueOf(String s)
    Parses the provided 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 Details

  • Method Details

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