Audit Trail

Overview

Introduction

The Audit Trail is designed to help administrators discover if and when issues occur during registration, authentication, or transaction. HYPR captures these user activity data and provides access to it in a simple, easy to use interface which lowers troubleshooting time and personnel resources, so that the issue can be identified and remedied at speed.

What is the Audit Trail

The Audit Trail is a collection of user activity events that is captured by all components in the HYPR ecosystem. These captured events span the entirety of the flow of operations, whether it's registration, authentication, de-registration, or a transaction. At every step of each HYPR request or response, an event is generated and collected with its corresponding information.

How it works

Event data is stored in a separate schema away from the critical HYPR FIDO databases. This allows registration, authentication and de-registration flows to continue functioning without being affected. The connection information to this schema can be found in the Vault and, or, a HYPR representative can help you find it. The settings for the Audit Trail schema will be automatically set up for you during installation.

We anticipate there could be potentially millions of records in this database so a data rollover mechanism exists. This mechanism will be described in detail at the bottom of this guide.

Events

Each single captured event is a result of a Successful or Failed attempt.

Registration events

Events reported during the registration of the Web Account or Workstation with HYPR Mobile App.

Event

Sub event

Description

OOB_WEBSITE_REG

/client/setup

Opening Registration request call from the Browser or Workstation. The client now waits for the mobile to scan QR

Typical problems: - Application is not setup in ControlCenter

  • HYPR License is invalid

OOB_DEVICE_REG

/device/setup start

Device scans the QR code and sends starts the registration process from its side. A sessionId is generated and returned as a part of the response. Initial handshake between the client (Browser/Workstation) is now complete
Typical problems:

  • Pin mismatch due to a timeout - Multiple scans of the same QR code

OOB_DEVICE_REG

/device/setup complete

Device started the registration successfully. Pin has been matched successfully. RP connection is ok. Device can now proceed to do a FIDO registration

FIDO_ONLY_REG

/fido/send/reg

FIDO registration.
Registration policy is supplied by the server. Device generates a cryptographic key pair sends the public key to the server. The user provides a 2nd factor (touch/pin/native/etc) to safeguard the key.

Typical failures:

  • Application policy not setup properly in ControlCenter
  • Authenticator specified by the policy is not available on the phone

OOB_WEBSITE_REG

/client/setup complete

Client setup step is done. The sessionId is returned to the Client

This indicates that the device has finished enrolling the user key pair. The registration process though, is not complete yet.

OOB_WEBSITE_REG

/client/registrations /client/registrations/{sessionId}

Client receives more registration information on the device and confirms completion on its side

OOB_DEVICE_REG_COMPLETE

/device/registrations

Final registration complete confirmation by the Device. On success, a registration record will exist in the DB

Website authentication events

Event

Sub event

Description

OOB_WEBSITE_AUTH

rp/oob/client/authentication/requests

Browser requests authentication from the HYPR server for the user in the context
A push notification is sent to the mobile at this point, asking it to authenticate
A sessionId is generated and returned as a part of the response
Typical problems:

  • Delay in receiving the push notification, caused by network conditions/traffic

FIDO_ONLY_AUTH

fido/send/auth

Upon receiving the push msg, the device prompts the user to authenticate

OOB_WEBSITE_AUTH_COMPLETE

rp/oob/client/authentication/requests/{sessionId}

Client polls the server periodically to check if the mobile authentication is successful
The server returns the current status of auth, in the response msg

WorkStation authentication events

Event

Sub event

Description

WORKSTATION_AUTH

device/authorize/ws/unlock

Start of the Workstation unlock request from the Device. This request is made when the user clicks the unlock button in the HYPR app.

A msg is sent to the workstation at this point to start unlock/login

WORKSTATION_AUTH_COMPLETE

client/auth/complete/{sessionId}

Client has finished unlocking the Workstation.
This indicates that the msg had reached the Workstation

WORKSTATION_AUTH_COMPLETE

client/verify/complete/{sessionId}

The user has verified their physical presence at the workstation
Generally, this involves hitting ctrl + alt + del keys

WORKSTATION_AUTH_COMPLETE

device/authorize/ws/complete/{sessionId}

Final confirmation that unlock is successful
Client and Device top up offline tokens if needed

Other events

Event

Definition

Fido Only Dereg

Core FIDO De-registration.

OOB Website Trans

The initial call for Website transaction.

OOB Website Initiated Delete

Deregistration request initiated from the Web Account or Control Center.

Workstation Initiated Delete

Deregistration request initiated from Workstation. The user clicked on the delete mobile device button in the HYPR App on the computer.

Mobile Initiated Website Delete

Deregistration request initiated from Mobile for Website. The mobile user clicked on the delete web account button.

Mobile Initiated Workstation Delete

Deregistration request initiated from Mobile for Workstation. The mobile user clicked on the delete computer button.

Offline Token Access

Offline Token Access Request

Offline Token Auth

Authentication using Offline Mode. Mobile App user used Offline Mode PIN to login into the workstation.

Workstation Socket Connect

Workstation Web Socket was Connected.

Workstation Socket Disconnect

Workstation Web Socket was Disconnected.

Workstation Configuration

Workstation was configured.

Workstation Startup

Workstation was started. Usually it indicates that user powered on or rebooted the computer.

Workstation Shutdown

Workstation was shutdown. Usually it indicates that user powered off or rebooted the computer.

Audit Action CC

Events that the Control Center admin performs to authenticators, policies, and to the Application settings.

Exception

Captures any oddities that may occur on the mobile, workstation or web components.

Each event will, available data permitting, provide the following

Parameter

Description

Time

Time of the event

Username

Username the registration was done with

Event

Event name

SubEvent

An event might be broken into sub steps. The sub event distinguishes the various steps. Typically, its the URI of the request

Status

Status of the individual Event. Success or Failure.

Machine ID

Machine Identification

Machine refers to Entity requesting authentication. Currently we support Website
and WorkStation

Device ID

Device Identification

Device refers to the mobile device (90%) or another hardware device (Yubi key) which stores the private key/authenticator - does the authentication

Logged By

The component which logged the event.
Mobile, Control Center/Relying party, Web, Workstation

Message

A message giving a brief recount of the event which happened.

Additional Details

Mobile Device

Parameter

Description

OS

Operating System of Mobile Device (Android/iOS)

OS Version

Operation System Version number

Model

Mobile device model number

SDK Version

Version of HYPR SDK

Tokens Available

Number of Offline Mode Tokens Available

Tokens Remaining

Number of Offline Mode Tokens Remaining

Workstation

Parameter

Description

Extended Message

An Additional Message from Workstation regarding the event

OS Version

Operating System version

Model

Operating System model

OS

Operating System

Offline Access Enabled

True/False

Offline Token Length

Length of the Offline Token

Offline Token Count

Total Number of Offline Token

Offline Access Days

Number of Days Remaining on Offline Tokens

Tokens Available

Number of Tokens Available

Tokens Remaining

Number of Tokens Remaining

Server

Parameter

Description

Node ID

I.P. of the node

Version

Version of the Server

Web

Parameter

Description

Extended Message

Additional Details

MachineName

Unique name of the machine

User Interface

The Audit Trail feature is Application specific and does not encompass a global scope as such. You can locate it in the left navigation panel of the Control Center under App Properties.

Searching events

When you first click on the Audit Tail option, the last 10 minutes of Events will be displayed.

Search By Time Frame

To expand the searchable timeframe, click the 'Calendar' icon.

Quick filters

Parameter

Description

Last Hour

Gets the last 24 Hours of Events

Today

Gets the Events from Midnight to Current Time

Yesterday

Gets the Events from Yesterday

Last 7 days

Gets the Events from the last 7 days

Last 30 Days

Gets the Events from the last 30 days

User Interface

You can also select a specific timeframe by clicking the start date and end date in the calendar. For a more precise timeframe search, you also can enter in a time HH:MM:SS.

Search by Users, Machine IDs, Session IDs or Device IDs

The Audit Trail allows searching by Username, Machine ID's, Session ID's or Device ID's. Searching on one of these identifiers allows the Admin to narrow down the action and get a resolution to the issue without having to dig through the server logs. By quickly identifying a Failed event, and cross-referencing it with a user, session, machineID or deviceID, you can further glean what the root cause of the issue is.

Export

To export rows of the Audit Trail, select the checkbox next to the row you want to export and click the "Export" button. This will provide you with a CSV file with all selected rows.

Examples

You have found a Failed event that is a Timeout. By searching for the MachineID, you see that this particular user has many timeouts and errors which say "Did not receive anything from device". This could be a device issue. Check connectivity and try again.

Database Rollover

We keep the last 30 days of event data.
Every hour we archive the data that is older than 30 days into a backup table.
The backup retains data indefinitely.

Event Log File

With Server 3.8, HYPR is introducing Event log files for users who want to parse the log file for tracing any errors and events. It will also help to integrate with SIEM tools such as Splunk, Greylog, etc.

Control Center Event Log File

This is located under the /opt/hypr/<Server Install dir> logs directory. This contains all the events for the Control Center.

UAF Event Log File

This is located under the /opt/hypr/<Server Install dir> logs directory. This contains all the events for UAF.

Troubleshooting

Mobile User Flow

Mobile users should send the support email which will contain required debug information.

πŸ“˜

Support Email Configuration

Support email can be configured here.

Admin Troubleshooting

Step 1: Check diagnostic email from the user

Step 2: Copy FIDO ID and paste it into the Audit Trail search

Step 3: Check HYPR Docs for error details and steps to resolve

API Access

You can integrate Audit Trail APIs into your application to leverage advanced search capabilities or improve integration with the existing system.

Learn more about API Access in our documentation.

Updated 8 months ago

Audit Trail


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.