July 28, 2021
  • Product
  • authentication
  • Identity Vault
  • security

Announcing Identity Vault 5.0

Dallas James


Today I’m excited to announce Identity Vault 5.0, the newest version of Ionic’s mobile biometrics solution. Featuring the latest in native security best practices, Identity Vault improves frontend security in any Ionic app by making it easy to add secure biometric authentication in minutes.

We created Identity Vault after many concerned enterprise teams told us they weren’t confident in their frontend security implementations. The concern is valid: if a device falls into the wrong hands and an app’s data (such as authentication tokens) is compromised, users could be vulnerable to data loss and unauthorized access to their accounts. That’s really bad for users, and it’s also dangerous to the integrity of your backend systems and public perception.

It turns out that many frontend authentication workflows store tokens where anyone can view and access them (such as in LocalStorage) or using weak authentication logic (such as using miscellaneous Cordova plugins) that are easily compromised. Identity Vault keeps users protected with the latest in multi-layer native security and best practices for storing authentication data on-device.

But that’s not all that Identity Vault offers. There’s also:

  • Native security that protects user data from ever leaving the device
  • Safe, private, and encrypted storage of authentication tokens and other sensitive information
  • Agnostic backend design works with any authentication provider or custom API
  • Always-on Session Management to keep your users protected at all times
  • Modular, easy to consume service that integrates with any new or existing Web Native apps
  • Ongoing updates and maintenance, backed by Ionic’s mobile experts
  • Developer-friendly docs, tutorials, and videos to get you started
  • Advisory services and mission-critical support SLAs

Identity Vault 5.0 expands on the above, with an easier-to-use API, better React, Vue, and plain JavaScript compatibility, an enhanced local development experience, and flexible Android biometric options.

Easier to Use API

Identity Vault combines over twelve APIs and native features into a single plugin. That primarily includes ensuring user identity and session tokens are managed correctly — encrypted at rest and accessible only through biometric authentication mechanisms like facial recognition, fingerprint, or PIN. Then there are other security features such as background data hiding (privacy screen) and native session timeouts that make Identity Vault an all-in-one frontend security solution for mobile apps.

With so many features being added over time, user feedback informed us that the API was getting a bit robust and thus challenging to work with. So, we took a fresh approach and revamped the API to be simpler and easier to use.

Let’s take a quick tour of the main concepts using Angular as the example framework. First, we recommend creating a service named vault to encapsulate all the logic that interacts with the Vault:

ionic generate service vault

This creates a file named src/app/vault.service.ts. Next, import the Vault object, define an interface used to store session data, and call the init function from the constructor:

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

export interface VaultServiceState {
  session: string;  

  providedIn: 'root'

export class VaultService {
  public state: VaultServiceState = {
    session: ''    

  vault: Vault | BrowserVault;

  constructor() {

Next, instantiate the Vault with a variety of configuration options:

async init() {
  this.vault = new Vault({
     key: 'io.ionic.getstarted.ivangular',
     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.

A key feature of Identity Vault is the ability to store sensitive information encrypted at rest. This is possible using the setValue function, a key/value API:

private async storeValue(key: string, value: string): Promise<void> {
   await this.vault.setValue(key, value);

this.storeValue(“token”, “IONIC_FTW”);

Speaking of securing sensitive data, 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:

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

  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;


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:

<br />async init() {
  // snip - Vault configuration

This is just a taste of all that Identity Vault has to offer. To view all features, see the Identity Vault docs.

Better React, Vue, and Plain JS Compatibility

The original version of Identity Vault was built when most Ionic products, including Ionic Framework, only supported Angular. In addition to being simpler and easier to use, Identity Vault 5.0 moved away from the old inheritance-based mechanism of construction and configuration to a more functional approach. This simplifies both integrations in frameworks such as React and Vue and also helps it to feel more familiar with the JavaScript programming style. This means that teams looking to add biometric security to their apps will feel right at home using their framework of choice. Here’s how a React app uses Identity Vault (get started with Vue here):

First, create a file named src/hooks/useVault.ts. Within this file, we will create a hook that defines the vault and all functions needed to interact with the vault.

// src/hooks/useVault.ts
import { useMemo } from "react";
import { IdentityVaultConfig, Vault } from "@ionic-enterprise/identity-vault";

const config: IdentityVaultConfig = {
  key: "io.ionic.getstarted.ivreact",
  type: VaultType.DeviceSecurity,
  deviceSecurityType: DeviceSecurityType.Both,
  lockAfterBackgrounded: 2000,
  shouldClearVaultAfterTooManyFailedAttempts: true,
  customPasscodeInvalidUnlockAttempts: 2,
  unlockVaultOnLoad: false,

export const useVault = () => {
  const vault = useMemo(() => {
    const vault = new Vault(config);

    return vault;
  }, []);

While there are some React-specific concepts there, such as useMemo and the useVault hook declaration, the rest of the code is the same as the Angular example. Next, to store sensitive information encrypted at rest, we again use the setValue function, a key/value API:

const storeValue = async (key: string, value: string): Promise<void> => {
   await vault.setValue(key, value);

storeValue(“token”, “IONIC_FTW”);

Now, to use the vault, we can pull the useVault hook we just created into the Home page:

// Home.tsx
import { useVault } from "../hooks/useVault";

const Home: React.FC = () => {
  const { storeValue } = useVault();

  return (
      <IonContent fullscreen>
       <IonLabel>Enter the "session" data</IonLabel>
        <IonInput value={data} />

        <IonButton expand="block" onClick={() => storeValue(“session”, data)}>
           Set Session Data

As you can see, using Identity Vault in a React app combines biometric security with familiar React concepts, providing a solution that’s easy to drop in.

Enhanced Local Development Experience

Identity Vault is not supported in the browser, primarily since the browser does not have a secure location for storing data like mobile devices do (besides the built-in browser sandbox itself). Usually, we build Ionic apps locally in the browser to maintain the speed of web development, so to accomplish this with Identity Vault, a special class is available.

The BrowserVault is a new class that implements all the same methods as the standard vault. However, methods that require native interaction, such as biometric authentication, are stubbed out (effectively doing nothing when called) and all data is stored in LocalStorage.

The BrowserVault should be used conditionally based on the platform your application is running on:

import { Capacitor } from '@capacitor/core';

const vault = Capacitor.isNativePlatform()
                ? new Vault(config) 
                : new BrowserVault(config);

All vault methods should exhibit the same behavior, allowing your application to run as expected regardless of the platform it’s running on.

Flexible Android Biometric Security

Biometric security is classified into tiers based on architectural security (resiliency to compromise) and spoofability (resiliency to a dedicated attacker) tests. A biometric implementation can be classified as Class 3 (Strong) or Class 2 (Weak). Identity Vault 4 has always required the use of Class 3 biometrics to securely store data on a device. However, this meant that if a user on an Android device only had a Weak biometric option enabled, Identity Vault v4 would fail to authenticate the user unless a workaround was provided, such as using an app-specific passcode instead.

It’s important to note that all biometric classifications are unique to the device, meaning that the same biometric on one device can be rated as a Class 3 biometric, but rated as a Class 2 biometric on a different device. One prominent example of this is with Samsung devices. The Samsung Galaxy S10 has two main biometric features available, Fingerprint and FaceID. For this device, the Fingerprint scanner qualifies as a Class 3 security implementation whereas the FaceID only qualifies as a Class 2. The result of these classifications was that if a user only had FaceID configured, Identity Vault could not use that for biometric authentication. Contrast this against the Google Pixel 4, a device with a FaceID implementation that qualifies as Class 3 biometric security, allowing it to work with Identity Vault.

Identity Vault v5.0 still defaults to Class 3, but adds support for Class 2 biometrics on Android, adding more flexibility than previously available. Now, developers can choose their risk tolerance for the app, optionally permitting Class 2 biometrics for user authentication with no effort on their part.

Or, to check the supported biometric security class, use the Device API provided by Identity Vault:

const strength = Device.getBiometricStrengthLevel();

if (strength === BiometricSecurityStrength.Weak) {
  // User does not have a strong biometric feature available
  // Optionally throw an error, warn the user, or ignore

This fulfills our promise to always provide the latest in security best practices, so your team can rest assured that your apps and users are secure.

Migrating Vault Data from v4 to v5

The entire Vault API was redesigned in Identity Vault 5.0. 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 so you can pull your existing data out of the old vault and insert it into the new one.

// Create new Identity Vault 5 vault
const vault = new Vault({
  // new V5 config

const migrator = new VaultMigrator({
  // old V4 config

// Migrate the v4 vault to v5 once
if (!localStorage.vaultMigrated) {
  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();

    localStorage.vaultMigrated = true;

View complete migration details here.

Secure Your Apps Today

It’s never been more important to protect your apps and users. If you’d like to learn more about how Identity Vault is helping other enterprises make their apps more secure, reach out to sales to schedule a private demo and get customized pricing based on your needs. Or, try it in your app along with other Ionic native solutions with a free trial here.

You can also view our Identity Vault webinar which covers mobile security best practices and a live demo of Identity Vault 5.0’s new features.

Dallas James