Log Monitoring Best Practices

The HYPR platform has robust event logging across the event lifecycle for all registration and authentication activities. By monitoring the logs, customers can create trending reports on usage as well as alerts to identify critical failures at various points in the registration or authentication flow.

Success/Failure Monitoring
Additional Error Monitoring
Event Log Keys
Pseudocode for Querying Event Logs

Success/Failure Monitoring

HYPR recommends that you watch for anomalies in the volume of successful and failed registration/authentication events as the cornerstone of any log monitoring process.

📘

Note

We suggest you monitor for failures at the event level as opposed to the errorCode level. Since events traverse several different components, a failed event can result in several error codes because each component will present an error. This is helpful during the debugging process but results in noise when employed within an alerting mechanism.

As an example, here’s a monitor built with Datadog’s anomaly detection that evaluates two monitors grouped on the same key (eventtags).

26802680

There are two checks happening here:

  1. For a given registration or authentication event type, are we seeing an anomalous increase in the number of failed events (based on the isSuccessful key described in Event Log Keys below) over a certain time interval (in this case, 15 minutes). The anomaly algorithm used here employs the “robust” anomaly detection in Datadog. This checks to see if the behavior observed in the given time interval is more than two standard deviations from the behavior in previous weeks during the same time period. For instance, we should expect that 8:00 AM - 8:15 AM on a Monday behaves similarly to 8:00 AM - 8:15 AM over the past six Mondays.
  2. For a given registration or authentication event type, are we seeing an anomalous decrease in the number of successful events (based on the isSuccessful key again) over a certain time interval (in this case, 15 minutes). The anomaly detection algorithm described above is used here as well.

Both of these checks are evaluated in a composite monitor. Only if both of these checks are true will the monitor fire. Remember, it’s possible for there to be a legitimate drop in success volumes (for example, a holiday or a “soft launch” period), as well as an increase in failures that may simply be the result of an overall volume increase. However, if both of these issues occur simultaneously, an alert should be triggered.

Additional Error Monitoring

In addition to the success/failure event monitoring described above, there are certain other errors where any instance should trigger an alert.

Error Code/Name

Description

Recommended Solution

1203003
FIDO2_SETTINGS_NULL_EC

FIDO2 settings are null.

Please make sure FIDO2 settings are configured.

1202501
LICENSE_VALIDATION_PROBLEM

This indicates that the license validation has failed.

The administrator should check that the correct license has been provided.

1202027
PUSH_NOT_CONFIG_EC

There was an issue with push provider configuration. Either push is disabled or the url is null.

Check Control Center logs and contact HYPR support for assistance.

Event Log Keys

Below is a list of registration and authentication event log keys which are useful as dimensions and filters.

traceId
A unique representation of a single usage attempt in the HYPR platform. A single traceId can have several event logs associated with it.

spanId
The individual hops made by a given traceId through the platform. A single traceId will have several spanIds under it.

rpAppId
The ID for an RP Application, typically created via the HYPR Control Center. Each RP Application represents an separate integration (such as SSO web login or workstation unlock).

machineUserName
A unique identifier for an end user/rpAppId combination. Please note that if the same end user has registered for more than one integration within a given tenant, they will show up with two separate machineUserName values.

deviceId
An ID that uniquely identifies the device on which a user has registered.

machineId
An ID that uniquely identifies the workstation on which a user has registered.

isSuccessful
A boolean value that indicates whether or not the given event was successful. Please note that an unsuccessful event by itself does not necessarily indicate that the entire traceId failed. It is always best to look at the latest event log for a given trace to determine its status.

errorCode
The error code value presented in the case of an unsuccessful attempt.

mobileType
The mobile device type (iOS/Android) for the given deviceId. Please note that this is sometimes only populated during the registration event.

deviceRelVer
The version of HYPR running on the registered device. Please note that this is sometimes only populated during the registration event.

clientRelVer
The version of HYPR running on the registered workstation machine. Please note that this is sometimes only populated during the registration event.

eventTimeInUTC
The UTC timestamp for the event log.

eventName
The type of event that is occurring. There are several possible values for this field. Key values to search on are:

  • OOB_WEBSITE_REG: indicates the start of a web registration event
  • OOB_DEVICE_REG: indicates the start of a device registration (as part of a web registration attempt)
  • OOB_DEVICE_REG_COMPLETE: indicates the successful completion of a web registration event
  • OOB_WEBSITE_AUTH: indicates the start of a web authentication event
  • OOB_WEBSTIE_AUTH_COMPLETE: indicates the successful completion of a web authentication event
  • SMARTKEY_ENROLL: indicates either successful or failed (via isSuccessful) smart key registration (note that at this time there is no event to indicate a Smart Key authentication)
  • FIDO2_DEVICE_REG_COMPLETE: indicates successful FIDO2 device registration event (note that this time there is no event indicating a failed FIDO2 device reg)
  • FIDO2_WEBAUTHN_COMPLETE: indicates successful FIDO2 web authentication event (note that at this time there is no event indicating a failed FIDO2 web authentication)

Pseudocode for Querying Event Logs

You can use the following sample searches as a foundation for writing any number of searches around registration and authentication activity.

Mobile Device Registration

Number of users with registration attempts:

select count(distinct machineUserName)
where eventName:OOB_WEBSITE_REG OR eventName:OOB_WORKSTATION_REG

Number of successfully registered users:

select count(distinct machineUserName)
where eventName:OOB_DEVICE_REG_COMPLETE AND isSuccessful:true

Subtracting the second query result from the first will give you the number of users with failed registration attempts.

Number of successful registrations by day:

select count(distinct traceId), day(eventTimeInUTC)
where eventName:OOB_DEVICE_REG_COMPLETE AND isSuccessful:true
group by day(eventTimeInUTC)

Remember that one user can successfully register multiple devices/machines.

Registered devices per user:

select a.deviceCount, count(a.machineUserName) as userCount
from
  (select count(distinct deviceId) as deviceCount, machineUserName
   where eventName:OOB_DEVICE_REG_COMPLETE AND isSuccessful:true
   group by machineUserName) a
group by a.deviceCount

This does not account for devices that have been deregistered.

Smart Key Device Registration

Number of unique users and registration events by status:

select count(distinct machineUserName), count(distinct traceId), isSuccessful
where eventName:SMARTKEY_ENROLL group by isSuccessful

FIDO2 Device Registration

Number of unique users and registration events:

select count(distinct machineUserName), count(distinct traceId), isSuccessful
where eventName:FIDO2_DEVICE_REG_COMPLETE

Mobile Device Authentication

Number of unique authentication attempts:

select count(distinct traceId)
where eventName:OOB_WEBSITE_AUTH OR eventName:WORKSTATION_AUTH

Number of successful authentication events and users:

select count(distinct traceId) as auths, count(distinct machineUserName) as users
where eventName:OOB_WEBSITE_AUTH_COMPLETE and isSuccessful:true

Subtracting the second query result from the first will give you the number of users with failed registration attempts.

Number of users attempting to authenticate:

select count(distinct machineUserName)
where eventName:OOB_WEBSITE_AUTH OR eventName:WORKSTATION_AUTH

Number of successful authentications by day:

select count(distinct machineUserName) as users, count(distinct traceId) as auths, day(eventTimeInUTC)
where eventName:OOB_WEBSITE_AUTH_COMPLETE AND isSuccessful:true
group by day(eventTimeInUTC)

FIDO2 Device Authentication

Number of unique users and registration events:

select count(distinct machineUserName), count(distinct traceId)
where eventName:FIDO2_WEBAUTHN_COMPLETE