Skip to main content
Version: 6.0

Upgrading Identity Vault

Upgrading to v6.0.0​

Identity Vault 6.0.0 includes some important changes that you'll need to address when upgrading:

Removal of VaultMigrator​

The VaultMigrator functionality, which was previously used to migrate data from Identity Vault 4.x to 5.x, has been removed. If you are upgrading directly from Identity Vault 4.x, you should first upgrade to Identity Vault 5.x to perform the data migration before upgrading to 6.0.0.

Privacy Screen Changes​

The Device.setHideScreenOnBackground() method has been removed. Instead, you should use the @capacitor/privacy-screen plugin to handle privacy screen functionality:

  1. First, install the privacy screen plugin:

_10
npm install @capacitor/privacy-screen
_10
npx cap sync

  1. Replace any usage of Device.setHideScreenOnBackground() with the privacy screen plugin:

_23
import { PrivacyScreen } from '@capacitor/privacy-screen';
_23
_23
// Enable privacy screen (previously Device.setHideScreenOnBackground(true))
_23
await PrivacyScreen.enable();
_23
_23
// Optional: Configure platform-specific behavior
_23
await PrivacyScreen.enable({
_23
android: {
_23
dimBackground: true,
_23
preventScreenshots: true,
_23
// Use this to hide the screen when prompting for biometrics (version 1.1.0+)
_23
privacyModeOnActivityHidden: 'dim'
_23
},
_23
ios: {
_23
blurEffect: 'dark'
_23
}
_23
});
_23
_23
// Disable privacy screen (previously Device.setHideScreenOnBackground(false))
_23
await PrivacyScreen.disable();
_23
_23
// Check if privacy screen is enabled
_23
const { enabled } = await PrivacyScreen.isEnabled();

The privacy screen plugin provides more granular control over the privacy screen behavior on both Android and iOS platforms. Note that this plugin is only supported on mobile platforms and is not available for web.

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
_21
const vault = new Vault();
_21
await vault.initialize({
_21
// new V5 config
_21
});
_21
_21
try {
_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
}

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.

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
_10
authConfig.tokenStorageProvider = vaultService;
_10
_10
// Identity Vault 5
_10
authConfig.tokenStorageProvider = vaultService.vault;

Complete example:


_18
import { IonicAuth } from '@ionic-enterprise/auth';
_18
import { VaultService } from './vault.service';
_18
_18
@Injectable({
_18
providedIn: 'root'
_18
})
_18
export 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-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.

Contents