Identity Vault
#
Ionic Identity VaultThe 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.
#
InstallationIf you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.
Next, install the plugin:
- Capacitor
- Cordova
Important Note
If you're upgrading from the 3.0.0
to >=3.1.0
versions you no longer need to install 2 packages. The plugin now ships under the @ionic-enterprise/identity-vault
package. Simply run the commands below to upgrade. Imports and usage should remain identical.
#
Upgrade from v3.0.0 to >=v3.1.0First remove v3.0.0 of the plugin
You should make sure @ionic-enterprise/cordova-plugin-identity-vault
and cordova-plugin-identity-vault
are completely removed from your package.json in all locations.
It should now be safe to add >=v3.1.0 of the plugin
#
Configuring the VaultThe 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:
#
Automatically adding your token to requestsIf 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 DocumentationYou 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#
Interfaces- DefaultSession
- IdentityVault
- IdentityVaultUser
- IonicNativeAuthPlugin
- LockEvent
- PluginConfiguration
- PluginOptions
- VaultConfig
- VaultDescriptor
- VaultError
- VaultOptions
#
Type aliases#
Enumerations#
AuthModeAuthMode:
The type of authentication the vault should be configured to allow.
#
BiometricAndPasscodeBiometricAndPasscode:
Both biometric and passcode authentication should be allowed
#
BiometricOnlyBiometricOnly:
Biometrics authentication should only be allowed
#
InMemoryOnlyInMemoryOnly:
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.
#
PasscodeOnlyPasscodeOnly:
Passcode authentication should only be allowed
#
VaultErrorCodesVaultErrorCodes:
The meaning of the error code in the thrown VaultError
#
AuthFailedAuthFailed:
User authentication failed
#
BiometricsNotEnabledBiometricsNotEnabled:
The operation failed because biometric authentication is not enabled
#
InvalidArgumentsInvalidArguments:
The operation failed because the provided arguments were invalid
#
InvalidAuthModeInvalidAuthMode:
The AuthMode is invalid
#
InvalidatedCredentialInvalidatedCredential:
The credentials were invalidated. This can happen when a user changes biometrics or passcode.
#
KeyNotFoundKeyNotFound:
The key was not found. This can happen when a user changes biometrics or passcode.
#
MismatchedPasscodeMismatchedPasscode:
The user provided mismatched passcodes
#
MissingPasscodeMissingPasscode:
The operation requires passcode to be setup but it isn't set yet. Call setPasscode to set it.
#
PasscodeNotEnabledPasscodeNotEnabled:
The operation failed because passcode authentication is not enabled
#
SecurityNotAvailableSecurityNotAvailable:
Biometric security is unavailable
#
TooManyFailedAttemptsTooManyFailedAttempts:
Too many failed authentication attempts so the vault was cleared an user will need to login again
#
UnknownUnknown:
An unknown error happened
#
UserCanceledInteractionUserCanceledInteraction:
The user cancelled the native authentication dialog
#
VaultLockedVaultLocked:
The operation failed because the vault was locked
#
VaultUnavailableVaultUnavailable:
The operation failed because the vault was unavailable
#
Interfaces#
DefaultSessionDefaultSession:
The interface for the Default Session. Extend this interface to make a custom session
usage:
#
token● token: string
#
username● username: string
#
IdentityVaultIdentityVault:
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
>
#
IdentityVaultUserIdentityVaultUser:
The main class which you can extend in order to implement vault usage. @typeparam T
must extend DefaultSession
usage:
#
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:
Returns: IonicNativeAuthPlugin
#
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
>
#
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 |
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
#
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
>
#
IonicNativeAuthPluginIonicNativeAuthPlugin:
The native plugin
#
getVault▸ getVault(config: PluginOptions): IdentityVault
Parameters:
Name | Type |
---|---|
config | PluginOptions |
Returns: IdentityVault
#
LockEventLockEvent:
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
#
PluginConfigurationPluginConfiguration:
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
#
PluginOptionsPluginOptions:
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
#
VaultConfigVaultConfig:
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
#
VaultDescriptorVaultDescriptor:
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
#
VaultErrorVaultError:
An error that can be thrown by the plugin.
usage:
#
code● code: VaultErrorCodes
#
message● message: string
#
VaultOptionsVaultOptions:
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
#
Change Log#
[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.