Online Authentication Events 

This specification provides details and schemas of authentication-related events available by the platform to the issuer.

These events cover the authentication flow and client registration lifecycle, including:

  • ClientRegistered
  • ClientDeleted
  • AuthenticationRequested
  • AuthenticationStarted
  • AuthenticationSuccessful
  • AuthenticationDeclined
  • AuthenticationTimedOut
  • AuthenticationFailed

Event Delivery model 

Events are pushed as opposed to traditional pulling. Customers are expected to expose endpoints to receive events with the following constraints:

  • HTTP POST + JSON content
  • Authentication supported is mTLS and/or oAuth2 The delivery model is At least once delivery which means that at events will be delivered at least once within reasonable time. Endpoints are however expected to be idempotent and tolerant reader to support forward compatibility.

Retry Logic and Retention 

After forwarding an event to the Issuer, the Event hub implements the following retry logic depending on the HTTP response from the Issuer's Backend:

  • An HTTP 2xx response acknowledges reception of the event. Endpoint must ensure storage or full business processing before acknowledgement.
  • An HTTP 4xx response from Issuer will either retry or abort. This is configurable.
  • An HTTP 5xx response will always retry. If the Event hub fails to notify a subscriber endpoint, it will retry calling the subscriber endpoint with a default retry frequency once per second; retries continue for a retry limit of 2 hours. If the subscriber cannot be notified after 2 hours, an alarm is raised requiring manual intervention to resolve. Resolution involves correcting the issue that is preventing events from being sent to the subscriber, and then resending all events going back to the time of initial failure. This may include resending events which were properly sent if the initial failure was intermittent. As the same event may be re-sent multiple times during resolution, the subscriber endpoint’s handling of an event must be idempotent. Resolution must be completed within the retention period, which is 1 day by default, otherwise the events are permanently lost.

Note 

The retry frequency is configurable and is intended to prevent retries from overwhelming the Issuer’s subscriber endpoints. The default is 1 retry per second. The 2-hour retry limit is enforced by the Event hub and cannot be increased. The retention period is configurable and is intended to limit data retention. The default is 1 day.

Event structure 

All event are structured in the same manner

  1. Common header
  2. Specific payload depending on the event type

Subscription model 

The customer must define a subscriber endpoint each event they want to be notified about. IDEMIA will register each endpoint with the Event Hub on request to our SRE team.

Online Authentication Related Events 

Know where is user during online authentication process

In order to make use of the API, please log in

Download dc-authenticate\Auth-Events.json