Angular-auth-oidc-client: Error handling support for better user experience

[GabrielGil]

Is your feature request related to a problem? Please describe.

I have successfully implemented this library in my project, however like in any other real-live app, errors do happen. Sometimes these errors are beyond the scope of our implementation, but still, they frustrate the experience of the users who do not know what to do.

Currently, when an error happens logging in the user is just redirected to the unauthorizedRoute with a generic "Unauthotized" message and error screen. There is no way to inform the user of what happened, since both this library, or the Authentication server may return an error.

I cannot find any mention to error handling in the docs.

Describe the solution you'd like
Ideally, this library offers a mechanism to access the error returned, wither in the subscription observer of the checkAuth method, or as an event, or any other way the responsible team consider.

The most common error that happens in our app is "iat validation", but we cannot identify this error and inform the users that their time is not correct, and they have to fix this. We noticed more people than expected have their system time set ahead, in order to be always on time for their meetings and appointments.

However, other errors are found such a code which was issued with a different state etc.

Moreover, OIDC spec defines a set of errors that the server may return, which ideally can be accessed through the library (error, error_description, error_uri, state).

Ref: https://openid.net/specs/openid-connect-core-1_0.html#AuthError

Describe alternatives you've considered

I thought about these possible solutions:

Subscriber observer error.

enum AuthenticationErrorCode {
  // From Section 4.1.2.1 of OAuth 2.0 [RFC6749] https://tools.ietf.org/html/rfc6749#section-4.1.2.1
  /** The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. */
  invalid_request,
  /** The client is not authorized to request an authorization code using this method. */
  unauthorized_client,
  /** The resource owner or authorization server denied the request. */
  access_denied,
  /** The authorization server does not support obtaining an authorization code using this method. */
  unsupported_response_type,
  /** The requested scope is invalid, unknown, or malformed. */
  invalid_scope,
  /** 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.) */
  server_error,
  /** 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.) */
  temporarily_unavailable,

  // From OIDC https://openid.net/specs/openid-connect-core-1_0.html#AuthError
  /** The Authorization Server requires End-User interaction of some form to proceed. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface for End-User interaction. */
  interaction_required, 
  /** The Authorization Server requires End-User authentication. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface for End-User authentication. */
  login_required, 
  /** The End-User is REQUIRED to select a session at the Authorization Server. The End-User MAY be authenticated at the Authorization Server with different associated accounts, but the End-User did not select a session. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface to prompt for a session to use. */
  account_selection_required, 
  /** The Authorization Server requires End-User consent. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface for End-User consent. */
  consent_required,
  /** The request_uri in the Authorization Request returns an error or contains invalid data. */
  invalid_request_uri,
  /** The request parameter contains an invalid Request Object. */
  invalid_request_object,
  /** The OP does not support use of the request parameter defined in Section 6. */
  request_not_supported,
  /** The OP does not support use of the request_uri parameter defined in Section 6. */
  request_uri_not_supported,
  /** The OP does not support use of the registration parameter defined in Section 7.2.1. */
  registration_not_supported,

  // From Angular Oidc Connect
  /** Validation, iat rejected id_token was issued too far away from the current time */
  invalid_iat_time,
  /** State of the client and code do not match */
  invalid_state_validation,
}

/** 
 * An Authentication Error Response is an OAuth 2.0 Authorization Error Response message returned from the 
 * OP's Authorization Endpoint in response to the Authorization Request message sent by the RP.
 */
interface AuthenticationError {
  /** Error code */
  error: AuthenticationErrorCode;
  /** Human-readable ASCII encoded text description of the error. */
  error_description?: string;
  /** URI of a web page that includes additional information about the error. */
  error_uri?: string;
  /** REQUIRED if the Authorization Request included the state parameter. Set to the value received from the Client. */
  state?: string;
}

// In app.module 
checkAuth()
.subscribe(
  () => console.log('Success'), 
  (error) => console.log('Error happened', error)
);

This error could be sent to the "Unauthorized" route using OidcService.lastError$ for instance, where the last error would be available so the route can either handle it, or display it to the user in a UX-friendly way.

[amiram]

We really need this. In order not to break current API, I suggest that checkAuth will only throw an error if a specific param was supplied.