Package org.forgerock.http.oauth2

Class 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 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 Detail

      • bestEffortResourceServerError

        public static OAuth2Error bestEffortResourceServerError​(org.forgerock.http.protocol.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​(org.forgerock.http.protocol.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.

      • 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 org.forgerock.http.protocol.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.

      • toWWWAuthenticateHeader

        public String toWWWAuthenticateHeader()
        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.