Skip to content
Titanium SDK

ti.identity

Officialtidev/titanium-identity

A collection of API's to authenticate with your device: Keychain/Keystore, Touch ID and Face ID

API reference

Compiled from

Modules.Identity

moduleAndroidiPhoneiPadsince 6.3.0

Extends Titanium.Module

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

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](api:Modules) element of your tiapp.xml file:

<ti:app>
  <!-- ... -->
  [modules](api: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](api:Global.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 40

ACCESS_CONTROL_AND

NumberiPhoneiPadsince 6.1.0read-only

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

ACCESS_CONTROL_APPLICATION_PASSWORD

NumberiPhoneiPadsince 6.1.0read-only

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

ACCESS_CONTROL_OR

NumberiPhoneiPadsince 6.1.0read-only

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

ACCESS_CONTROL_TOUCH_ID_ANY

Numbersince 6.1.0read-only

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

Numbersince 6.1.0read-only

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

Numbersince 6.1.0read-only

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

StringiPhoneiPadsince 6.1.0read-only

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

StringiPhoneiPadsince 6.1.0read-only

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

Number | Stringsince 6.1.0read-only

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

Number | Stringsince 6.1.0read-only

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

Number | Stringsince 6.1.0read-only

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

StringiPhoneiPadsince 6.1.0read-only

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

StringiPhoneiPadsince 6.1.0read-only

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

Numbersince 6.1.0read-only

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_PASSCODE

Numbersince 6.1.0read-only

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.

authenticationPolicy

Numbersince 6.1.0

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.

Accepts

Default: Modules.Identity.AUTHENTICATION_POLICY_BIOMETRICS

ERROR_APP_CANCELLED

NumberiPhoneiPadread-only

Constant indicating that the app cancelled authentication.

ERROR_BIOMETRY_LOCKOUT

Numbersince 6.3.0read-onlyiOS 11.0+

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 Modules.Identity.authenticate will ask for passcode as a prerequisite.

ERROR_BIOMETRY_NOT_AVAILABLE

Numbersince 6.3.0read-onlyiOS 11.0+

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

ERROR_BIOMETRY_NOT_ENROLLED

NumberiPhoneiPadsince 6.3.0read-onlyiOS 11.0+

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

ERROR_PASSCODE_NOT_SET

NumberiPhoneiPadread-only

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

ERROR_SYSTEM_CANCEL

NumberiPhoneiPadread-only

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

ERROR_TOUCH_ID_LOCKOUT

Numberdeprecatedread-only

Deprecated since 10.0.0

This constant has deprecated in iOS. Use <Modules.Identity.ERROR_BIOMETRY_LOCKOUT> instead.

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

ERROR_TOUCH_ID_NOT_ENROLLED

NumberdeprecatediPhoneiPadread-only

Deprecated since 10.0.0

Use <Modules.Identity.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

NumberiPhoneiPadread-only

Constant indicating that the user canceled authentication.

ERROR_USER_FALLBACK

NumberiPhoneiPadread-only

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

hasFaceScanner

BooleanAndroidsince 12.1.0

Returns true if the has biometric hardware to perform face authentication

hasFingerprintScanner

BooleanAndroidsince 12.1.0

Returns true if the device has biometric hardware to detect a fingerprint.

hasIrisScanner

BooleanAndroidsince 12.1.0

Returns true if the device has biometric hardware to perform iris authentication.

Methods 5

authenticate

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
ParametersTypeDescription
paramsIdentityAuthenticationType

Dictionary of arguments passed to the method, e.g. the reason to autheicate and the callback.

9 fields
allowableReuseDuration Number

Note: This property is iOS only!

The time interval (in seconds) for accepting a successful Touch ID / Face ID device unlock (on the lock screen) from the past. If the device was successfully unlocked by Touch ID / Face ID within this time interval, then the biometric authentication on this context will succeed automatically and the reply block will be called without prompting user for authentication.

The default value is 0, meaning that no previous TouchID unlock can be reused.

This property is meant only for reusing biometric matches from the device lock screen. It does not allow reusing previous biometric matches in application or between applications.

The maximum supported interval is 5 minutes and setting the value beyond 5 minutes does not increase the accepted interval.

callback Callback

Callback function executed after the authentication completes. The callback function is passed a dictionary with three properties:

  • success (Boolean): Set to true if authentication succeeded.
  • error (String): System error message.
  • code (Number): Module ERROR_* constant indicating the reason for the failure.
cancelTitle String

Allows cancel button title customization. A default localized title "Cancel" is used when this property is not defined or is set to empty string. Android: The default value will be "Cancel".

confirmationRequired String

Sets a hint to the system for whether to require user confirmation after authentication. For example, implicit modalities like face and iris are passive, meaning they don't require an explicit user action to complete authentication. See https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.Builder#setConfirmationRequired(boolean)

fallbackTitle String

Note: This property is iOS only!

Allows fallback button title customization. A default localized title "Enter Password" is used when this property is left nil. If set to empty string, the button will be hidden.

keepAlive Boolean

Note: This property is iOS only!

Determines whether the auth-context should be kept alive after authorizing with the TouchID-API and can be used to automatically terminate an auth-context after authorizing.

Please note that calling invalidate will not be possible unless you have a valid auth-context, so you would decide whether to use invalidate to invalidate the context and release the auth-instance or use the keepAlive property inside authenticate to only terminate the context.

Terminated contexts cannot be recovered and will be recreated with a new auth-context once authenticate is called again.

reason String

Message displayed in the authentication dialog describing why the application is requesting authentication. Android: The title of the dialog.

reasonSubtitle? String

Subtitle of the authentication dialog (2nd line).

reasonText? String

Text of the authentication dialog (3rd line).

createKeychainItem

Create KeychainItem.

Parameters
ParametersTypeDescription
paramsKeychainItemType

Dictionary of arguments passed to the method.

7 fields
accessControlMode Number

Optional constants used to determine the access control with the specified protection type and flags. The constants can be concatenated by using the Bit OR operator, e.g. optionA | optionB | optionC.

accessGroup String

Optional identifier used to define the access group the keychain item should be valid. This can be used to share a keychain item across two or more apps that use the same organization group identifier. More information about keychain access groups can be found in the official iOS documentation.

accessibilityMode Number

Optional constant used for determining when a keychain item should be readable. Use this property with caution to enable advanced access control. More information about this property and it's values can be found in the official iOS documentation.

cipher String

Define the cipher used to encrypt keychain items. Android supported ciphers

identifier String

Required identifier to create or receive a keychain item. The identifier cannot contain alphanumeric characters or it might be rejected by the keychain.

options Dictionary

Optional parameter used to specify additional values to the keychain. Example: The raw-value of kSecUseOperationPrompt is u_OpPrompt, so you could specify options: {'u_OpPrompt': 'Please authenticate yourself!'}.

service String

A key whose value is a string indicating the item's service. Defaults to ti.touchid if not set for backwards compatibility with the deprecated Ti.TouchID module. This property is required when using app extensions and should also include the app-prefix (aka team-ID).

deviceCanAuthenticate

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 DeviceCanAuthenticateResult

invalidate

since 6.1.0

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 Modules.Identity.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 Modules.Identity.ERROR_INVALID_CONTEXT.

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

isSupported

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 Boolean

Modules.Identity.KeychainItem

moduleAndroidiPhoneiPadsince 6.1.0

Extends Titanium.Module

Represents a keychain item to communicate with the native iOS Keychain and Android Keystore.

The following example demonstrates the basic usage to save, read and delete values with the native iOS Keychain and/or Android Keystore:

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

// Create a keychain item
var keychainItem = Identity.createKeychainItem({
    identifier: 'password'
});

// Triggered when the keychain item was successfully saved
keychainItem.addEventListener('save', function(e) {
    // Notify the user that the operation succeeded or failed
});

// Write to the keychain
keychainItem.save('s3cr3t_p4$$w0rd');

For advanced security options, you can specify accessibility mode to the keychain that will be applied when writing items to the keychain, for example:

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

// Create a keychain item
var keychainItem = Identity.createKeychainItem({
  identifier: 'mypassword',
  service: 'my_service', // iOS only. Defaults to 'ti.touchid' for backwards compatibility
  accessGroup: '<YOUR-TEAM-ID>.com.appc.identitytest',
  accessibilityMode: Identity.ACCESSIBLE_WHEN_PASSCODE_SET_THIS_DEVICE_ONLY,
  accessControlMode: Identity.ACCESS_CONTROL_TOUCH_ID_ANY,
  // Pass more native options to the keychain. Since there are hundrets of them,
  // look up the value of the constant and pass it here. Example:
    options: {
      // The value of kSecUseOperationPrompt
      'u_OpPrompt': 'Please authenticate yourself!'
  }
});

Methods 5

fetchExistence

since 6.1.0

Asynchronously determines whether or not a value of the specified identifier exists in the keychain item.

Parameters
ParametersTypeDescription
resultCallback

Use the event key exists of the callback to determine the existence of the keychain item.

read

since 6.1.0

Reads an existing value to the native keychain.

The Modules.Identity.KeychainItem.read event is triggered when an item is fetched. If an error occurs, the error key informs you about the exact error.

reset

since 6.1.0

Resets an existing value from the native keychain.

The Modules.Identity.KeychainItem.reset event is triggered when a new item is saved. If an error occurs, the error key informs you about the exact error.

save

since 6.1.0

Saves a new value to the native keychain.

The Modules.Identity.KeychainItem.save event is triggered when a new item is saved. If an error occurs, the error key informs you about the exact error.

On Android this will also overwrite any existing value.

Parameters
ParametersTypeDescription
valueString

The value to be stored in the native keychain.

update

since 6.1.0

Updates an existing value to the native keychain.

The Modules.Identity.KeychainItem.update event is triggered when an item is updated. If an error occurs, the error key informs you about the exact error.

Parameters
ParametersTypeDescription
valueString

The value to be stored in the native keychain.

Events 4

read

since 6.1.0

Triggered when a new keychain item is read (or an error occurred).

reset

since 6.1.0

Triggered when a new keychain item is reset (or an error occurred).

save

since 6.1.0

Triggered when a new keychain item is saved (or an error occurred).

update

since 6.1.0

Triggered when a new keychain item is updated (or an error occurred).