Upgrading Identity Vault
Upgrading to v5.0.0
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.
_21// This is example code only_21const vault = new Vault();_21await vault.initialize({_21 // new V5 config_21});_21_21try {_21 const migrator = new VaultMigrator({_21 // old V4 config_21 })_21 const oldData = await migrator.exportVault();_21 if (!!oldData) {_21 // Import data into new vault_21 await vault.importVault(oldData);_21 // Remove all of the old data from the legacy vault_21 await migrator.clear();_21 }_21} catch (err) {_21 // Something went wrong..._21 console.log("MIGRATOR ERROR: ", err.message);_21}
Migrating from v4 to v5
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:
_10ionic generate service vault
Begin by changing the import statement to:
_10import { Device, DeviceSecurityType, Vault, _10 BrowserVault, VaultType } from '@ionic-enterprise/identity-vault';
Next, the service may be extending IonicIdentityVaultUser. Remove it and define a Vault object:
_10export class VaultService {_10 vault: Vault | BrowserVault;
In the constructor or wherever Identity Vault is configured, remove the following Identity Vault v4 initialization/configuration:
_10constructor(public platform: Platform) {_10 super(platform, {_10 restoreSessionOnReady: false,_10 unlockOnReady: false,_10 unlockOnAccess: true,_10 lockAfter: 1000,_10 hideScreenOnBackground: true_10 });_10}
Instead, we'll use the new Vault object:
_15constructor() {_15 this.init();_15}_15_15async init() {_15 this.vault = new Vault({_15 key: 'com.abc.appname',_15 type: VaultType.DeviceSecurity,_15 deviceSecurityType: DeviceSecurityType.Both,_15 lockAfterBackgrounded: 2000,_15 customPasscodeInvalidUnlockAttempts: 2,_15 shouldClearVaultAfterTooManyFailedAttempts: true,_15 unlockVaultOnLoad: false,_15 });_15}
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.
Comparison Table
Changes between objects, properties, and functions:
| IV 4 | IV 5 |
|---|---|
| IonicIdentityVaultUser | Vault |
| unlockOnReady | unlockVaultOnLoad |
| unlockOnAccess | Removed (always true). Any attempts to access any data in the locked vault will automatically try to unlock it. |
| lockAfter | lockAfterBackgrounded |
| shouldClearVaultAfterTooManyFailedAttempts | same |
| hideScreenOnBackground | Device.setHideScreenOnBackground(true) |
| vault.storeValue(key, value) | vault.setValue(key, value) |
| vault.hasStoredSession() | vault.doesVaultExist() |
| logout() | clear() |
Device API
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 Device API.
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 setHideScreenOnBackground method:
_10async init() {_10 // snip - Vault configuration_10_10 Device.setHideScreenOnBackground(true);_10}
View the complete Device API here.
Browser Support
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 BrowserVault instead:
_10export class BrowserAuthService implements IdentityVault { }
Securing Auth Connect Tokens
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 Vault object:
_10// Identity Vault 4_10authConfig.tokenStorageProvider = vaultService;_10_10// Identity Vault 5_10authConfig.tokenStorageProvider = vaultService.vault;
Complete example:
_18import { IonicAuth } from '@ionic-enterprise/auth';_18import { VaultService } from './vault.service';_18_18@Injectable({_18 providedIn: 'root'_18})_18export class AuthenticationService extends IonicAuth {_18 constructor(vaultService: VaultService) {_18 let authConfig: IonicAuthOptions = {_18 authConfig: 'auth0',_18 platform: 'capacitor',_18 // snip - other options_18 };_18 _18 // Pass Identity Vault instance here_18 authConfig.tokenStorageProvider = vaultService.vault;_18 super(authConfig);_18 }
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-android9.x (see the 9.0.0 milestone for progress) or Capacitor 2.x. - Install the new plugin version.