Version: 4.1

Ionic Identity Vault

Ionic Identity Vault is an all-in-one frontend identity management system that combines security best practices and the latest in biometric authentication options available on iOS and Android.

The Vault manages secure user identity and session tokens, ensuring sensitive tokens are encrypted at rest, stored only in secure locations on the device, and unlocked only with biometric identity (TouchID/FaceID).

Without Ionic Identity Vault, Ionic developers have to resort to combining third party Cordova plugins, often resulting in insecure setups due to the lack of correct implementation of biometric and at-rest encryption strategies. Learn more.

Installation

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

Capacitor
Cordova

npm install @ionic-enterprise/identity-vault
npx cap sync

ionic cordova plugin add @ionic-enterprise/identity-vault 

Update the native project config files:


_10// iOS - Info.plist
_10<key>NSFaceIDUsageDescription</key>
_10<string>Use Face ID to authenticate yourself and login</string>
_10
_10// Android - No additional changes needed

Reference App

A complete login/logout experience that includes biometrics (Face ID with passcode as a fallback), secure token storage, background data hiding, and session timeouts.

Configuring the Vault

The IonicIdentityVaultUser class takes a generic session type which represents the type of the session you'll store in the vault. You can use the DefaultSession or extend the class to create a custom session. In the constructor of your Identity service, the vault is configured by providing options to the super() call:


_35interface MyCustomSession extends DefaultSession {
_35  // username & token are inherited
_35  email: string;
_35  age: number;
_35  nicknames: string[];
_35}
_35
_35export class IdentityService extends IonicIdentityVaultUser<MyCustomSession> {
_35
_35constructor(private http: HttpClient, private router: Router, platform: Platform) {
_35  super(platform, {
_35    authMode: AuthMode.BiometricAndPasscode, // Use biometrics auth with passcode fallback
_35    restoreSessionOnReady: false, // whether or not to immediately attempt to restore the session when the vault is ready
_35    unlockOnReady: false, // set true to auto prompt the user to unlock when vault is ready
_35    unlockOnAccess: true, // set to true to auto prompt the user to unlock on first read access
_35    lockAfter: 5000, // lock after 5 seconds in the background
_35    hideScreenOnBackground: true // when in app launcher mode hide the current screen and display the splashscreen
_35  });
_35
_35  onVaultUnlocked(config: VaultConfig) {
_35    //Route to my home page
_35  }
_35
_35  onVaultLocked() {
_35    //Route to my login page
_35  }
_35
_35  async onPasscodeRequest(isPasscodeSetRequest: boolean) {
_35    // Display a custom Passcode prompt and return the passcode as a string
_35    // or return undefined to use the build in native prompts. isPasscodeSetRequest
_35    // is true when attempting to set a new passcode on the vault, you can use
_35    // it to do something like prompt the user twice for the pin.
_35  }
_35
_35}

Automatically adding your token to requests

If you'd like to automatically add your authorization token from your identity service to every request, you can see a simple example at in our demo repo.

Upgrading to v4.0.0

If you have Identity Vault <3.1.0, please see Upgrading from v3.0.0 to >=v3.1.0 before following these upgrade instructions.

Upgrade your app to use cordova-android 9.x (see the 9.0.0 milestone for progress) or Capacitor 2.x.
- For Capacitor, please see the upgrade guide for Android and iOS.
Install the new plugin version.

API Documentation

You can find the API and interface documentation for everything below. The main classes to pay attention to are:

IonicIdentityVaultUser - Subclass this when creating your identity service.
DefaultSession - This is the generic type that represents your session. Extend this to implement a custom session.
IdentityVault - This is the lower level vault API. You can use this to implement advanced workflows including multi-tenant vaults.

Index

Enumerations

AuthMode

AuthMode:

The type of authentication the vault should be configured to allow.

BiometricAndPasscode

BiometricAndPasscode:

Both biometric and passcode authentication should be allowed

BiometricOnly

BiometricOnly:

Biometrics authentication should only be allowed

BiometricOrPasscode

BiometricOrPasscode:

Use biometrics if it is available, otherwise use passcode

InMemoryOnly

InMemoryOnly:

Both biometric and passcode authentication should be disabled. With this setting all data in the vault will be cleared on lock or if the app is closed. Stored data is kept only in memory.

PasscodeOnly

PasscodeOnly:

Passcode authentication should only be allowed

SecureStorage

SecureStorage:

Both biometric and passcode authentication will be disabled but any stored values will persist and be stored securely at rest using the keychain and will be available without needing to authenticate via passcode or biometrics when the device is unlocked.

VaultErrorCodes

VaultErrorCodes:

The meaning of the error code in the thrown VaultError

AuthFailed

AuthFailed:

User authentication failed.

BiometricsNotEnabled

BiometricsNotEnabled:

The operation failed because biometric authentication is not enabled. This can occur when biometrics is not supported by the device or when biometrics has not been configured for the device or vault.

InvalidArguments

InvalidArguments:

The operation failed because the some of the vault provided arguments were invalid.

InvalidAuthMode

InvalidAuthMode:

The provided AuthMode is invalid. Should be one of AuthMode.

InvalidatedCredential

InvalidatedCredential:

The credentials were invalidated. This can happen when a user changes biometrics or passcode.

KeyNotFound

KeyNotFound:

The key was not found. This can happen when a user changes biometrics or passcode.

MismatchedPasscode

MismatchedPasscode:

The user provided mismatched passcodes.

MissingPasscode

MissingPasscode:

The operation requires passcode to be setup but it isn't set yet. Call setPasscode to set it.

PasscodeNotEnabled

PasscodeNotEnabled:

The operation failed because the application tried to unlock the vault with passcode authentication, but the vault is not configured to allow passcode authentication.

SecurityNotAvailable

SecurityNotAvailable:

Biometric security is unavailable due to a passcode not being set up at the system level. In order to use biometric identification on the device a system level passcode must be set up by the user.

TooManyFailedAttempts

TooManyFailedAttempts:

Too many failed authentication attempts so the vault was cleared an user will need to login again.

Unknown

Unknown:

An unknown error happened.

UserCanceledInteraction

UserCanceledInteraction:

The user cancelled the native authentication dialog.

VaultLocked

VaultLocked:

The operation failed because the vault was locked.

VaultUnavailable

VaultUnavailable:

The operation failed because the vault was unavailable. The most likely cause of this error is that a vault has not been configured.

Interfaces

DefaultSession

DefaultSession:

The interface for the Default Session. Extend this interface to make a custom session

usage:


_10MyCustomSession extends DefaultSession {
_10 email: string;
_10 age: number;
_10 nicknames: string[];
_10}

token

● token: string

username

● username: string

IdentityVault

IdentityVault:

The underlying vault API. You can gain direct access to the vault for more advanced usage by using the IdentityVaultUser.getVault method.

`<Optional>` config

● config: PluginConfiguration

The current configuration of the vault will stay current as long as unsubscribe is not called.

clear

▸ clear(): Promise<void>

Clear all vault data including stored tokens, values, and passcodes. The vault will be empty and unlocked after this.

Returns: Promise<void>

getBiometricType

▸ getBiometricType(): Promise<BiometricType>

Get the type of biometrics the device supports

Returns: Promise<BiometricType> the type of biometrics the device supports

getConfig

▸ getConfig(): Promise<PluginConfiguration>

Get the current configuration of the vault

Returns: Promise<PluginConfiguration> the configuration

getKeys

▸ getKeys(): Promise<string[]>

Get all keys with stored values.

throws: VaultError - if vault is locked

Returns: Promise<string[]> array with all keys

getToken

▸ getToken(): Promise<any>

Get any data stored in the token slot. This is equivalent to calling getValue("token").

throws: VaultError - if vault is locked

Returns: Promise<any> token data

getUsername

▸ getUsername(): Promise<string>

Get the username associated with the vault

Returns: Promise<string> the username for the vault

getValue

▸ getValue(key: string): Promise<any>

Get a value stored under the given key.

throws: VaultError - if vault is locked

Parameters:

Name	Type	Description
key	`string`	the key where the value is stored

Returns: Promise<any> the value stored at the key

isBiometricsAvailable

▸ isBiometricsAvailable(): Promise<boolean>

Check whether or not biometrics is supported by the device and has been configured by the current user of the device

Returns: Promise<boolean> whether or not biometrics is available

isBiometricsEnabled

▸ isBiometricsEnabled(): Promise<boolean>

Check whether or not biometrics is enabled on the vault

Returns: Promise<boolean> whether or not biometrics is enabled

isBiometricsSupported

▸ isBiometricsSupported(): Promise<boolean>

Check whether or not biometrics is supported by the device

Returns: Promise<boolean> whether or not biometrics is supported

isInUse

▸ isInUse(): Promise<boolean>

Check whether the vault has any values stored in it.

Returns: Promise<boolean> whether the vault has stored values

isLocked

▸ isLocked(): Promise<boolean>

Check whether the vault is currently locked

Returns: Promise<boolean> whether the vault is locked

isLockedOutOfBiometrics

▸ isLockedOutOfBiometrics(): Promise<boolean>

Check whether the biometrics are locked on the device

Returns: Promise<boolean> whether biometrics are locked

isPasscodeEnabled

▸ isPasscodeEnabled(): Promise<boolean>

Check if passcode authentication is enabled for the vault

Returns: Promise<boolean> whether or not the passcode is enabled

isPasscodeSetupNeeded

▸ isPasscodeSetupNeeded(): Promise<boolean>

Check whether or not a passcode needs to be set for the vault using setPasscode

Returns: Promise<boolean> whether or not the passcode needs to be set

isSecureStorageModeEnabled

▸ isSecureStorageModeEnabled(): Promise<boolean>

Check if AuthMode.SecureStorage is enabled for the vault

Returns: Promise<boolean> whether or not the secure storage mode is enabled

lock

▸ lock(): Promise<void>

Lock the vault clearing the contents from memory and requiring biometrics or passcode to unlock

Returns: Promise<void>

remainingAttempts

▸ remainingAttempts(): Promise<number>

Check how many remaining failed attempts are left until vault clears

Returns: Promise<number> the number of remaining attempts

removeValue

▸ removeValue(key: string): Promise<void>

Removes data under the given key.

throws: VaultError - if vault is locked, or if passcode is enabled but passcode has not been setup

Parameters:

Name	Type	Description
key	`string`	the key to remove the value from

Returns: Promise<void>

setBiometricsEnabled

▸ setBiometricsEnabled(isBiometricsEnabled: boolean): Promise<void>

Enable/Disable Biometric authentication for the vault

throws: VaultError - if biometrics is unavailable or the vault is locked

Parameters:

Name	Type	Description
isBiometricsEnabled	`boolean`	whether or not biometrics should be enabled

Returns: Promise<void>

setPasscode

▸ setPasscode(passcode?: string): Promise<void>

Set or Change the passcode for the vault

throws: VaultError - if the vault is locked, passcode is disabled, user canceled pin prompt, or pin was mismatched

Parameters:

Name	Type	Description
`Optional` passcode	`string`	The passcode to set. If left null a native dialog will prompt the user to enter it.

Returns: Promise<void>

setPasscodeEnabled

▸ setPasscodeEnabled(isPasscodeEnabled: boolean): Promise<void>

Enable/Disable passcode authentication for the vault

throws: VaultError - if the vault is locked

Parameters:

Name	Type	Description
isPasscodeEnabled	`boolean`	whether or not passcode should be enabled

Returns: Promise<void>

setSecureStorageModeEnabled

▸ setSecureStorageModeEnabled(isSecureStorageModeEnabled: boolean): Promise<void>

Enable/Disable secure storage mode for the vault. Setting AuthMode.SecureStorage automatically disables passcode and biometric authentication and allows for session values to be stored persistently and securely at rest using the keychain but allowing the user to access the data without authenticating as long as the device is unlocked.

throws: VaultError - if the vault is locked

Parameters:

Name	Type	Description
isSecureStorageModeEnabled	`boolean`	whether or not secure storage mode should be enabled

Returns: Promise<void>

storeToken

▸ storeToken(token: any): Promise<void>

Store a value securely in the token slot. This is equivalent to calling storeValue("token", token).

throws: VaultError - if vault is locked, or if passcode is enabled but passcode has not been setup

Parameters:

Name	Type	Description
token	`any`	the value to store in the token slot

Returns: Promise<void>

storeValue

▸ storeValue(key: string, value: any): Promise<void>

Store data securely under the given key.

throws: VaultError - if vault is locked, or if passcode is enabled but passcode has not been setup

Parameters:

Name	Type	Description
key	`string`	the key to store in the value in
value	`any`	the value to store

Returns: Promise<void>

unlock

▸ unlock(usingPasscode?: boolean, passcode?: string): Promise<void>

Unlock the vault using either passcode or biometrics

throws: VaultError - if the vault is locked, the unlock type wasn't enabled, user canceled pin prompt, or pin was mismatched

Parameters:

Name	Type	Description
`Optional` usingPasscode	`boolean`	whether or not to use passcode to unlock the vault
`Optional` passcode	`string`	The passcode to use. If left null a native dialog will prompt the user to enter it.

Returns: Promise<void>

unsubscribe

▸ unsubscribe(): Promise<void>

Unsubscribe the instance from events about the vault.

Returns: Promise<void>

IdentityVaultUser

IdentityVaultUser:

The main class which you can extend in order to implement vault usage. @typeparam T must extend DefaultSession

usage:


_28interface MyCustomSession extends DefaultSession {
_28 // username & token are inherited
_28 email: string;
_28 age: number;
_28 nicknames: string[];
_28}
_28
_28export class IdentityService extends IonicIdentityVaultUser<MyCustomSession> {
_28
_28constructor(private http: HttpClient, private router: Router, platform: Platform) {
_28 super(platform, {
_28   authMode: AuthMode.BiometricAndPasscode,
_28   restoreSessionOnReady: false,
_28   unlockOnReady: false, // set true to auto prompt the user to unlock when vault is ready
_28   unlockOnAccess: true,
_28   lockAfter: 5000, // lock after 5 seconds in the background
_28   hideScreenOnBackground: true
_28 });
_28
_28 onVaultUnlocked(config: VaultConfig) {
_28   //Route to my home page
_28 }
_28
_28 onVaultLocked(event: LockEvent) {
_28   //Route to my login page
_28 }
_28
_28}

getAuthMode

▸ getAuthMode(): Promise<AuthMode>

Get the AuthMode for the vault.

Returns: Promise<AuthMode>

getBiometricType

▸ getBiometricType(): Promise<BiometricType>

Get the type of biometrics the device supports

Returns: Promise<BiometricType> the type of biometrics the device supports

getPlugin

▸ getPlugin(): IonicNativeAuthPlugin

Returns the underlying Plugin Implementation. This can be overriden in the sub class service to allow for a customer browser implementation. Note that when overriding this with a browser implementation you should use the storeValue/getValue functions with the key session to store & retrieve the session as described or by DefaultSession or the interface that extends it.

usage:


_10getPlugin(): IonicNativeAuthPlugin {
_10 if (this.platform.is('cordova')) {
_10   return super.getPlugin();
_10 }
_10 // MyCustomerBrowserImplementation must implement the IonicNativeAuthPlugin interface
_10 // make sure getValue('session') & storeValue('session') store & retrieve the session.
_10 return MyCustomBrowserImplementation();
_10}

Returns: IonicNativeAuthPlugin

getSession

▸ getSession(): Promise<T | undefined>

The stored session data

Returns: Promise<T | undefined>

Get the session from memory (without checking the vault for it)

Returns: Promise<T | undefined>

getVault

▸ getVault(): Promise<IdentityVault>

Get raw access to the underlying vault api

Returns: Promise<IdentityVault>

hasStoredSession

▸ hasStoredSession(): Promise<boolean>

Check if there are any saved sessions in the vault

Returns: Promise<boolean>

isBiometricsAvailable

▸ isBiometricsAvailable(): Promise<boolean>

Check whether or not biometrics is supported by the device and has been configured by the current user of the device

Returns: Promise<boolean> whether or not biometrics is available

isBiometricsEnabled

▸ isBiometricsEnabled(): Promise<boolean>

Check whether or not biometrics is enabled on the vault

Returns: Promise<boolean> whether or not biometrics is enabled

isBiometricsSupported

▸ isBiometricsSupported(): Promise<boolean>

Check whether or not biometrics is supported by the device

Returns: Promise<boolean> whether or not biometrics is supported

isPasscodeEnabled

▸ isPasscodeEnabled(): Promise<boolean>

Check if passcode authentication is enabled for the vault

Returns: Promise<boolean> whether or not the passcode is enabled

isSecureStorageModeEnabled

▸ isSecureStorageModeEnabled(): Promise<boolean>

Check if AuthMode.SecureStorage is enabled for the vault

Returns: Promise<boolean> whether or not the secure storage mode is enabled

lockOut

▸ lockOut(): Promise<void>

Lock the user out without clearing their secure session information from the vault

Returns: Promise<void>

▸ login(session: T, authMode?: AuthMode): Promise<void>

Parameters:

Name	Type	Description
session	`T`	the session to store
`Optional` authMode	AuthMode

Returns: Promise<void>

logout

▸ logout(): Promise<void>

Log the user out entirely, and forget any stored authentication tokens

Returns: Promise<void>

onConfigChange

▸ onConfigChange(state: VaultConfig): any

Called when there has been a configuration change in the vault

Parameters:

Name	Type
state	VaultConfig

Returns: any

onPasscodeRequest

▸ onPasscodeRequest(isPasscodeSetRequest: boolean): Promise<string | void>

Called when attempting passcode unlock to allow for user defined passcode prompts.

Parameters:

Name	Type	Description
isPasscodeSetRequest	`boolean`	Whether or not this is a request to set the passcode.

Returns: Promise<string | void>

a string to use as the passcode of undefined to use native prompts

onSessionRestoreError

▸ onSessionRestoreError(err: VaultError): any

Called when the session fails to auto restore

Parameters:

Name	Type	Description
err	VaultError	The VaultError or that occurred.

Returns: any

onSessionRestored

▸ onSessionRestored(session: T): any

Called when the session object is restored.

Parameters:

Name	Type	Description
session	`T`	The DefaultSession or user defined session that occurred.

Returns: any

onSetupError

▸ onSetupError(error: VaultError): any

Called when there is an error during vault setup

Parameters:

Name	Type	Description
error	VaultError	The VaultError that occurred.

Returns: any

onUnlockOnReadyError

▸ onUnlockOnReadyError(err: VaultError): any

Called when the automatically unlocking the vault after it is ready fails.

Parameters:

Name	Type	Description
err	VaultError	The VaultError or that occurred.

Returns: any

onVaultLocked

▸ onVaultLocked(event: LockEvent): any

Called when the vault has been locked

Parameters:

Name	Type	Description
event	LockEvent	The data about the lock event LockEvent

Returns: any

onVaultReady

▸ onVaultReady(state: VaultConfig): any

Called when the vault is ready

Parameters:

Name	Type
state	VaultConfig

Returns: any

A promise that resolves when the vault is successfully configured and available.

onVaultUnlocked

▸ onVaultUnlocked(state: VaultConfig): any

Called when the vault has been unlocked

Parameters:

Name	Type
state	VaultConfig

Returns: any

ready

▸ ready(): Promise<void>

Promise ensuring the user vault is ready to be accessed or denoting an error in setup;

Returns: Promise<void>

A promise that resolves when the vault is succesfully configured and available.

restoreSession

▸ restoreSession(): Promise<T | undefined>

Restore the session from the vault

Returns: Promise<T | undefined>

saveSession

▸ saveSession(session: T): Promise<void>

Store the session to the vault

Parameters:

Name	Type	Description
session	`T`	the session to store

Returns: Promise<void>

setAuthMode

▸ setAuthMode(authMode: AuthMode): Promise<void>

Set the AuthMode for the vault. The vault must be unlocked or this will throw an error.

throws: VaultError - If the vault is locked or the mode is unavailale due to device hardware

Parameters:

Name	Type	Description
authMode	AuthMode	The AuthMode to use.

Returns: Promise<void>

setBiometricsEnabled

▸ setBiometricsEnabled(isBiometricsEnabled: boolean): Promise<void>

Enable/Disable Biometric authentication

throws: VaultError - if biometrics is unavailable or the vault is locked

Parameters:

Name	Type	Description
isBiometricsEnabled	`boolean`	whether or not biometrics should be enabled

Returns: Promise<void>

setPasscode

▸ setPasscode(): Promise<void>

Set or change the passcode for the user This will call the onPasscodeRequest handler to allow for user defined passcode prompt. You can get more fine grain contol using the IdentityVault directly by calling getVault

throws: VaultError - if the vault is locked, passcode is disabled, user canceled pin prompt, or pin was mismatched

Returns: Promise<void>

setPasscodeEnabled

▸ setPasscodeEnabled(isPasscodeEnabled: boolean): Promise<void>

Enable/Disable passcode authentication. This will cause setPasscode to fire if passcode setup is required causing the onPasscodeRequest handler to fire to allow for user defined passcode prompt. You can get more fine grain contol using the IdentityVault directly by calling getVault

throws: VaultError - if the vault is locked

Parameters:

Name	Type	Description
isPasscodeEnabled	`boolean`	whether or not passcode should be enabled

Returns: Promise<void>

unlock

▸ unlock(authMode?: AuthMode): Promise<void>

Unlock the user's vault using the AuthMode configured for the vault or the override passed in to the call. This will call the onPasscodeRequest handler if the specified AuthMode allows for it to allow for user defined passcode prompt You can get more fine grain contol using the IdentityVault directly by calling getVault

Parameters:

Name	Type
`Optional` authMode	AuthMode

Returns: Promise<void>

IonicNativeAuthPlugin

IonicNativeAuthPlugin:

The native plugin

getVault

▸ getVault(config: PluginOptions): IdentityVault

Parameters:

Name	Type
config	PluginOptions

Returns: IdentityVault

LockEvent

LockEvent:

The lock event passed to the onVaultLocked handler.

saved

● saved: boolean

If the data was persisted to the device before lock

timeout

● timeout: boolean

If the lock was due to a background timeout

PluginConfiguration

PluginConfiguration:

The configuration returned from IonicNativeAuthPlugin when getConfig is called.

descriptor

● descriptor: VaultDescriptor

The values the uniquely identify the vault

hideScreenOnBackground

● hideScreenOnBackground: boolean

Obscures the app when backgrounded to avoid leaking sensitive information, such as financial statements or balances

isBiometricsEnabled

● isBiometricsEnabled: boolean

Whether biometric authentication is enabled for the vault

isPasscodeEnabled

● isPasscodeEnabled: boolean

Whether passcode authentication is enabled for the vault

isPasscodeSetupNeeded

● isPasscodeSetupNeeded: boolean

Whether a passcode needs to be set with setPasscode

isSecureStorageModeEnabled

● isSecureStorageModeEnabled: boolean

Whether AuthMode.SecureStorage is enabled for the vault

lockAfter

● lockAfter: number

The amount of number of milliseconds the app can be in the background for until the vault locks

PluginOptions

PluginOptions:

The options passed the the IonicNativeAuthPlugin when creating a vault with getVault

`<Optional>` allowSystemPinFallback

● allowSystemPinFallback: boolean

If biometric auth fails, allow system pin fallback.

Please note: when Android devices are set to allow system pin fallback, the behavior of the biometrics prompt changes. The OS biometric prompt will not report that biometrics failed nor that the user has been locked out of biometrics. It is only currently possible to know the user either canceled the authentication prompt, or was successful in verifying.

default: false

`<Optional>` androidPromptDescription

● androidPromptDescription: string

The description text for the Android authentication prompt.

default: null

`<Optional>` androidPromptNegativeButtonText

● androidPromptNegativeButtonText: string

The cancel text for the Android authentication prompt.

default: "Cancel"

`<Optional>` androidPromptSubtitle

● androidPromptSubtitle: string

The subtitle text for the Android authentication prompt.

default: null

`<Optional>` androidPromptTitle

● androidPromptTitle: string

The title text for the Android authentication prompt.

default: "Please Authenticate"

`<Optional>` hideScreenOnBackground

● hideScreenOnBackground: boolean

Obscures the app when backgrounded to avoid leaking sensitive information, such as financial statements or balances

`<Optional>` lockAfter

● lockAfter: number

The amount of number of milliseconds the app can be in the background for until the vault locks

`<Optional>` shouldClearVaultAfterTooManyFailedAttempts

● shouldClearVaultAfterTooManyFailedAttempts: boolean

After too many failed authentication attempts, should the vault be cleared?

default: true

username

● username: string

The username for the vault you wish to access

vaultId

● vaultId: string

The vaultId for the vault you wish to access

`<Optional>` onConfig

▸ onConfig(event: PluginConfiguration): any

A handler that will receive events any time the vault is configuration is changed

Parameters:

Name	Type
event	PluginConfiguration

Returns: any

`<Optional>` onError

▸ onError(error: VaultError): any

Called when there is an error during vault setup

Parameters:

Name	Type	Description
error	VaultError	The VaultError that occurred.

Returns: any

`<Optional>` onLock

▸ onLock(event: LockEvent): any

A handler that will receive events any time the vault is locked

Parameters:

Name	Type
event	LockEvent

Returns: any

`<Optional>` onReady

▸ onReady(vault: IdentityVault): any

Called when the vault is configured and available.

Parameters:

Name	Type	Description
vault	IdentityVault	The IdentityVault instance.

Returns: any

`<Optional>` onUnlock

▸ onUnlock(event: PluginConfiguration): any

A handler that will receive events any time the vault is unlocked

Parameters:

Name	Type
event	PluginConfiguration

Returns: any

VaultConfig

VaultConfig:

The configuration file returned to event handlers such as onConfigChange and onVaultReady.

`<Optional>` allowSystemPinFallback

● allowSystemPinFallback: boolean

If biometric auth fails, allow system pin fallback.

default: false

`<Optional>` androidPromptDescription

● androidPromptDescription: string

The description text for the Android authentication prompt.

default: null

`<Optional>` androidPromptNegativeButtonText

● androidPromptNegativeButtonText: string

The cancel text for the Android authentication prompt.

default: "Cancel"

`<Optional>` androidPromptSubtitle

● androidPromptSubtitle: string

The subtitle text for the Android authentication prompt.

default: null

`<Optional>` androidPromptTitle

● androidPromptTitle: string

The title text for the Android authentication prompt.

default: "Please Authenticate"

`<Optional>` authMode

● authMode: AuthMode

The AuthMode to configure a new vault with. Note: This will only affect newly created vaults. Vaults with existing data and configuration will use there previous configuration. They can be change by unlocking and then chaning the AuthMode.

default: * BiometricAndPasscode

`<Optional>` hideScreenOnBackground

● hideScreenOnBackground: boolean

Obscures the app when backgrounded to avoid leaking sensitive information, such as financial statements or balances

default: false

isPasscodeSetupNeeded

● isPasscodeSetupNeeded: boolean

Whether a passcode needs to be set with setPasscode

`<Optional>` lockAfter

● lockAfter: number

The amount of number of milliseconds the app can be in the background for until the vault locks. A value of 0 means the vault won't lock in the background.

default: 0

`<Optional>` shouldClearVaultAfterTooManyFailedAttempts

● shouldClearVaultAfterTooManyFailedAttempts: boolean

After too many failed authentication attempts, should the vault be cleared?

default: true

VaultDescriptor

VaultDescriptor:

An interface that describes the vault. In IdentityVaultUser this defaults to _lastUser & default you can optionally add this to the constructor to accomplish advanced use cases multi-tenant vaults.

username

● username: string

The username for the vault you wish to access

vaultId

● vaultId: string

The vaultId for the vault you wish to access

VaultError

VaultError:

An error that can be thrown by the plugin.

usage:


_14try {
_14vault.unlock();
_14} catch(e) {
_14 switch (e.code) {
_14   case VaultErrorCodes.AuthFailed:
_14     alert('You failed to authenticate!');
_14     break;
_14   case VaultErrorCodes.UserCanceledInteraction:
_14     alert('You cancelled the face id prompt!');
_14     break;
_14   default:
_14     throw e;
_14 }
_14}

code

● code: VaultErrorCodes

message

● message: string

VaultOptions

VaultOptions:

The options passed in to initialize the vault.

`<Optional>` allowSystemPinFallback

● allowSystemPinFallback: boolean

If biometric auth fails, allow system pin fallback.

default: false

`<Optional>` androidPromptDescription

● androidPromptDescription: string

The description text for the Android authentication prompt.

default: null

`<Optional>` androidPromptNegativeButtonText

● androidPromptNegativeButtonText: string

The cancel text for the Android authentication prompt.

default: "Cancel"

`<Optional>` androidPromptSubtitle

● androidPromptSubtitle: string

The subtitle text for the Android authentication prompt.

default: null

`<Optional>` androidPromptTitle

● androidPromptTitle: string

The title text for the Android authentication prompt.

default: "Please Authenticate"

`<Optional>` authMode

● authMode: AuthMode

default: * BiometricAndPasscode

`<Optional>` hideScreenOnBackground

● hideScreenOnBackground: boolean

Obscures the app when backgrounded to avoid leaking sensitive information, such as financial statements or balances

default: false

`<Optional>` lockAfter

● lockAfter: number

The amount of number of milliseconds the app can be in the background for until the vault locks. A value of 0 means the vault won't lock in the background.

default: 0

`<Optional>` restoreSessionOnReady

● restoreSessionOnReady: boolean

Whether or not to attempt to automatically restore the session when the vault is ready If restoreSessionOnReady and unlockOnAccess are both true the vault will be immediately unlocked & the session restored if onReady if the vault is in use.

default: false

`<Optional>` shouldClearVaultAfterTooManyFailedAttempts

● shouldClearVaultAfterTooManyFailedAttempts: boolean

After too many failed authentication attempts, should the vault be cleared?

default: true

`<Optional>` unlockOnAccess

● unlockOnAccess: boolean

Whether or not to attempt to automatically unlock the vault when a value is accessed. If restoreSessionOnReady and unlockOnAccess are both true the vault will be immediately unlocked & the session restored if onReady if the vault is in use.

default: false

`<Optional>` unlockOnReady

● unlockOnReady: boolean

Whether or not to attempt to automatically unlock the vault when the vault is ready

default: false

Type aliases

BiometricType

Ƭ BiometricType: "touchID" | "faceID" | "none"

The possible values returned by getBiometricType

Change Log

[4.1.0] (2020-04-29)

Bug Fixes

cordova: remove full paths in config file targets

Features

allowSystemPinFallback, shouldClearVaultAfterTooManyFailedAttempts, and `isLockedOutOfBiometrics

[4.0.1] (2020-04-17)

Bug Fixes

android: clear vault when there are too many failed bio unlock attempts
ios: clear vault when there are too many failed bio unlock attempts
allow install in cordova-android 9-dev

[4.0.0] (2020-04-08)

Bug Fixes

ios: swift 4.2 compilation issue

Features

android: AndroidX upgrade, Android Face ID support

BREAKING CHANGES

android: AndroidX is now required in projects with IV v4.

[3.6.4] (2020-05-13)

Bug Fixes

android: avoid KeyPermanentlyInvalidatedException problem on SDK 19 [SE-183]
ios: swift 4.2 compilation issue

[3.6.3] (2020-04-01)

Bug Fixes

ios: remove old vault upon reinstall

[3.6.2] (2020-02-28)

Bug Fixes

ios: clear the vault on lock when using InMemoryOnly mode

[3.6.1] (2020-02-05)

Bug Fixes

Android, iOS: fix an issue where if auto unlock or restore session fails the vault fails to fire the onVaultReady event

[3.6.0] (2019-12-20)

Features

add getKeys to IdentityVault
add removeValue to IdentityVault

[3.5.1] (2019-12-18)

Bug Fixes

android: properly call onVaultLocked after lock
ios: add screenProtectView on top window

[3.5.0] (2019-11-27)

Bug Fixes

Android: Fix issue where vault would crash if Android device only supported FaceMatch
vault-user: use the vault user methods to set the auth mode

Features

add isBiometricsSupported function

[3.4.8] (2019-11-08)

Bug Fixes

vault-user: use the vault user methods to set the auth mode

[3.4.7] (2019-09-09)

Bug Fixes

Android: Fix an issue where the vault would not be cleared when fingerprints were added or all fingerprints were removed on Android..

[3.4.6] (2019-08-07)

Bug Fixes

Android: fix an issue where adding a fingerprint to device after the app was open would not refresh whether biometrics was available or not

[3.4.5] (2019-07-27)

Bug Fixes

Android, iOS: getSession return type and default IonicIdentityVaultUser generic to DefaultSession

[3.4.4] (2019-07-25)

Bug Fixes

Android: Fixes an issue on Android where getBiometricType would return none if Biometrics was not enabled even though the device had biometric hardware.

[3.4.3] (2019-06-14)

Bug Fixes

Android: Fixed issue where when hideScreenInBackground feature was enabled screenshots would be disabled.

[3.4.2] (2019-06-14)

Bug Fixes

iOS: Fixed an issue where the hide screen in background functionality was broken

[3.4.1] (2019-06-06)

Bug Fixes

Android: fix issue where setBiometricsEnabled(false) would throw an error if biometrics was unavailable

[3.4.0] (2019-06-06)

Bug Fixes

iOS: fix an issue where if a user removed fingerprints after authentication storing the session would return an error rather than default to passcode only mode
iOS: Fix issue where getBiometricType would return none if TouchID or FaceID was present on device but the user was not enrolled.
iOS: fix issue with getBiometricType and issue where lock event was triggered when lock was called in secure storage mode

Features

Added android side of Secure Storage Mode
update Typescript/JS layer to support Secure Storage mode

[3.3.0] (2019-05-10)

Bug Fixes

Android, iOS: make the setting of the auth mode fault tolerant

Features

Android. iOS: add Biometric or Passcode mode

[3.2.3] (2019-04-29)

Bug Fixes

Android: fix bug in Android where FingerprintManager import was missing

[3.2.2] (2019-04-29)

Bug Fixes

fix release configuration issue where xlmns:android was incorrectly add to manifest

[3.2.1] (2019-04-27)

Bug Fixes

fix bug where plugin id was incorrect and didn't include scope

[3.2.0] (2019-04-26)

Features

Added getPlugin method which can be overridden in advanced use cases to provide custom implementations for PWA compatibility etc.

Bug Fixes

iOS: Fixed a bug on iOS where when using the hideScreenOnBackground flag the splashscreen may temporarily flash during biometric prompts.
Android: Fixed a bug on Android where isBiometricsAvailable would return true is some cases if No fingerprints were enrolled or fingerprint hardware wasn't available.
Android, iOS: Fixed a bug where getSession may incorrectly return undefined due to failing to wait for the plugin to be ready before returning.

[3.1.0] (2019-04-19)

Features

Added login method which clears the vault and stores the session passed to it.

[3.0.0] (2019-04-08)

Features

Added the ability to use onPasscodeRequest to use a custom pin prompt screen.
Made IdentityVaultUser a generic class to allow using the DefaultSession or extending it to type and store the session object.
Added support for advanced usages such as multi-tenant vaults by using the IonicNativeAuthPlugin and IdentityVault APIs directly.

Reference App
Configuring the Vault
Automatically adding your token to requests
Upgrading to v4.0.0
API Documentation
Index
Enumerations
- AuthMode
- VaultErrorCodes
Interfaces
Type aliases
- BiometricType
Change Log

Ionic Identity Vault

Installation​

Reference App​

Configuring the Vault​

Automatically adding your token to requests​

Upgrading to v4.0.0​

API Documentation​

Index​

Enumerations​

Interfaces​

Type aliases​

Enumerations​

AuthMode​

BiometricAndPasscode​

BiometricOnly​

BiometricOrPasscode​

InMemoryOnly​

PasscodeOnly​

SecureStorage​

VaultErrorCodes​

AuthFailed​

BiometricsNotEnabled​

InvalidArguments​

InvalidAuthMode​

InvalidatedCredential​

KeyNotFound​

MismatchedPasscode​

MissingPasscode​

PasscodeNotEnabled​

SecurityNotAvailable​

TooManyFailedAttempts​

Unknown​

UserCanceledInteraction​

VaultLocked​

VaultUnavailable​

Interfaces​

DefaultSession​

token​

username​

IdentityVault​

<Optional> config​

clear​

getBiometricType​

getConfig​

getKeys​

getToken​

getUsername​

getValue​

isBiometricsAvailable​

isBiometricsEnabled​

isBiometricsSupported​

isInUse​

isLocked​

isLockedOutOfBiometrics​

isPasscodeEnabled​

isPasscodeSetupNeeded​

isSecureStorageModeEnabled​

lock​

remainingAttempts​

removeValue​

setBiometricsEnabled​

setPasscode​

setPasscodeEnabled​

setSecureStorageModeEnabled​

storeToken​

storeValue​

unlock​

unsubscribe​

IdentityVaultUser​

getAuthMode​

getBiometricType​

getPlugin​

getSession​

getVault​

hasStoredSession​

isBiometricsAvailable​

isBiometricsEnabled​

isBiometricsSupported​

isPasscodeEnabled​

isSecureStorageModeEnabled​

Installation

Reference App

Configuring the Vault

Automatically adding your token to requests

Upgrading to v4.0.0

API Documentation

Index

Enumerations

Interfaces

Type aliases

Enumerations

AuthMode

BiometricAndPasscode

BiometricOnly

BiometricOrPasscode

InMemoryOnly

PasscodeOnly

SecureStorage

VaultErrorCodes

AuthFailed

BiometricsNotEnabled

InvalidArguments

InvalidAuthMode

InvalidatedCredential

KeyNotFound

MismatchedPasscode

MissingPasscode

PasscodeNotEnabled

SecurityNotAvailable

TooManyFailedAttempts

Unknown

UserCanceledInteraction

VaultLocked

VaultUnavailable

Interfaces

DefaultSession

token

username

IdentityVault

`<Optional>` config

clear

getBiometricType

getConfig

getKeys

getToken

getUsername

getValue

isBiometricsAvailable

isBiometricsEnabled

isBiometricsSupported

isInUse

isLocked

isLockedOutOfBiometrics

isPasscodeEnabled

isPasscodeSetupNeeded

isSecureStorageModeEnabled

lock

remainingAttempts

removeValue

setBiometricsEnabled

setPasscode

setPasscodeEnabled

setSecureStorageModeEnabled

storeToken

storeValue

unlock

unsubscribe

IdentityVaultUser

getAuthMode

getBiometricType

getPlugin

getSession

getVault

hasStoredSession

isBiometricsAvailable

isBiometricsEnabled

isBiometricsSupported

isPasscodeEnabled

isSecureStorageModeEnabled

lockOut