The entire Vault API was redesigned for Identity Vault 5. Because of this, it's not possible to access your stored vault data from version 4 using the new Vault API. To seamlessly handle this transition, we've created a
VaultMigrator class that you can use to pull your existing data out of the old vault and insert it into a new one.
The following migration steps use Angular for the code examples, but all steps are conceptually similar regardless of framework used.
If you don't have one already, we recommend creating a service named
vault to encapsulate all the logic that interacts with the Vault:
Begin by changing the import statement to:
Next, the service may be extending
IonicIdentityVaultUser. Remove it and define a
In the constructor or wherever Identity Vault is configured, remove the following Identity Vault v4 initialization/configuration:
Instead, we'll use the new
These options make up the core of how Identity Vault is configured. Apps can create multiple vaults, so provide a unique name in the
key field. The next option,
type, is the most important since it determines how the vault will be secured. We recommend most apps use
DeviceSecurity and device security type
Both as this utilizes biometrics followed by System Passcode to authenticate app users. Additional vault type options include
SecureStorage (no additional security is required in the app as long as the device was unlocked with a secure method),
CustomPasscode (user will set a custom passcode to access the vault), and
InMemory (data will persist only while the application is in memory).
The other major vault configuration options relate to locking the vault.
lockAfterBackgrounded will lock the vault after it has been in the background after the specified number of milliseconds has passed.
customPasscodeInvalidUnlockAttempts controls how many failed unlock attempts are allowed if
shouldClearVaultAfterTooManyFailedAttempts is enabled. If the limit is reached, all data stored in the vault is deleted. Finally,
unlockVaultOnLoad will attempt to unlock the vault when the app launches and resumes from the background.
See the comparison table below and the API page for all available configuration options.
Changes between objects, properties, and functions:
|IV 4||IV 5|
|unlockOnAccess||Removed (always true). Any attempts to access any data in the locked vault will automatically try to unlock it.|
|vault.storeValue(key, value)||vault.setValue(key, value)|
There are some capabilities that Identity Vault allows you to control that are applicable to the device that the application is running on rather than being applicable to any given vault. For these, you can use Identity Vault’s
The most notable feature is the "privacy screen." When an application is put into the background, the default OS behavior displays a screenshot of the current page while the user scrolls through the open applications. However, if your application displays sensitive information, you may not want that, so another option is to display the splash screen (on iOS) or a plain rectangle (on Android) instead of the screenshot. To hide the screen, use the
View the complete Device API here.
Identity Vault is not supported in the browser for a number of reasons, the primary among them being that the browser does not have a secure location for storing data like actual mobile devices do. Ideally, we'd like to continue development using our browser tools to maintain the speed of web development. To accomplish this, Identity Vault provides a special
BrowserVault class. Learn how to use it here.
You may have rolled your own Identity Vault web implementation, a class that implements
IdentityVault. You can delete it in favor of
Auth Connect, Ionic’s native solution for easy single sign-on implementations, is designed to work easily with Identity Vault. In just one line of code, Auth Connect’s logged-in credentials can be stored securely by passing an instance of Identity Vault to Auth Connect’s
tokenStorageProvider configuration option.
First, update to the latest version of Auth Connect. Then, assign the
tokenStorageProvider to the
If you have Identity Vault <3.1.0, please see Upgrading from v3.0.0 to >=v3.1.0 before following these upgrade instructions.