Native Biometrics Authenticator

This document provides a description of and integration guidelines for the HYPR Native Biometric Prompt Authenticator interface.

SDK for Android

Pooled Biometrics

The Native Biometric Prompt mechanism pools all Android OS registered biometrics together. This means that any registered biometric on the Android OS can register/authenticate into your app.

Description	Value
Standard Native Biometric Prompt AAID (Authenticator ID)	0045#0005
Library Name	HyprBiometricPrompt-<version>.aar

Biometrics in Biometric Prompt are Manufacturer-specified

The biometrics available in Biometric Prompt depend on the capabilities built into the device by the manufacturer. Some devices may have only fingerprint readers or face scanners; others may have both.

Native Biometric Prompt Fingerprint Reader

Number of Retries for Enrollment	5
Number of Retries for Authentication	5
Number of Retries before Timeout	5
Timeout before Authentication Can Commence Again	30 seconds
Number of Retries before Fingerprint Reader Is Locked	15
Fingerprint Reader Lock Time	Forever until user goes to Android Settings and unlocks the fingerprint reader.

Integration

Do This First

Before any HYPR authenticator can be added to a project, be sure to follow the HYPR SDK for Android Quick Start setup and integration.

The HYPR Native Biometric Prompt Authenticator specifically requires the following app/commonlibraries/build.gradle file additions.

dependencies {
  // HYPR Common Dependency
  api(name: 'HyprCommon', version: "${hyprVersion}", ext: 'aar')
  // HYPR Crypto Dependency
  api(name: 'crypto', version: "${cryptoVersion}", ext: 'aar') { transitive = true }
  // HYPR Native Biometric Prompt Authenticator Dependency
  api(name: 'HyprBiometricPrompt', version: "${hyprVersion}", ext: 'aar')
  
  // Android X Biometric Prompt dependency
  implementation 'androidx.biometric:biometric:1.1.0'
}

User Interface

Fingerprint Authenticator

Face Authenticator

Multiple Native Biometrics

If two or more native biometrics are registered on the device, the user will have to choose the preferred authentication method for the native Android Biometric prompt.

UI Customization

Configuration

Limited Customization

Due to the nature of the Android OS Native Biometric Prompt, there are only a few customization options available, which mainly consist of the text displayed.

The text used in the Native Biometric Prompt Authenticator can be overridden in the top-level application by modifying the app/<module_name>/src/main/res/values/strings.xml file. Below are the string names and default values that can be overridden.

<resources>
    <string name="hypr_biometricprompt_register">Register Biometric</string>
    <string name="hypr_biometricprompt_verify">Verify Biometric</string>
    <string name="hypr_biometricprompt_register_description">Confirm biometric to continue</string>
    <string name="hypr_biometricprompt_verify_description">Confirm biometric to continue</string>
    <string name="hypr_biometricprompt_cancel_button_text">Cancel</string>
</resources>

Customization Elements

SDK for iOS

Face ID

Face in the Crowd

Any Face ID registered on the device can register/authenticate into your App.

Standard Face ID AAID (Authenticator ID)	0045#1050
Full Basic Attestation Face ID AAID (requires Advanced Device Protection)	0045#1051
Number of Retries for Enrollment	2
Number of Retries for Authentication	2
Number of Retries before Face ID Reader Is Locked	Unlimited

Enrollment/Authentication Screen

Invalid Face ID Screen

Setup

1. Follow the steps below to enable the Face ID Authenticator. Since this is done during App startup, place it in AppDelegate.swift.

import UIKit
import HyprCore

@UIApplicationMain

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
        
    internal func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        let appConfig = AppConfig(rpServerUrl: "server url",
                                  rpAppId: "relying party application id",
                                  registrationPolicy: "reg policy name",
                                  authenticationPolicy: "auth policy name")
        
        
        HYPRWrapper.initHYPRForMobileAppUnlock(serverUrl: appConfig.rpServerUrl,
                                              relyingPartyAppId: appConfig.rpAppId,
                                              httpHeaderAdapter: httpHeaderAdapter())
        
        if let viewController = window?.rootViewController as? ViewController {
            viewController.hyprWrapper = HYPRWrapper.shared
            viewController.appConfig = appConfig
        }
        
        return true
    }
    
    func httpHeaderAdapter() -> HTTPHeaderAdapter {
        let httpHeaderAdapter = HTTPHeaderAdapter.shared
        httpHeaderAdapter.deviceInfo = DeviceInfo()
        return httpHeaderAdapter
    }
}

Register, Authenticate, Deregister

Create a Policy with FaceID

To dictate what authenticators to use during registration, authentication, and deregistration, you'll need to create a policy that includes the Face ID Authenticator.

See Policy Matching for greater detail.

Register

import HyprCore
  
class ViewController: UIViewController {
	func register() {
  	HYPRUserAgent.setParentViewController(self)
    HYPRUserAgent.sharedInstance().registerUser(withName: nil, action: "<policy name goes here>") { error in
    	if let error = error {
      	// Handle the error
      }
      else {
      	// Registration is successful
      }
    }
  }
}

Authenticate

By passing nil for the first argument, it will authenticate the current user.

import HyprCore
  
class ViewController: UIViewController {
	func authenticate() {
  	HYPRUserAgent.setParentViewController(self)
    HYPRUserAgent.sharedInstance().authenticateUser(nil, action: "<policy name goes here>") { error in
    	if let error = error {
      	// Handle the error
      }
      else {
      	// Authentication is successful
      }
    }
  }
}

Deregister

By passing nil for the first argument, it will deregister the current user.

import HyprCore
  
class ViewController: UIViewController {
	func deregister() {
  	HYPRUserAgent.setParentViewController(self)
    HYPRUserAgent.sharedInstance().deregisterUser(nil) { error in
    	if let error = error {
      	// Handle the error
      }
      else {
      	// Deregistration is successful
      }
    }
  }
}

UI Customization

To customize elements displayed by the HYPR SDK for iOS, use HYPRFaceIDAuthenticatorViewConfiguration sharedInstance to set properties describing the specific changes you want to make.

The HYPRFaceIDAuthenticatorViewConfiguration sharedInstance provides the following properties to style UI elements:

Property	Description
authenticationPromptText	Text displayed to the user in the Face ID authentication alert
biometryLockoutVerifyAlertTitle	Text displayed to the user if authentication was unsuccessful
biometryLockoutEnrollAlertTitle	Text displayed to the user if enrollment was unsuccessful
biometryLockoutAlertCloseButtonTitle	Alert cancellation button text
biometryLockoutAlertMessage	Text displayed to the user if authentication or enrollment were unsuccessful and amount of allowed attempt have exceeded

Example

import HyprCore
import HYPRFaceID

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
	func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    	let faceIDConfig = HYPRFaceIDAuthenticatorViewConfiguration.sharedInstance()
      faceIDConfig.authenticationPromptText = "This is the latest face id prompt text"
      faceIDConfig.biometryLockoutVerifyAlertTitle = "Verification failed"
      faceIDConfig.biometryLockoutEnrollAlertTitle = "Enrollment failed"
      faceIDConfig.biometryLockoutAlertCloseButtonTitle = "Close"
      faceIDConfig.biometryLockoutAlertMessage = "Try again later"
    return true
  }
}

Here is a full list of properties:

@interface HYPRFaceIDAuthenticatorViewConfiguration : NSObject <NSCopying, NSCoding>

+ (instancetype _Nonnull )sharedInstance;

/**
 * Face ID authenticator prompt text
 */
@property (nonatomic, copy, nullable) NSString *authenticationPromptText;
/**
 * Biometry lockout enroll alert title
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutEnrollAlertTitle;
/**
 * Biometry lockout verify alert title
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutVerifyAlertTitle;
/**
 * Biometry lockout alert message
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutAlertMessage;
/**
 * Biometry lockout alert close button title
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutAlertCloseButtonTitle;

@end

Fingerprint

All for One, One for All

Any fingerprint registered on the device can register/authenticate into your App.

Enrollment Screen

Authentication Screen

Invalid Fingerprint Screen

Description

Standard Fingerprint AAID (Authenticator ID)	0045#1005
Full Basic Attestation Fingerprint AAID (Requires Advanced Device Protection)	0045#1006
Number of Retries for Enrollment	3
Number of Retries for Authentication	3
Number of Retries before Fingerprint reader is locked	5
Fingerprint reader lock time	Forever until you unlock your phone via PIN

Setup

1. Follow the steps below to enable the Fingerprint Authenticator. Since this is typically done during App startup, place it in AppDelegate.swift.

import HyprCore
import HYPRFingerprint

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    HYPRUAFClient.registerAuthenticatorModule(HYPRFingerprintAsm.self)
    HYPRUserAgent.setSSLPinningEnabled(false)
    if HYPRUserAgent.sharedInstance().activeProfile() == nil {
    let config = HYPRUserAgentProfileConfiguration(
      rpAppId: "Relying Party App ID i.e: HYPRDefaultApplication",
      rpServerUrl: "Relying Party URL i.e.: https://9999-pov.hypr.com",
      deviceType: "WEB",
      rpSSLPinCredentials: nil,
      additionalData: nil)
  
    let profile = HYPRUserAgentProfile(displayName: "Place a profile name name here: i.e., MyProfile",
      configuration: config,
      persona: nil,
      userAccounts: nil)
      HYPRUserAgent.sharedInstance().registerProfile(profile!)
    }
    return true
  }
}

Register, Authenticate, Deregister

Create a Policy with Fingerprint

To dictate what authenticators to use during registration, authentication, and deregistration, you'll need to create a policy that includes the Fingerprint Authenticator.

See Policy Matching for greater detail.

import HyprCore
  
class ViewController: UIViewController {
	func register() {
  	HYPRUserAgent.setParentViewController(self)
    HYPRUserAgent.sharedInstance().registerUser(withName: nil, action: "<policy name goes here>") { error in
    	if let error = error {
      	// Handle the error
      }
      else {
      	// Registration is successful
      }
    }
  }
}

By passing nil for the first argument, it will authenticate the current user.

import HyprCore
  
class ViewController: UIViewController {
	func authenticate() {
  	HYPRUserAgent.setParentViewController(self)
    HYPRUserAgent.sharedInstance().authenticateUser(nil, action: "<policy name goes here>") { error in
    	if let error = error {
      	// Handle the error
      }
      else {
      	// Authentication is successful
      }
    }
  }
}

By passing nil for the first argument, it will deregister the current user.

import HyprCore
  
class ViewController: UIViewController {
	func deregister() {
  	HYPRUserAgent.setParentViewController(self)
    HYPRUserAgent.sharedInstance().deregisterUser(nil) { error in
    	if let error = error {
      	// Handle the error
      }
      else {
      	// Deregistration is successful
      }
    }
  }
}

UI Customization

To customize elements displayed by the HYPR SDK for iOS, use HYPRFingerprintAuthenticatorViewConfiguration.sharedInstance to set properties describing the specific changes you want to make.

The HYPRFingerprintAuthenticatorViewConfiguration.sharedInstance provides the following properties to style UI elements:

Property	Description
authenticationPromptText	Text displayed to the user in the fingerprint authentication alert.
biometryLockoutVerifyAlertTitle	Text displayed to the user if authentication was unsuccessful.
biometryLockoutEnrollAlertTitle	Text displayed to the user if enrollment was unsuccessful.
biometryLockoutAlertCloseButtonTitle	Alert cancellation button text.
biometryLockoutAlertMessage	Text displayed to the user if authentication or enrollment has been unsuccessful and the number of allowed attempts has been exceeded.

Example

import HyprCore
import HYPRFingerprint

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
	func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    	let fingerprintConfig = HYPRFingerprintAuthenticatorViewConfiguration.sharedInstance()
      fingerprintConfig.authenticationPromptText = "This is where your touch instructions go"
      fingerprintConfig.biometryLockoutVerifyAlertTitle = "Verification failed"
      fingerprintConfig.biometryLockoutEnrollAlertTitle = "Enrollment failed"
      fingerprintConfig.biometryLockoutAlertCloseButtonTitle = "Close"
      fingerprintConfig.biometryLockoutAlertMessage = "Try again later"
    return true
  }
}

Here is the full list of properties:

@interface HYPRFingerprintAuthenticatorViewConfiguration : NSObject <NSCopying, NSCoding>

+ (instancetype _Nonnull )sharedInstance;

/**
 * Fingerprint authenticator prompt text
 */
@property (nonatomic, copy, nullable) NSString *authenticationPromptText;
/**
 * Biometry lockout enroll alert title
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutEnrollAlertTitle;
/**
 * Biometry lockout verify alert title
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutVerifyAlertTitle;
/**
 * Biometry lockout alert message
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutAlertMessage;
/**
 * Biometry lockout alert close button title
 */
@property (nonatomic, copy, nullable) NSString *biometryLockoutAlertCloseButtonTitle;

@end