Ionic Identity Vault

The Ionic Identity Vault is an all-in-one frontend identity management system that uses 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.

Configuring the Vault

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

_35

interface MyCustomSession extends DefaultSession {

_35

// username & token are inherited

_35

email: string;

_35

age: number;

_35

nicknames: string[];

_35

}

_35

_35

export class IdentityService extends IonicIdentityVaultUser<MyCustomSession> {

_35

_35

constructor(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(event: LockEvent) {

_35

//Route to my login page

_35

}

_35

_35

async onPasscodeRequest(isSetupRequest: 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. isSetupRequest

_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 user service to every request, you can see a simple example at in our demo repo.

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 used this to implement advanced workflows including multi tenant vaults.

Index

Enumerations

• AuthMode
• VaultErrorCodes

Interfaces

• DefaultSession
• IdentityVault
• IdentityVaultUser
• IonicNativeAuthPlugin
• LockEvent
• PluginConfiguration
• PluginOptions
• VaultConfig
• VaultDescriptor
• VaultError
• VaultOptions

Type aliases

• BiometricType

---

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

---

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

---

---

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

---

InvalidArguments

InvalidArguments:

The operation failed because the provided arguments were invalid

---

InvalidAuthMode

InvalidAuthMode:

The AuthMode is invalid

---

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 passcode authentication is not enabled

---

SecurityNotAvailable

SecurityNotAvailable:

Biometric security is unavailable

---

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

---

---

Interfaces

DefaultSession

DefaultSession:

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

usage:

_10

MyCustomSession 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

---

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

---

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

---

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

---

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

---

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>

---

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:

_28

interface MyCustomSession extends DefaultSession {

_28

// username & token are inherited

_28

email: string;

_28

age: number;

_28

nicknames: string[];

_28

}

_28

_28

export class IdentityService extends IonicIdentityVaultUser<MyCustomSession> {

_28

_28

constructor(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

---

getSession

▸ getSession(): Promise<T>

▸ getSession(): Promise<T | undefined>

The stored session data

Returns: Promise<T>

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

---

isPasscodeEnabled

▸ isPasscodeEnabled(): Promise<boolean>

Check if passcode authentication is enabled for the vault

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

---

lockOut

▸ lockOut(): Promise<void>

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

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

---

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

---

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

---

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

---

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

---

---

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:

_14

try {

_14

vault.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> 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

---

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

---