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.

// This is example code only
const vault = new Vault({
  // new V5 config
});

try {
  const migrator = new VaultMigrator({
    // old V4 config
  })
  const oldData = await migrator.exportVault();
  if (!!oldData) {
    // Import data into new vault
    await vault.importVault(oldData);
    // Remove all of the old data from the legacy vault
    await migrator.clear();
  }
} catch (err) {
  // Something went wrong...
  console.log("MIGRATOR ERROR: ", err.message);
}

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:

ionic generate service vault

Begin by changing the import statement to:

import { Device, DeviceSecurityType, Vault, 
         BrowserVault, VaultType } from '@ionic-enterprise/identity-vault';

Next, the service may be extending IonicIdentityVaultUser. Remove it and define a Vault object:

export class VaultService {
  vault: Vault | BrowserVault;

In the constructor or wherever Identity Vault is configured, remove the following Identity Vault v4 initialization/configuration:

constructor(public platform: Platform) {
  super(platform, {
    restoreSessionOnReady: false,
    unlockOnReady: false,
    unlockOnAccess: true,
    lockAfter: 1000,
    hideScreenOnBackground: true
  });
}

Instead, we'll use the new Vault object:

constructor() {
  this.init();
}

async init() {
  this.vault = new Vault({
    key: 'com.abc.appname',
    type: VaultType.DeviceSecurity,
    deviceSecurityType: DeviceSecurityType.Both,
    lockAfterBackgrounded: 2000,
    customPasscodeInvalidUnlockAttempts: 2,
    shouldClearVaultAfterTooManyFailedAttempts: true,
    unlockVaultOnLoad: false,
 });
}

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:

async init() {
  // snip - Vault configuration

  Device.setHideScreenOnBackground(true);
}

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:

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

// Identity Vault 4
authConfig.tokenStorageProvider = vaultService;

// Identity Vault 5
authConfig.tokenStorageProvider = vaultService.vault;

Complete example:

import { IonicAuth } from '@ionic-enterprise/auth';
import { VaultService } from './vault.service';

@Injectable({
  providedIn: 'root'
})
export class AuthenticationService extends IonicAuth {
  constructor(vaultService: VaultService) {
    let authConfig: IonicAuthOptions = {
      authConfig: 'auth0',
      platform: 'capacitor',
      // snip - other options
    };
    
    // Pass Identity Vault instance here
    authConfig.tokenStorageProvider = vaultService.vault;
    super(authConfig);
  }

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-android 9.x (see the 9.0.0 milestone for progress) or Capacitor 2.x.
  • For Capacitor, please see the upgrade guide for Android and iOS.
• Install the new plugin version.