GaitAuth™ Authentication

Note: The authenticator functionality outlined on this page is currently in experimental beta and the interface to this portion of the SDK may change over time. Current support is for iOS, with Android coming soon.

Using GaitAuth Authenticator objects, you can automatically collect gait features, score those features, apply authentication logic to the scores, and produce an authenticated, unauthenticated, or inconclusive authentication status.

Authentication configurations are a customizable set of rules that take inputs (like feature scores) and produce an authentication result.

Creating an Authenticator

Before you begin, make sure you’ve set up the SDK and loaded a trained model.

An Authenticator instance collects data from the device and allows you to query the authentication status at any time. To create a new authenticator, you’ll want to provide a configuration that determines the authentication behavior:

let authenticator = unifyId.gaitAuth.authenticator(
  config: GaitQuantileConfig(
    ...
  ),
  model: model
)

When an authenticator is created, depending on its configuration, certain processes may begin. For example:

  1. A gait-based configuration causes feature collection to automatically begin, removing the need to explicitly call startFeatureUpdates.
  2. A configuration that uses the device unlock status may begin listening for lock/unlock events.

Authentication Status

The current authentication status can be queried with the status function. A completion handler should be provided to process the authentication result.

authenticator.status { res in
    switch res {
    case .success(let status):
        // Authentication status obtained
    case .failure:
        // Failure querying authentication status
    }
}

The status can be queried multiple times for an authenticator.

As long as the authenticator instance is allocated it will also continue any processes it has begun (e.g., collecting features or listening for unlock events). To stop these processes, ensure there are no more references to it so it will be de-allocated.

Configurations

Authenticators use configurations, which define the rules for determining authentication status. Configurations can expose options to customize their behavior. Additionally, based on the inputs/signals a configuration uses, an authenticator that uses it may begin certain data collection processes.

Currently, a gait-based quantile configuration and a device authentication configuration are available in the SDK. As new configurations are added, they will be documented below.

Gait Quantile Config

The Gait Quantile Config takes recent feature scores and returns an authenticated result if splitting the features across numQuantiles quantiles, all data at or above the nth (n = quantile) quantile are at or above the score threshold (threshold). A few examples:

  • numQuantiles: 100, quantile: 75, threshold: 0.5
    The result is authenticated if the top 25% of scores are at or above 0.5.
  • numQuantiles: 100, quantile: 20, threshold: 0.5
    The result is authenticated if the top 80% of scores are at or above 0.5.
  • numQuantiles: 5, quantile: 2, threshold: 0.8
    The result is authenticated if the top 60% of scores are at or above 0.8.

Create the Authenticator

To create an authenticator with the quantile configuration, provide a GaitQuantileConfig and a trained model.

The configuration has the following options:

  • minNumScores
    Minimum number of scores to require. Otherwise, inconclusive will be returned as the result.
  • maxNumScores
    Maximum number of scores to use, ordered by most recent. Additional scores are not used.
  • maxScoreAge
    Maximum allowed age for scores, in seconds. Scores older than this limit are not used.
  • numQuantiles
    Number of quantiles.
  • quantile
    Quantile number to require.
  • threshold
    Score threshold to require.

Because a model is needed to score features, a trained/downloaded model is also required. Your complete call will look something like this:

let authenticator = unifyId.gaitAuth.authenticator(
  config: GaitQuantileConfig(
    minScores: 5,
    maxScores: 50,
    maxScoreAge: 300,
    numQuantiles: 100,
    quantile: 50,
    threshold: 0.8,
  ),
  model: model
)

Feature Collection

When an authenticator is created with a GaitQuantileConfig, feature collection begins, and the features are stored locally in a buffer. Calling status on the authenticator queries the features in this buffer. No separate call to startFeatureUpdates is required.

To stop feature collection, ensure there are no more references to the authenticator instance so that it will be de-allocated.

Device Authentication Config

The Device Authentication Config produces the following behavior:

  • authenticated if the device is currently, or has recently been, unlocked
  • unauthenticated if the device is currently locked or has not recently been unlocked
  • inconclusive if a determination cannot be made

Depending on the maxUnlockAge option, the authenticator either looks at the current state or uses a lookback window.

Create the Authenticator

To create an authenticator with the device authentication configuration, provide a DeviceAuthenticationConfig. Unlike the quantile configuration, no model is provided because device authentication does not require it.

The configuration has a single option:

  • maxUnlockAge
    How far back, in seconds, to detect an unlock. If no value is provided, the default behavior is to only consider the current locked/unlocked state. Using a value of 60 would allow the authenticator to return authenticated if the device is currently locked, but was unlocked within the last minute.

To create an authenticator that considers only the current state:

let authenticator = unifyId.gaitAuth.authenticator(
  config: DeviceAuthenticationConfig()
)

Updated: