# Modules.Identity

Allows a Titanium application to use the iOS Touch ID / Face ID authentication mechanism.

Availability

6.3.0

Extends

Titanium.Module

# Overview

Touch ID / Face ID are security mechanisms that use biometric sensors to authenticate the user.

# Requirements

The Identity module is available with the Titanium SDK starting with Release 6.3.0. This module only works with devices running iOS 8 and later.

# Getting Started

Add the module as a dependency to your application by adding a <module> item to the <modules> element of your tiapp.xml file:

<ti:app>
  <!-- ... -->
  <modules>
    <module platform="iphone">ti.identity</module>
  </modules>
  <!-- ... -->
</ti:app>

Use require() to access the module from JavaScript:

var Identity = require('ti.identity');

The Identity variable is a reference to the module. Make API calls using this reference:

Identity.authenticate({
    reason: 'Verify to modify personal settings',
    callback: function(e) {
        Ti.API.info(e);
    }
});

# Lifetime Notes (iOS-only)

The current context will, once evaluated, be used until it's instance gets released or invalidated. You can you use the Modules.Identity.invalidate method to force the user to be prompted every time a new authentication is triggered. On iOS 9 and later, this can also be called to cancel a current evaluation of an auth-context, e.g. to hide the auth-dialoag.

# Distinguish between Touch ID and Face ID

Use the Modules.Identity.biometryType to receive the currently used biometry type. See an example of using the property to create a personalized interface when using Touch ID and Face ID:

var authPhrase = 'Unknown';

if (TiIdentity.biometryType === TiIdentity.BIOMETRY_TYPE_FACE_ID) { // Face ID
    authPhrase = 'Face ID';
} else if (TiIdentity.biometryType === TiIdentity.BIOMETRY_TYPE_TOUCH_ID) { // Touch ID
    authPhrase = 'Touch ID';
}

# Face ID Requirements (iOS only)

For Face ID to work properly, you need to add a <key> item to the <plist> element of your tiapp.xml file:

<ti:app>
  <!-- ... -->
  <ios>
    <!-- ... -->
    <plist>
      <dict>
        <key>NSFaceIDUsageDescription</key>
        <string>Why you need Face ID.</string>
      </dict>
    </plist>
    <!-- ... -->
  </ios>
  <!-- ... -->
</ti:app>

# Native Keychain Integration

For more infos regarding the keychain integration, check the "KeychainItem" "documentation.

# Sample Application

The module contains a sample application in the <TITANIUM_SDK_HOME>/modules/iphone/ti.identity/<VERSION>/example/ folder.

# Properties

# authenticationPolicy

Availability

6.3.0

authenticationPolicy :Number

Sets the global authentication policy used in this Touch ID / Face ID context.

You should set this property before checking the availability or starting the authentication. By default, AUTHENTICATION_POLICY_BIOMETRICS will be used to authenticate using the Touch ID / Face ID sensor only. Using the AUTHENTICATION_POLICY_PASSCODE constant will still try to authenticate with Touch ID / Face ID first and use the passcode as the fallback.

This API can be assigned the following constants:

Default: Modules.Identity.AUTHENTICATION_POLICY_BIOMETRICS

# biometryType READONLY

Availability

6.3.0

biometryType :Number

Indicates the type of the biometry supported by the device.

This property is set only when isSupported succeeds for a biometric policy. The default value is BIOMETRY_TYPE_NONE.

This API can be assigned the following constants:

Default: Modules.Identity.BIOMETRY_TYPE_NONE

# Methods

# authenticate

Availability

6.3.0

authenticate(params) → void

Initiates the biometric authentication process.

A special note for Android:

When you call this method in Android, it will either authenticate the fingerprint or it will fallback to the device's password, pin or pattern which is the case when biometric means of identification is not available. If you provide an incorrect fingerprint and receive an error message "Unable to recognize fingerprint", do not call authenticate. Instead, get the user to try again. If you call authenticate, it will end up in a bad state. This flow will be improved in the next update for Android.

Parameters

Name	Type	Description
`params`	IdentityAuthenticationType	Dictionary of arguments passed to the method, e.g. the reason to autheicate and the callback.

Returns

Type: void

# createKeychainItem

Availability

6.3.0

createKeychainItem(params) → void

Create KeychainItem.

Parameters

Name	Type	Description
`params`	KeychainItemType	Dictionary of arguments passed to the method.

Returns

Type: void

# deviceCanAuthenticate

Availability

6.3.0

deviceCanAuthenticate() → DeviceCanAuthenticateResult

Checks to see if device is configured for biometric authentication.

On Android this takes into account the authenticationPolicy.

Example:

var Identity = require("ti.identity");
var result = Identity.deviceCanAuthenticate();
if (!result.canAuthenticate) {
    alert('Message: ' + result.error + '\nCode: ' + result.code);
} else {
    alert('Device can authenticate');
}

Returns

Type: DeviceCanAuthenticateResult

# invalidate

Availability

6.3.0

invalidate() → void

Invalidates the current biometric dialog.

The context is invalidated automatically when it is (auto)released.

This method allows invalidating it manually while it is still in scope. Invalidation terminates any existing policy evaluation and the respective call will fail with ERROR_APP_CANCELLED. After the context has been invalidated, it can not be used for policy evaluation and an attempt to do so will fail with ERROR_INVALID_CONTEXT.

See the "Lifetime Notes (iOS-only)" paragraph in the module paragraph for more infos.

Returns

Type: void

# isSupported

Availability

6.3.0

isSupported() → Boolean

Determines if the current device supports Touch ID or Face ID.

This module is only supported on Android 6.0 or newer. So, this method always returns false on older versions of Android.

Returns

Type: Boolean

# Constants

# ACCESS_CONTROL_AND

Availability

6.3.0

ACCESS_CONTROL_AND :Number

Constraint logic operation - When using more than one constraint, all must be satisfied.

# ACCESS_CONTROL_APPLICATION_PASSWORD

Availability

6.3.0

ACCESS_CONTROL_APPLICATION_PASSWORD :Number

Security: Application provided password for data encryption key generation. This is not a constraint but additional item encryption mechanism.

# ACCESS_CONTROL_DEVICE_PASSCODE

Availability

6.3.0

ACCESS_CONTROL_DEVICE_PASSCODE :Number

Constraint - Device passcode.

# ACCESS_CONTROL_OR

Availability

6.3.0

ACCESS_CONTROL_OR :Number

Constraint logic operation - When using more than one constraint, at least one of them must be satisfied.

# ACCESS_CONTROL_PRIVATE_KEY_USAGE

Availability

6.3.0

ACCESS_CONTROL_PRIVATE_KEY_USAGE :Number

Create access control for private key operations (i.e. sign operation).

# ACCESS_CONTROL_TOUCH_ID_ANY

Availability

6.3.0

ACCESS_CONTROL_TOUCH_ID_ANY :Number

Constraint - Touch ID (any finger). Touch ID must be available and at least one finger must be enrolled. Item is still accessible by Touch ID even if fingers are added or removed.

# ACCESS_CONTROL_TOUCH_ID_CURRENT_SET

Availability

6.3.0

ACCESS_CONTROL_TOUCH_ID_CURRENT_SET :Number

Constraint - Touch ID from the set of currently enrolled fingers. Touch ID must be available and at least one finger must be enrolled. When fingers are added or removed, the item is invalidated.

# ACCESS_CONTROL_USER_PRESENCE

Availability

6.3.0

ACCESS_CONTROL_USER_PRESENCE :Number

User presence policy using Touch ID, Face ID or Passcode. Touch ID / Face ID does not have to be available or enrolled. Item is still accessible by Touch ID / Face ID even if fingers are added or removed.

# ACCESSIBLE_AFTER_FIRST_UNLOCK

Availability

6.3.0

ACCESSIBLE_AFTER_FIRST_UNLOCK :String

Item data can only be accessed once the device has been unlocked after a restart. This is recommended for items that need to be accesible by background applications. Items with this attribute will migrate to a new device when using encrypted backups.

# ACCESSIBLE_AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY

Availability

6.3.0

ACCESSIBLE_AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY :String

Item data can only be accessed once the device has been unlocked after a restart. This is recommended for items that need to be accessible by background applications. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device these items will be missing.

# ACCESSIBLE_ALWAYS

Availability

6.3.0

ACCESSIBLE_ALWAYS :Number | String

Item data can always be accessed regardless of the lock state of the device. This is not recommended for anything except system use. Items with this attribute will migrate to a new device when using encrypted backups.

Value is a Number on Android, a String on iOS.

# ACCESSIBLE_ALWAYS_THIS_DEVICE_ONLY

Availability

6.3.0

ACCESSIBLE_ALWAYS_THIS_DEVICE_ONLY :Number | String

Item data can always be accessed regardless of the lock state of the device. This option is not recommended for anything except system use. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device, these items will be missing.

Value is a Number on Android, a String on iOS.

# ACCESSIBLE_WHEN_PASSCODE_SET_THIS_DEVICE_ONLY

Availability

6.3.0

ACCESSIBLE_WHEN_PASSCODE_SET_THIS_DEVICE_ONLY :Number | String

Item data can only be accessed while the device is unlocked. This class is only available if a passcode is set on the device. This is recommended for items that only need to be accessible while the application is in the foreground. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device, these items will be missing. No items can be stored in this class on devices without a passcode. Disabling the device passcode will cause all items in this class to be deleted.

Value is a Number on Android, a String on iOS.

# ACCESSIBLE_WHEN_UNLOCKED

Availability

6.3.0

ACCESSIBLE_WHEN_UNLOCKED :String

Item data can only be accessed while the device is unlocked. This is recommended for items that only need be accesible while the application is in the foreground. Items with this attribute will migrate to a new device when using encrypted backups.

# ACCESSIBLE_WHEN_UNLOCKED_THIS_DEVICE_ONLY

Availability

6.3.0

ACCESSIBLE_WHEN_UNLOCKED_THIS_DEVICE_ONLY :String

Item data can only be accessed while the device is unlocked. This is recommended for items that only need be accesible while the application is in the foreground. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device, these items will be missing.

# AUTHENTICATION_POLICY_BIOMETRICS

Availability

6.3.0

AUTHENTICATION_POLICY_BIOMETRICS :Number

Device owner was authenticated using a biometric method.

A biometric authentication is required. If there are no biometrics available or not enrolled, policy evaluation will fail. If Touch ID / Face ID is locked out, passcode is required as the first step to unlock with Touch ID.

Touch ID authentication dialog contains a cancel button with default title "Cancel" which can be customized using cancelTitle property and a fallback button with default title "Enter Password" which can be customized using fallbackTitle property. Fallback button is initially hidden and shows up after first unsuccessful Touch ID attempt. Tapping cancel button or fallback button causes evaluatePolicy call to fail, returning a distinct error code.

Biometric authentication will get locked after 5 unsuccessful attempts. After that, users have to unlock it by entering passcode.

# AUTHENTICATION_POLICY_BIOMETRICS_OR_WATCH

Availability

9.0.0

AUTHENTICATION_POLICY_BIOMETRICS_OR_WATCH :Number

Device owner was authenticated using a biometric method or the Apple Watch.

# AUTHENTICATION_POLICY_PASSCODE

Availability

6.3.0

AUTHENTICATION_POLICY_PASSCODE :Number

Device owner was authenticated by Touch ID or device passcode.

Touch ID or passcode authentication is required. If Touch ID is available, enrolled and not locked out, user is asked for it first, otherwise they are asked to enter device passcode. If passcode is not enabled, policy evaluation will fail.

Touch ID authentication dialog behaves similarly as the one used by AUTHENTICATION_POLICY_BIOMETRICS. However, instead of "Enter Password" button there is "Enter Passcode" button which, when tapped, switches the authentication method and allows users to enter device passcode.

Passcode authentication will get locked after 6 unsuccessful attempts with progressively increased backoff delay.

# AUTHENTICATION_POLICY_WATCH

Availability

9.0.0

AUTHENTICATION_POLICY_WATCH :Number

Device owner was authenticated using the Apple Watch.

# BIOMETRY_TYPE_FACE_ID

Availability

6.3.0

BIOMETRY_TYPE_FACE_ID :Number

The device supports Face ID.

Used as a return-value for biometryType.

# BIOMETRY_TYPE_NONE

Availability

6.3.0

BIOMETRY_TYPE_NONE :Number

The device does not support biometry.

Used as a return-value for biometryType.

# BIOMETRY_TYPE_TOUCH_ID

Availability

6.3.0

BIOMETRY_TYPE_TOUCH_ID :Number

The device supports Touch ID.

Used as a return-value for biometryType.

# ERROR_APP_CANCELLED

Availability

6.3.0

ERROR_APP_CANCELLED :Number

Constant indicating that the app cancelled authentication.

# ERROR_AUTHENTICATION_FAILED

Availability

6.3.0

ERROR_AUTHENTICATION_FAILED :Number

Constant indicating that the authentication was not successful.

# ERROR_BIOMETRY_LOCKOUT

Availability

6.3.0

ERROR_BIOMETRY_LOCKOUT :Number

Authentication was not successful, because there were too many failed biometry attempts and biometry is now locked. Passcode is required to unlock biometry, e.g. evaluating authenticate will ask for passcode as a prerequisite.

# ERROR_BIOMETRY_NOT_AVAILABLE

Availability

6.3.0

ERROR_BIOMETRY_NOT_AVAILABLE :Number

Authentication could not start, because biometry is not available on the device.

# ERROR_BIOMETRY_NOT_ENROLLED

Availability

6.3.0

ERROR_BIOMETRY_NOT_ENROLLED :Number

Authentication could not start, because biometry has no enrolled identities.

# ERROR_INVALID_CONTEXT

Availability

6.3.0

ERROR_INVALID_CONTEXT :Number

Constant indicating that there is an invalid context.

# ERROR_PASSCODE_NOT_SET

Availability

6.3.0

ERROR_PASSCODE_NOT_SET :Number

Constant indicating that the passcode is not set for the device.

# ERROR_SYSTEM_CANCEL

Availability

6.3.0

ERROR_SYSTEM_CANCEL :Number

Constant indicating that iOS cancelled authentication, for example, if another application enters the foreground.

# ERROR_TOUCH_ID_LOCKOUT DEPRECATED

Availability

6.3.0

ERROR_TOUCH_ID_LOCKOUT :Number

DEPRECATED SINCE 10.0.0

This constant has deprecated in iOS. Use ERROR_BIOMETRY_LOCKOUT instead.

Constant indicating that Touch ID has locked out. Note: This constant has been deprecated for iOS 11 and later. Use ERROR_BIOMETRY_LOCKOUT for apps targeting iOS 11 and later.

# ERROR_TOUCH_ID_NOT_AVAILABLE DEPRECATED

Availability

6.3.0

ERROR_TOUCH_ID_NOT_AVAILABLE :Number

DEPRECATED SINCE 10.0.0

Use ERROR_BIOMETRY_NOT_AVAILABLE instead.

Constant indicating that Touch ID is not available on the device. Note: This constant has been deprecated for iOS 11 and later. Use ERROR_BIOMETRY_NOT_AVAILABLE for apps targeting iOS 11 and later.

# ERROR_TOUCH_ID_NOT_ENROLLED DEPRECATED

Availability

6.3.0

ERROR_TOUCH_ID_NOT_ENROLLED :Number

DEPRECATED SINCE 10.0.0

Use ERROR_BIOMETRY_NOT_ENROLLED instead.

Constant indicating that Touch ID does not have any enrolled fingerprints. Note: This constant has been deprecated for iOS 11 and later. Use <Modules.Identity.ERROR_BIOMETRY_NOT_ENROLLED for apps targeting iOS 11 and later.

# ERROR_USER_CANCEL

Availability

6.3.0

ERROR_USER_CANCEL :Number

Constant indicating that the user canceled authentication.

# ERROR_USER_FALLBACK

Availability

6.3.0

ERROR_USER_FALLBACK :Number

Constant indicating that the user tapped the fallback button to enter their passcode.