Identity Vault API
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.
Identity Vault
#
Table of contents#
Enumerations#
Interfaces- DefaultSession
- IdentityVault
- IdentityVaultUser
- IonicNativeAuthPlugin
- LockEvent
- PluginConfiguration
- PluginOptions
- VaultConfig
- VaultDescriptor
- VaultError
- VaultOptions
#
Type aliases#
Type aliases#
BiometricTypeƬ BiometricType: touchID | faceID | none
The possible values returned by getBiometricType
deprecated
these types have been deprecated in favor of {@link SupportedBiometricTypes}
#
SupportedBiometricTypeƬ SupportedBiometricType: fingerprint | face | iris
The possible values returned by getAvailableHardware
Enums
#
Enumeration: AuthModeThe type of authentication the vault should be configured to allow.
#
Table of contents#
Enumeration members#
Enumeration members#
BiometricAndPasscode• BiometricAndPasscode: = 2
Both biometric and passcode authentication should be allowed
#
BiometricOnly• BiometricOnly: = 0
Biometrics authentication should only be allowed
#
BiometricOrPasscode• BiometricOrPasscode: = 4
Use biometrics if it is available, otherwise use passcode
#
InMemoryOnly• InMemoryOnly: = 3
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: = 1
Passcode authentication should only be allowed
#
SecureStorage• SecureStorage: = 5
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.
#
Enumeration: VaultErrorCodesThe meaning of the error code in the thrown VaultError
#
Table of contents#
Enumeration members- AuthFailed
- BiometricsNotEnabled
- InvalidArguments
- InvalidAuthMode
- InvalidatedCredential
- KeyNotFound
- MismatchedPasscode
- MissingPasscode
- PasscodeNotEnabled
- SecurityNotAvailable
- TooManyFailedAttempts
- Unknown
- UserCanceledInteraction
- VaultLocked
- VaultUnavailable
#
Enumeration members#
AuthFailed• AuthFailed: = 6
User authentication failed.
#
BiometricsNotEnabled• BiometricsNotEnabled: = 13
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: = 3
The operation failed because the some of the vault provided arguments were invalid.
#
InvalidAuthMode• InvalidAuthMode: = 14
The provided AuthMode is invalid. Should be one of AuthMode.
#
InvalidatedCredential• InvalidatedCredential: = 4
The credentials were invalidated. This can happen when a user changes biometrics or passcode.
#
KeyNotFound• KeyNotFound: = 12
The key was not found. This can happen when a user changes biometrics or passcode.
#
MismatchedPasscode• MismatchedPasscode: = 9
The user provided mismatched passcodes.
#
MissingPasscode• MissingPasscode: = 10
The operation requires passcode to be setup but it isn't set yet. Call setPasscode to set it.
#
PasscodeNotEnabled• PasscodeNotEnabled: = 11
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: = 5
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: = 7
Too many failed authentication attempts so the vault was cleared an user will need to login again.
#
Unknown• Unknown: = 0
An unknown error happened.
#
UserCanceledInteraction• UserCanceledInteraction: = 8
The user cancelled the native authentication dialog.
#
VaultLocked• VaultLocked: = 1
The operation failed because the vault was locked.
#
VaultUnavailable• VaultUnavailable: = 2
The operation failed because the vault was unavailable. The most likely cause of this error is that a vault has not been configured.
Interfaces
#
Interface: DefaultSessionThe interface for the Default Session. Extend this interface to make a custom session
usage
MyCustomSession extends DefaultSession { email: string; age: number; nicknames: string[];}
#
Table of contents#
Properties#
Properties#
token• token: string
#
username• username: string
#
Interface: IdentityVaultThe underlying vault API. You can gain direct access to the vault for more advanced usage by using the IdentityVaultUser.getVault method.
#
Table of contents#
Properties#
Methods- clear
- getAvailableHardware
- 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
#
Properties#
config• Optional
config: PluginConfiguration
The current configuration of the vault will stay current as long as unsubscribe is not called.
#
Methods#
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>
#
getAvailableHardware▸ getAvailableHardware(): Promise<SupportedBiometricType[]>
Gets the types of biometrics the device supports.
Please note, this method only shows the biometrics the device is capable of, and does not reflect whether the biometric methods are enrolled or enabled.
Traditionally Android has only supported fingerprint biometrics through the SDK. As of Android 10 multiple options are supported. Samsung devices can offer iris and face biometrics that exists outside the scope of the Android SDK. Since there is no official Android SDK support to detect those Samsung features, we attempt to determine their presence based on if the device has the Samsung face or iris biometrics software installed.
Returns: Promise<SupportedBiometricType[]>
the list of biometrics the device supports
#
getBiometricType▸ getBiometricType(): Promise<BiometricType>
Get the type of biometrics the device supports
deprecated
this method has been deprecated in favor of getAvailableHardware
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 |
---|---|---|
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 |
---|---|---|
usingPasscode? | boolean | whether or not to use passcode to unlock the vault |
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>
#
Interface: IdentityVaultUser<T>The main class which you can extend in order to implement vault usage.
typeparam
must extend DefaultSession
usage
interface MyCustomSession extends DefaultSession { // username & token are inherited email: string; age: number; nicknames: string[];}
export class IdentityService extends IonicIdentityVaultUser<MyCustomSession> {
constructor(private http: HttpClient, private router: Router, platform: Platform) { super(platform, { authMode: AuthMode.BiometricAndPasscode, restoreSessionOnReady: false, unlockOnReady: false, // set true to auto prompt the user to unlock when vault is ready unlockOnAccess: true, lockAfter: 5000, // lock after 5 seconds in the background hideScreenOnBackground: true });
onVaultUnlocked(config: VaultConfig) { //Route to my home page }
onVaultLocked(event: LockEvent) { //Route to my login page }
}
#
Type parametersName | Type | Default |
---|---|---|
T | object | DefaultSession |
#
Table of contents#
Methods- getAuthMode
- getBiometricType
- getPlugin
- getSession
- getVault
- hasStoredSession
- isBiometricsAvailable
- isBiometricsEnabled
- isBiometricsSupported
- isPasscodeEnabled
- isSecureStorageModeEnabled
- lockOut
- login
- logout
- onConfigChange
- onPasscodeRequest
- onSessionRestoreError
- onSessionRestored
- onSetupError
- onUnlockOnReadyError
- onVaultLocked
- onVaultReady
- onVaultUnlocked
- ready
- restoreSession
- saveSession
- setAuthMode
- setBiometricsEnabled
- setPasscode
- setPasscodeEnabled
- unlock
#
Methods#
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
getPlugin(): IonicNativeAuthPlugin { if (this.platform.is('cordova')) { return super.getPlugin(); } // MyCustomerBrowserImplementation must implement the IonicNativeAuthPlugin interface // make sure getValue('session') & storeValue('session') store & retrieve the session. return MyCustomBrowserImplementation();}
Returns: IonicNativeAuthPlugin
#
getSession▸ getSession(): Promise<undefined | T>
The stored session data
Returns: Promise<undefined | T>
▸ getSession(): Promise<undefined | T>
Get the session from memory (without checking the vault for it)
Returns: Promise<undefined | T>
#
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▸ login(session
: T, authMode?
: AuthMode): Promise<void>
Login a new session for the user. This method will clear the vault & any stored PIN for previously stored sessions.
#
Parameters:Name | Type | Description |
---|---|---|
session | T | the session to store |
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<undefined | T>
Restore the session from the vault
Returns: Promise<undefined | T>
#
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 |
---|---|
authMode? | AuthMode |
Returns: Promise<void>
#
Interface: IonicNativeAuthPluginThe native plugin
#
Table of contents#
Methods#
Methods#
getVault▸ getVault(config
: PluginOptions): IdentityVault
#
Parameters:Name | Type |
---|---|
config | PluginOptions |
Returns: IdentityVault
#
Interface: LockEventThe lock event passed to the onVaultLocked handler.
#
Table of contents#
Properties#
Properties#
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
#
Interface: PluginConfigurationThe configuration returned from IonicNativeAuthPlugin when getConfig is called.
#
Table of contents#
Properties- descriptor
- hideScreenOnBackground
- isBiometricsEnabled
- isPasscodeEnabled
- isPasscodeSetupNeeded
- isSecureStorageModeEnabled
- lockAfter
#
Properties#
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. App screenshots won't work on Android 10 devices using gesture navigation if this option is set to true.
#
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
#
Interface: PluginOptionsThe options passed the the IonicNativeAuthPlugin when creating a vault with getVault
#
Hierarchy↳ PluginOptions
#
Table of contents#
Properties- allowSystemPinFallback
- androidPromptDescription
- androidPromptNegativeButtonText
- androidPromptSubtitle
- androidPromptTitle
- hideScreenOnBackground
- lockAfter
- shouldClearVaultAfterTooManyFailedAttempts
- username
- vaultId
#
Methods#
Properties#
allowSystemPinFallback• Optional
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
#
androidPromptDescription• Optional
androidPromptDescription: string
The description text for the Android authentication prompt.
default
null
#
androidPromptNegativeButtonText• Optional
androidPromptNegativeButtonText: string
The cancel text for the Android authentication prompt.
default
"Cancel"
#
androidPromptSubtitle• Optional
androidPromptSubtitle: string
The subtitle text for the Android authentication prompt.
default
null
#
androidPromptTitle• Optional
androidPromptTitle: string
The title text for the Android authentication prompt.
default
"Please Authenticate"
#
hideScreenOnBackground• Optional
hideScreenOnBackground: boolean
Obscures the app when backgrounded to avoid leaking sensitive information, such as financial statements or balances. App screenshots won't work on Android 10 devices using gesture navigation if this option is set to true.
#
lockAfter• Optional
lockAfter: number
The amount of number of milliseconds the app can be in the background for until the vault locks
#
shouldClearVaultAfterTooManyFailedAttempts• Optional
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
Inherited from: VaultDescriptor.username
#
vaultId• vaultId: string
The vaultId for the vault you wish to access
Inherited from: VaultDescriptor.vaultId
#
Methods#
onConfig▸ Optional
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
#
onError▸ Optional
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
#
onLock▸ Optional
onLock(event
: LockEvent): any
A handler that will receive events any time the vault is locked
#
Parameters:Name | Type |
---|---|
event | LockEvent |
Returns: any
#
onReady▸ Optional
onReady(vault
: IdentityVault): any
Called when the vault is configured and available.
#
Parameters:Name | Type | Description |
---|---|---|
vault | IdentityVault | The IdentityVault instance. |
Returns: any
#
onUnlock▸ Optional
onUnlock(event
: PluginConfiguration): any
A handler that will receive events any time the vault is unlocked
#
Parameters:Name | Type |
---|---|
event | PluginConfiguration |
Returns: any
#
Interface: VaultConfigThe configuration file returned to event handlers such as onConfigChange and onVaultReady.
#
HierarchyVaultOptionsBase
↳ VaultConfig
#
Table of contents#
Properties- allowSystemPinFallback
- androidPromptDescription
- androidPromptNegativeButtonText
- androidPromptSubtitle
- androidPromptTitle
- authMode
- hideScreenOnBackground
- isPasscodeSetupNeeded
- lockAfter
- shouldClearVaultAfterTooManyFailedAttempts
#
Properties#
allowSystemPinFallback• Optional
allowSystemPinFallback: boolean
If biometric auth fails, allow system pin fallback.
default
false
#
androidPromptDescription• Optional
androidPromptDescription: string
The description text for the Android authentication prompt.
default
null
#
androidPromptNegativeButtonText• Optional
androidPromptNegativeButtonText: string
The cancel text for the Android authentication prompt.
default
"Cancel"
#
androidPromptSubtitle• Optional
androidPromptSubtitle: string
The subtitle text for the Android authentication prompt.
default
null
#
androidPromptTitle• Optional
androidPromptTitle: string
The title text for the Android authentication prompt.
default
"Please Authenticate"
#
authMode• Optional
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
#
hideScreenOnBackground• Optional
hideScreenOnBackground: boolean
Obscures the app when backgrounded to avoid leaking sensitive information, such as financial statements or balances. App screenshots won't work on Android 10 devices using gesture navigation if this option is set to true.
default
false
#
isPasscodeSetupNeeded• isPasscodeSetupNeeded: boolean
Whether a passcode needs to be set with setPasscode
#
lockAfter• Optional
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
#
shouldClearVaultAfterTooManyFailedAttempts• Optional
shouldClearVaultAfterTooManyFailedAttempts: boolean
After too many failed authentication attempts, should the vault be cleared?
default
true
#
Interface: VaultDescriptorAn 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.
#
HierarchyVaultDescriptor
#
Table of contents#
Properties#
Properties#
username• username: string
The username for the vault you wish to access
#
vaultId• vaultId: string
The vaultId for the vault you wish to access
#
Interface: VaultErrorAn error that can be thrown by the plugin.
usage
try { vault.unlock();} catch(e) { switch (e.code) { case VaultErrorCodes.AuthFailed: alert('You failed to authenticate!'); break; case VaultErrorCodes.UserCanceledInteraction: alert('You cancelled the face id prompt!'); break; default: throw e; }}
#
Table of contents#
Properties#
Properties#
code• code: VaultErrorCodes
#
message• message: string
#
Interface: VaultOptionsThe options passed in to initialize the vault.
#
HierarchyVaultOptionsBase
↳ VaultOptions
#
Table of contents#
Properties- allowSystemPinFallback
- androidPromptDescription
- androidPromptNegativeButtonText
- androidPromptSubtitle
- androidPromptTitle
- authMode
- hideScreenOnBackground
- lockAfter
- restoreSessionOnReady
- shouldClearVaultAfterTooManyFailedAttempts
- unlockOnAccess
- unlockOnReady
#
Properties#
allowSystemPinFallback• Optional
allowSystemPinFallback: boolean
If biometric auth fails, allow system pin fallback.
default
false
#
androidPromptDescription• Optional
androidPromptDescription: string
The description text for the Android authentication prompt.
default
null
#
androidPromptNegativeButtonText• Optional
androidPromptNegativeButtonText: string
The cancel text for the Android authentication prompt.
default
"Cancel"
#
androidPromptSubtitle• Optional
androidPromptSubtitle: string
The subtitle text for the Android authentication prompt.
default
null
#
androidPromptTitle• Optional
androidPromptTitle: string
The title text for the Android authentication prompt.
default
"Please Authenticate"
#
authMode• Optional
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
#
hideScreenOnBackground• Optional
hideScreenOnBackground: boolean
Obscures the app when backgrounded to avoid leaking sensitive information, such as financial statements or balances. App screenshots won't work on Android 10 devices using gesture navigation if this option is set to true.
default
false
#
lockAfter• Optional
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
#
restoreSessionOnReady• Optional
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
#
shouldClearVaultAfterTooManyFailedAttempts• Optional
shouldClearVaultAfterTooManyFailedAttempts: boolean
After too many failed authentication attempts, should the vault be cleared?
default
true
#
unlockOnAccess• Optional
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
#
unlockOnReady• Optional
unlockOnReady: boolean
Whether or not to attempt to automatically unlock the vault when the vault is ready
default
false