IDW Gateway Error handling

When performing a user verification transaction via Gateway, Iddataweb's
AXN application will handle the browser interaction steps via
/authorize, /token and /userinfo endpoints. In the event that the AXN
encounters an error, it will:

By default, the AXN will display an error description with

information about what went wrong within our own UI.
If the service is configured to redirect on error, the frontend will

redirect to the preconfigured callback URL with an error code
(error) and error description (error_description) matching OIDC
spec as below. To enable this feature, please speak to your
solution architect.

Gateway redirect Error Codes

In the Gateway use case, we use either SAML or OIDC spec to authenticate
with the correct IDP and then return results. For SP initiated OIDC, IDW
adheres to both the OpenID Connect (OIDC) error handling specification
and the OAuth error handling compliance standards.

Example redirect:

HTTP/1.1 302 Found
Location: <https://client.example.org/>?
error=invalid_request
&error_description=
missing%20parameter%20in%20request%20asi%208df82ee6-2cf1-4559-a0e7-82d7736dbbe3

"error" Is the standardized error code, as listed in the table

below.
"error_description" This field provides detailed information

about what went wrong, and potential remedies. asi or
reference_id is attached at the end of the description as a
reference for further troubleshooting. (Note: The error
description list below is only a set of common examples and is not
a complete list)

  <th>
    Endpoint
  </th>

  <th>
    Error Code
  </th>

  <th>
    Meaning
  </th>

  <th>
    Error Causes and Descriptions
  </th>
</tr>

  <td>
    /authorize
  </td>

  <td>
    invalid\_request\_uri
  </td>

  <td>
    The request\_uri in the Authorization Request returns an error or contains invalid data.
  </td>

  <td>
    • Invalid redirect URI (No redirect - We will display error page) <br> • Missing URI parameter response\_type <br> • Missing required URI parameter scope <br> • Invalid redirect URI <br> • Missing grant type (No redirect - token endpoint) <br> • Invalid grant type (No redirect - token endpoint)
  </td>
</tr>

<tr>
  <td>
    OIDC
  </td>

  <td>
    /authorize
  </td>

  <td>
    invalid\_request\_object
  </td>

  <td>
    The request parameter contains an invalid Request object.
  </td>

  <td>
    • Invalid token in request (No redirect - token endpoint only) <br> • Token expired in request (No redirect - token endpoint only)
  </td>
</tr>

<tr>
  <td>
    OIDC
  </td>

  <td>
    /userinfo
  </td>

  <td>
    invalid\_token
  </td>

  <td>
    The request tried to use an invalid OIDC token
  </td>

  <td>
    • The access token is not valid. (No redirect - userinfo endpoint only) <br> • The access token has expired. (No redirect - userinfo endpoint only)
  </td>
</tr>

<tr>
  <td>
    OAuth 2.0
  </td>

  <td>
    /authorize
  </td>

  <td>
    invalid\_request
  </td>

  <td>
    The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
  </td>

  <td>
    • Missing parameter in request <br> • Parameter in request has invalid value <br> • Refreshing a page during the verification process <br> • Clicking on back button during verification process <br> • Copying a URL during verification and reusing it in another browser or tab <br> • Tampering with state parameters in requests <br> • INVALID\_ASI: The session information is not valid. This could be because the session has expired, the session information was never valid, or an illegal step was attempted, making the session information invalid. Please start a new session and ensure you follow the correct steps. <br> • INVALID\_TOKEN: The token is not valid. This could be because the token has already been consumed, was never valid in the first place, or is invalid due to a page refresh or clicking the back button. Please start a new session and avoid refreshing the page or using the back button.
  </td>
</tr>

<tr>
  <td>
    OAuth 2.0
  </td>

  <td>
    /authorize
  </td>

  <td>
    unauthorized\_client
  </td>

  <td>
    The client is not authorized to request an authorization code using this method.
  </td>

  <td>
    • Client ID is invalid, we cannot redirect - User will see error page
  </td>
</tr>

<tr>
  <td>
    OAuth 2.0
  </td>

  <td>
    /authorize
  </td>

  <td>
    invalid\_scope
  </td>

  <td>
    The requested scope is invalid, unknown, or malformed.
  </td>

  <td>
    • IDP not configured or wrong idp used in the URL - error\_description=Missing scope - missing idp configuration
  </td>
</tr>

<tr>
  <td>
    OAuth 2.0
  </td>

  <td>
    /authorize
  </td>

  <td>
    server\_error
  </td>

  <td>
    The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
  </td>

  <td>
    • JWT not valid/incomplete returns a description - “JWT signature does not match locally computed signature. JWT validity cannot be asserted and should not be trusted” <br> • Improper JWT returns a description as - “JWT strings must contain exactly 2 period characters.” <br> • Expired JWT <br> • JWT string has a digest/signature, but the header does not reference a valid signature algorithm <br> • Unable to read JSON value <br> • JWT string is missing a body/payload <br> • Unsigned Claims JWTs are not supported <br> • An unknown error occurred <br> • Refreshing a page during the verification process <br> • Clicking on back button during verification process <br> • Copying a URL during verification and reusing it in another browser or tab <br> • Tampering with state parameters in requests
  </td>
</tr>

<tr>
  <td>
    IDW
  </td>

  <td>
    /authorize
  </td>

  <td>
    invalid\_login\_hint
  </td>

  <td>
    The login hint value was not valid.
  </td>

  <td>
    • login\_hint supports 3 methods (unencrypted, signed or secured), using these incorrectly will cause an error <br> • If login\_hint feature is not enabled, using it during verification will return an error
  </td>
</tr>

Spec
OIDC

Consult Section
[3.1.2.6]{.underline}
of OpenID Connect Core 1.0 specification and section
[4.1.2.1]{.underline}
of The OAuth 2.0 Authorization Framework.