Version: 5.0

Getting Started with Identity Vault

Generate the Application

Before we explore the use of Identity Vault, we need to scaffold an application. In this section, we will generate a tabs-based @ionic/react application, perform some basic configuration, and add the iOS and Android platforms.

If you need to refresh your memory on the overall developer workflow for Capacitor, please do so now. However, here is a synopsis of the commands you will use the most while performing this tutorial:

npm start: Start the development server so the application can be run in the browser.
npm run build: Build the web portion of the application.
npx cap sync: Copy the web app and any new plugins into the native applications.
npx cap open android: Open Android Studio in order to build, run, and debug the application on Android.
npx cap open ios: Open Xcode in order to build, run, and debug the application on iOS.

Let's get started.

Terminal


_10ionic start iv-getting-started tabs --type=react

Use the Ionic CLI to generate the application.

Terminal


_10ionic start iv-getting-started tabs --type=react
_10cd iv-getting-started

Change directory into the newly generated project.

Terminal

capacitor.config.ts


_12import { CapacitorConfig } from '@capacitor/cli';
_12
_12const config: CapacitorConfig = {
_12  appId: 'io.ionic.gettingstartediv',
_12  appName: 'iv-getting-started',
_12  webDir: 'dist',
_12  server: {
_12    androidScheme: 'https',
_12  },
_12};
_12
_12export default config;

Change the appId to be something unique. The appId is used as the bundle ID / application ID. Therefore it should be a string that is unique to your organization and application. We will use io.ionic.gettingstartediv for this application.

It is best to do this before adding the iOS and Android platforms to ensure they are setup properly from the start.

Terminal

capacitor.config.ts


_10ionic start iv-getting-started-ac tabs --type=react
_10cd iv-getting-started
_10npm run build
_10ionic cap add android
_10ionic cap add ios

Build the application and install the platforms.

Terminal

capacitor.config.ts

package.json


_15{
_15  "name": "iv-getting-started",
_15  "version": "0.0.1",
_15  "author": "Ionic Framework",
_15  "homepage": "https://ionicframework.com/",
_15  "scripts": {
_15    "dev": "vite",
_15    "build": "tsc && vite build && cap sync",
_15    "preview": "vite preview",
_15    "test.e2e": "cypress run",
_15    "test.unit": "vitest",
_15    "lint": "eslint"
_15  },
_15  ...
_15}

We should do a cap sync with each build. Change the scripts in package.json to do this.

Use the Ionic CLI to generate the application.

Change directory into the newly generated project.

It is best to do this before adding the iOS and Android platforms to ensure they are setup properly from the start.

Build the application and install the platforms.

We should do a cap sync with each build. Change the scripts in package.json to do this.

Terminal


_10ionic start iv-getting-started tabs --type=react

Install Identity Vault

In order to install Identity Vault, you will need to use the ionic enterprise register command to register your product key. This will create a .npmrc file containing the product key.

If you have already performed that step for your production application, you can just copy the .npmrc file from your production project. Since this application is for learning purposes only, you don't need to obtain another key.

You can now install Identity Vault and sync the platforms:

Terminal


_10npm install @ionic-enterprise/identity-vault
_10npx cap sync

Create the Session Model

We first need to define the shape of the authentication session data via a TypeScript interface. Create a src/models directory and a src/models/Session.ts file.

src/models/Session.ts


_10export interface Session {
_10  firstName: string;
_10  lastName: string;
_10  email: string;
_10  accessToken: string;
_10  refreshToken: string;
_10}

Create the Utility Files

Our tutorial application will have a single vault that simulates storing our application's authentication session information. To manage this vault, we will create two utility files:

vault-factory: Builds either a Vault or BrowserVault depending on the whether our application is running in a web-native or web context, respectively. The BrowserVault only mimics the basic behavior of the Vault for the purpose of running on the web and provides no security, as there as none available in the browser context.
session-vault: Manages the vault and its contents.

`vault-factory`

Create a src/util folder and add a file named src/util/vault-factory.ts with the following contents:

src/util/vault-factory.ts


_10import { Capacitor } from '@capacitor/core';
_10import { BrowserVault, Vault } from '@ionic-enterprise/identity-vault';
_10
_10export const createVault = (): Vault | BrowserVault => {
_10  return Capacitor.isNativePlatform() ? new Vault() : new BrowserVault();
_10};

`session-vault`

The session-vault file will contain the functions that are used to manage the session vault for the application. Create the src/util/session-vault.ts file with the following contents. We will build the necessary functions in this tutorial.

src/util/session-vault.ts


_10import { createVault } from './vault-factory';

Create and Initialization the Vault

Before we use Identity Vault, we need to make sure that our vault is properly created and initialized. It is important to note that creation and initialization are different processes. Creation is performed when the module for the vault-factory utility file is constructed and is limited to the creation of a JavaScript object.

The initialization involves communication with the native layer. As such it is asynchronous. Since initialization needs to complete before we can begin normal operation of the application, we run the initialization and await its completion before the main application component is mounted.

warning

Awaiting the completion of initialization in this manner is a best-practice that should always be followed.

src/util/session-vault.ts

src/main.tsx


_10import { 
_10  BrowserVault, 
_10  Vault 
_10} from '@ionic-enterprise/identity-vault';
_10import { createVault } from './vault-factory';
_10
_10const vault: Vault | BrowserVault = createVault();

Create the vault using our factory function.

src/util/session-vault.ts

src/main.tsx


_10import { 
_10  BrowserVault, 
_10  Vault 
_10} from '@ionic-enterprise/identity-vault';
_10import { createVault } from './vault-factory';
_10import { Session } from '../models/Session';
_10
_10const vault: Vault | BrowserVault = createVault();
_10let session: Session | null = null;

Create the session variable. To sync the store with React, we will use useSyncExternalStore.

src/util/session-vault.ts

src/main.tsx


_19import { 
_19  BrowserVault,
_19  Vault,
_19  VaultType,
_19  DeviceSecurityType,
_19} from '@ionic-enterprise/identity-vault';
_19import { createVault } from './vault-factory';
_19import { Session } from '../models/Session';
_19
_19const vault: Vault | BrowserVault = createVault();
_19let session: Session | null = null;
_19
_19export const initializeVault = async (): Promise<void> => {
_19  await vault.initialize({
_19    key: 'io.ionic.gettingstartedivreact',
_19    type: VaultType.SecureStorage,
_19    deviceSecurityType: DeviceSecurityType.None,
_19  });
_19};

Create the initializeVault function from which we will perform all vault initialization. At this time, the only thing we need to do is pass a configuration object to our vault. The meaning of the configuration properties will be explained later.

src/util/session-vault.ts

src/main.tsx


_13import React from 'react';
_13import { createRoot } from 'react-dom/client';
_13import App from './App';
_13
_13import { initializeVault } from './util/session-vault';
_13
_13const container = document.getElementById('root');
_13const root = createRoot(container!);
_13initializeVault().then(() => root.render(
_13  <React.StrictMode>
_13    <App />
_13  </React.StrictMode>
_13));

In our src/main.tsx, execute the initializeVault function prior to rendering the React app.

Create the vault using our factory function.

Create the session variable. To sync the store with React, we will use useSyncExternalStore.

In our src/main.tsx, execute the initializeVault function prior to rendering the React app.

src/util/session-vault.ts

src/main.tsx


_10import { 
_10  BrowserVault, 
_10  Vault 
_10} from '@ionic-enterprise/identity-vault';
_10import { createVault } from './vault-factory';
_10
_10const vault: Vault | BrowserVault = createVault();

In this section, we created a vault using the key io.ionic.gettingstartediv. Our vault is a "Secure Storage" vault, which means that the information we store in the vault is encrypted in the keychain / keystore and is only visible to our application, but the vault is never locked. We will explore other types of vaults later in this tutorial.

Store a Value

Let's store some data in the vault. Here, we will:

Add the necessary code to utilize useSyncExternalStore.
Add a function to session-vault to store a session.
Add a button to our Tab1 page to store a fake session.

src/util/session-vault.ts


_37import { 
_37  BrowserVault,
_37  Vault,
_37  VaultType,
_37  DeviceSecurityType,
_37} from '@ionic-enterprise/identity-vault';
_37import { createVault } from './vault-factory';
_37import { Session } from '../models/Session';
_37
_37const vault: Vault | BrowserVault = createVault();
_37let session: Session | null = null;
_37let listeners: any[] = [];
_37
_37export const initializeVault = async (): Promise<void> => {
_37  await vault.initialize({
_37    key: 'io.ionic.gettingstartedivreact',
_37    type: VaultType.SecureStorage,
_37    deviceSecurityType: DeviceSecurityType.None,
_37  });
_37};
_37
_37export const getSnapshot = (): Session | null => {
_37  return session;
_37}
_37
_37export const subscribe = (listener: any) => {
_37  listeners = [...listeners, listener];
_37  return () => {
_37    listeners = listeners.filter((l) => l !== listener);
_37  };
_37};
_37
_37export const emitChange = () => {
_37  for (let listener of listeners) {
_37    listener();
_37  }
_37};

Before we add the logic to update the vault, we first need to add a small bit of boilerplate code in order to track the state of our session variable.

src/util/session-vault.ts


_43import { 
_43  BrowserVault,
_43  Vault,
_43  VaultType,
_43  DeviceSecurityType,
_43} from '@ionic-enterprise/identity-vault';
_43import { createVault } from './vault-factory';
_43import { Session } from '../models/Session';
_43
_43const vault: Vault | BrowserVault = createVault();
_43let session: Session | null = null;
_43let listeners: any[] = [];
_43
_43export const initializeVault = async (): Promise<void> => {
_43  await vault.initialize({
_43    key: 'io.ionic.gettingstartedivreact',
_43    type: VaultType.SecureStorage,
_43    deviceSecurityType: DeviceSecurityType.None,
_43  });
_43};
_43
_43export const getSnapshot = (): Session | null => {
_43  return session;
_43}
_43
_43export const subscribe = (listener: any) => {
_43  listeners = [...listeners, listener];
_43  return () => {
_43    listeners = listeners.filter((l) => l !== listener);
_43  };
_43};
_43
_43export const emitChange = () => {
_43  for (let listener of listeners) {
_43    listener();
_43  }
_43};
_43
_43export const storeSession = async (newSession: Session): Promise<void> => {
_43  await vault.setValue('session', newSession);
_43  session = newSession;
_43  emitChange();
_43}

Now that we can track the state of our session, we can create our function to store our data. We can store multiple items within the vault, each with their own key. For this application, we will store a single item with the key of session. The vault has a setValue() method that is used for this purpose. Modify src/util/session-vault.ts to store the session.

Before we add the logic to update the vault, we first need to add a small bit of boilerplate code in order to track the state of our session variable.

src/util/session-vault.ts


_37import { 
_37  BrowserVault,
_37  Vault,
_37  VaultType,
_37  DeviceSecurityType,
_37} from '@ionic-enterprise/identity-vault';
_37import { createVault } from './vault-factory';
_37import { Session } from '../models/Session';
_37
_37const vault: Vault | BrowserVault = createVault();
_37let session: Session | null = null;
_37let listeners: any[] = [];
_37
_37export const initializeVault = async (): Promise<void> => {
_37  await vault.initialize({
_37    key: 'io.ionic.gettingstartedivreact',
_37    type: VaultType.SecureStorage,
_37    deviceSecurityType: DeviceSecurityType.None,
_37  });
_37};
_37
_37export const getSnapshot = (): Session | null => {
_37  return session;
_37}
_37
_37export const subscribe = (listener: any) => {
_37  listeners = [...listeners, listener];
_37  return () => {
_37    listeners = listeners.filter((l) => l !== listener);
_37  };
_37};
_37
_37export const emitChange = () => {
_37  for (let listener of listeners) {
_37    listener();
_37  }
_37};

Notice that we have created a very light wrapper around the vault's setValue() method. This is often all that is required. It is best-practice to encapsulate the vault in a function like this one and only expose the functionality that makes sense for your application.

With the "store session" feature properly abstracted, add a button to the Tab1 page that will simulate logging in by storing some fake authentication data in the vault.

src/pages/Tab1.tsx


_31import { 
_31  IonContent, 
_31  IonHeader, 
_31  IonPage, 
_31  IonTitle, 
_31  IonToolbar,
_31} from '@ionic/react';
_31import ExploreContainer from '../components/ExploreContainer';
_31import './Tab1.css';
_31
_31const Tab1: React.FC = () => {
_31  return (
_31    <IonPage>
_31      <IonHeader>
_31        <IonToolbar>
_31          <IonTitle>Tab 1</IonTitle>
_31        </IonToolbar>
_31      </IonHeader>
_31      <IonContent fullscreen>
_31        <IonHeader collapse="condense">
_31          <IonToolbar>
_31            <IonTitle size="large">Tab 1</IonTitle>
_31          </IonToolbar>
_31        </IonHeader>
_31        <ExploreContainer name="Tab 1 page" />
_31      </IonContent>
_31    </IonPage>
_31  );
_31};
_31
_31export default Tab1;

We are currently displaying the generic starter "Explore Container" data.

src/pages/Tab1.tsx


_41import { 
_41  IonButton,
_41  IonContent, 
_41  IonHeader, 
_41  IonItem, 
_41  IonLabel, 
_41  IonList, 
_41  IonPage, 
_41  IonTitle, 
_41  IonToolbar,
_41} from '@ionic/react';
_41import './Tab1.css';
_41
_41const Tab1: React.FC = () => {
_41  return (
_41    <IonPage>
_41      <IonHeader>
_41        <IonToolbar>
_41          <IonTitle>Tab 1</IonTitle>
_41        </IonToolbar>
_41      </IonHeader>
_41      <IonContent fullscreen>
_41        <IonHeader collapse="condense">
_41          <IonToolbar>
_41            <IonTitle size="large">Tab 1</IonTitle>
_41          </IonToolbar>
_41        </IonHeader>
_41        
_41        <IonList>
_41          <IonItem>
_41            <IonLabel>
_41              <IonButton expand="block">Store</IonButton>
_41            </IonLabel>
_41          </IonItem>
_41        </IonList>
_41      </IonContent>
_41    </IonPage>
_41  );
_41};
_41
_41export default Tab1;

Replace the explore container with a list containing a button.

src/pages/Tab1.tsx


_52import { 
_52  IonButton,
_52  IonContent, 
_52  IonHeader, 
_52  IonItem, 
_52  IonLabel, 
_52  IonList, 
_52  IonPage, 
_52  IonTitle, 
_52  IonToolbar,
_52} from '@ionic/react';
_52import './Tab1.css';
_52import { storeSession } from '../util/session-vault';
_52
_52const Tab1: React.FC = () => {
_52  const storeClicked = async (): Promise<void> => {
_52    await storeSession({
_52      email: 'test@ionic.io',
_52      firstName: 'Tessa',
_52      lastName: 'Testsmith',
_52      accessToken: '4abf1d79-143c-4b89-b478-19607eb5ce97',
_52      refreshToken: '565111b6-66c3-4527-9238-6ea2cc017126',
_52    });
_52  };
_52
_52  return (
_52    <IonPage>
_52      <IonHeader>
_52        <IonToolbar>
_52          <IonTitle>Tab 1</IonTitle>
_52        </IonToolbar>
_52      </IonHeader>
_52      <IonContent fullscreen>
_52        <IonHeader collapse="condense">
_52          <IonToolbar>
_52            <IonTitle size="large">Tab 1</IonTitle>
_52          </IonToolbar>
_52        </IonHeader>
_52        
_52        <IonList>
_52          <IonItem>
_52            <IonLabel>
_52              <IonButton expand="block" onClick={storeClicked}>Store</IonButton>
_52            </IonLabel>
_52          </IonItem>
_52        </IonList>
_52      </IonContent>
_52    </IonPage>
_52  );
_52};
_52
_52export default Tab1;

Store some fake test data.

We are currently displaying the generic starter "Explore Container" data.

Replace the explore container with a list containing a button.

Store some fake test data.

src/pages/Tab1.tsx


_31import { 
_31  IonContent, 
_31  IonHeader, 
_31  IonPage, 
_31  IonTitle, 
_31  IonToolbar,
_31} from '@ionic/react';
_31import ExploreContainer from '../components/ExploreContainer';
_31import './Tab1.css';
_31
_31const Tab1: React.FC = () => {
_31  return (
_31    <IonPage>
_31      <IonHeader>
_31        <IonToolbar>
_31          <IonTitle>Tab 1</IonTitle>
_31        </IonToolbar>
_31      </IonHeader>
_31      <IonContent fullscreen>
_31        <IonHeader collapse="condense">
_31          <IonToolbar>
_31            <IonTitle size="large">Tab 1</IonTitle>
_31          </IonToolbar>
_31        </IonHeader>
_31        <ExploreContainer name="Tab 1 page" />
_31      </IonContent>
_31    </IonPage>
_31  );
_31};
_31
_31export default Tab1;

We have stored data in our vault. The next step is to get the data back out of the vault.

Get a Value

In order to better illustrate the operation of the vault, we will modify the Tab1Page to display our session if one is stored. We can get the current session data with useSyncExternalStore.

src/pages/Tab1.tsx


_64import { 
_64  IonButton,
_64  IonContent, 
_64  IonHeader, 
_64  IonItem, 
_64  IonLabel, 
_64  IonList, 
_64  IonPage, 
_64  IonTitle, 
_64  IonToolbar,
_64} from '@ionic/react';
_64import { useSyncExternalStore } from 'react';
_64import './Tab1.css';
_64import { storeSession, subscribe, getSnapshot } from '../util/session-vault';
_64
_64const Tab1: React.FC = () => {
_64  const session = useSyncExternalStore(subscribe, getSnapshot);
_64
_64  const storeClicked = async (): Promise<void> => {
_64    await storeSession({
_64      email: 'test@ionic.io',
_64      firstName: 'Tessa',
_64      lastName: 'Testsmith',
_64      accessToken: '4abf1d79-143c-4b89-b478-19607eb5ce97',
_64      refreshToken: '565111b6-66c3-4527-9238-6ea2cc017126',
_64    });
_64  };
_64
_64  return (
_64    <IonPage>
_64      <IonHeader>
_64        <IonToolbar>
_64          <IonTitle>Tab 1</IonTitle>
_64        </IonToolbar>
_64      </IonHeader>
_64      <IonContent fullscreen>
_64        <IonHeader collapse="condense">
_64          <IonToolbar>
_64            <IonTitle size="large">Tab 1</IonTitle>
_64          </IonToolbar>
_64        </IonHeader>
_64        
_64        <IonList>
_64          <IonItem>
_64            <IonLabel>
_64              <IonButton expand="block" onClick={storeClicked}>Store</IonButton>
_64            </IonLabel>
_64          </IonItem>
_64
_64          <IonItem>
_64            <div>
_64              <div>{ session?.email }</div>
_64              <div>{ session?.firstName } { session?.lastName }</div>
_64              <div>{ session?.accessToken }</div>
_64              <div>{ session?.refreshToken }</div>
_64            </div>
_64          </IonItem>
_64        </IonList>
_64      </IonContent>
_64    </IonPage>
_64  );
_64};
_64
_64export default Tab1;

This displays the session when the user presses the "Store" button. However, if you refresh the browser or restart the application, the session data is no longer displayed. That is because our session variable was cleared.

src/util/session-vault.ts


_51import { 
_51  BrowserVault,
_51  Vault,
_51  VaultType,
_51  DeviceSecurityType,
_51} from '@ionic-enterprise/identity-vault';
_51import { createVault } from './vault-factory';
_51import { Session } from '../models/Session';
_51
_51const vault: Vault | BrowserVault = createVault();
_51let session: Session | null = null;
_51let listeners: any[] = [];
_51
_51export const initializeVault = async (): Promise<void> => {
_51  await vault.initialize({
_51    key: 'io.ionic.gettingstartedivreact',
_51    type: VaultType.SecureStorage,
_51    deviceSecurityType: DeviceSecurityType.None,
_51  });
_51};
_51
_51export const getSnapshot = (): Session | null => {
_51  return session;
_51}
_51
_51export const subscribe = (listener: any) => {
_51  listeners = [...listeners, listener];
_51  return () => {
_51    listeners = listeners.filter((l) => l !== listener);
_51  };
_51};
_51
_51export const emitChange = () => {
_51  for (let listener of listeners) {
_51    listener();
_51  }
_51};
_51
_51export const storeSession = async (newSession: Session): Promise<void> => {
_51  await vault.setValue('session', newSession);
_51  session = newSession;
_51  emitChange();
_51}
_51
_51export const getSession = async (): Promise<void> => {
_51  if (session === null) {
_51    if (await vault.isEmpty()) session = null; 
_51    else session = await vault.getValue<Session>('session');
_51  }
_51  emitChange()
_51};

Add a function to session-vault that encapsulates getting the session. Checking if the vault is empty first ensures that we don't try to unlock a vault that may be locked but empty, which can happen in some cases.

src/util/session-vault.ts


_53import { 
_53  BrowserVault,
_53  Vault,
_53  VaultType,
_53  DeviceSecurityType,
_53} from '@ionic-enterprise/identity-vault';
_53import { createVault } from './vault-factory';
_53import { Session } from '../models/Session';
_53
_53const vault: Vault | BrowserVault = createVault();
_53let session: Session | null = null;
_53let listeners: any[] = [];
_53
_53export const initializeVault = async (): Promise<void> => {
_53  await vault.initialize({
_53    key: 'io.ionic.gettingstartedivreact',
_53    type: VaultType.SecureStorage,
_53    deviceSecurityType: DeviceSecurityType.None,
_53  });
_53
_53  await getSession()
_53};
_53
_53export const getSnapshot = (): Session | null => {
_53  return session;
_53}
_53
_53export const subscribe = (listener: any) => {
_53  listeners = [...listeners, listener];
_53  return () => {
_53    listeners = listeners.filter((l) => l !== listener);
_53  };
_53};
_53
_53export const emitChange = () => {
_53  for (let listener of listeners) {
_53    listener();
_53  }
_53};
_53
_53export const storeSession = async (newSession: Session): Promise<void> => {
_53  await vault.setValue('session', newSession);
_53  session = newSession;
_53  emitChange();
_53}
_53
_53export const getSession = async (): Promise<void> => {
_53  if (session === null) {
_53    if (await vault.isEmpty()) session = null; 
_53    else session = await vault.getValue<Session>('session');
_53  }
_53  emitChange()
_53};

Add our getSession function to the initializeVault function so that we fetch vault data upon initialization.

src/util/session-vault.ts


_51import { 
_51  BrowserVault,
_51  Vault,
_51  VaultType,
_51  DeviceSecurityType,
_51} from '@ionic-enterprise/identity-vault';
_51import { createVault } from './vault-factory';
_51import { Session } from '../models/Session';
_51
_51const vault: Vault | BrowserVault = createVault();
_51let session: Session | null = null;
_51let listeners: any[] = [];
_51
_51export const initializeVault = async (): Promise<void> => {
_51  await vault.initialize({
_51    key: 'io.ionic.gettingstartedivreact',
_51    type: VaultType.SecureStorage,
_51    deviceSecurityType: DeviceSecurityType.None,
_51  });
_51};
_51
_51export const getSnapshot = (): Session | null => {
_51  return session;
_51}
_51
_51export const subscribe = (listener: any) => {
_51  listeners = [...listeners, listener];
_51  return () => {
_51    listeners = listeners.filter((l) => l !== listener);
_51  };
_51};
_51
_51export const emitChange = () => {
_51  for (let listener of listeners) {
_51    listener();
_51  }
_51};
_51
_51export const storeSession = async (newSession: Session): Promise<void> => {
_51  await vault.setValue('session', newSession);
_51  session = newSession;
_51  emitChange();
_51}
_51
_51export const getSession = async (): Promise<void> => {
_51  if (session === null) {
_51    if (await vault.isEmpty()) session = null; 
_51    else session = await vault.getValue<Session>('session');
_51  }
_51  emitChange()
_51};

We now have a way to store and retrieve the session. When you first run the application, the session area will be blank. When you press the Store button you will see the session information on the page. If you restart the application, you will see the session information.

If you would like to clear the session information at this point, remove the application from your device (physical or simulated) and re-install it. On the web, you can close the running tab and open new one.

Next we will see how to remove this data from within our application.

Remove the Session from the Vault

The vault has two different methods that we can use to remove the data:

clear: Clear all of the data stored in the vault and remove the vault from the keystore / keychain.
- This operation does not require the vault to be unlocked.
- This operation will remove the existing vault from the keychain / keystore.
- Subsequent operations on the vault such as storing a new session will not require the vault to be unlocked since the value had been removed.
- Use this method if your vault stores a single logical entity, even if it uses multiple entries to do so.
removeValue: Clear just the data stored with the specified key.
- This operation does require the vault to be unlocked.
- This operation will not remove the existing vault from the keychain / keystore even though the vault may be empty.
- Subsequent operations on the vault such as storing a new session may require the vault to be unlocked since the vault had been removed.
- Use this method if your vault stores multiple logical entities.

note

We will address locking and unlocking a vault later in this tutorial.

Our vault stores session information. Having a single vault that stores only the session information is the best-practice for this type of data, and it is the practice we are using here. Thus we will use the clear() method to clear the session.

src/util/session-vault.ts


_59import { 
_59  BrowserVault,
_59  Vault,
_59  VaultType,
_59  DeviceSecurityType,
_59} from '@ionic-enterprise/identity-vault';
_59import { createVault } from './vault-factory';
_59export const clearSession = async (): Promise<void> => {

Add a "Clear" button to the Tab1 page.

src/pages/Tab1.tsx


_77import { 
_77  IonButton,
_77  IonContent, 
_77  IonHeader, 
_77  IonItem, 
_77  IonLabel, 
_77  IonList, 
_77  IonPage, 
_77  IonTitle, 
_77  IonToolbar,
_77} from '@ionic/react';
_77import { useSyncExternalStore } from 'react';
_77import './Tab1.css';
_77import { 
_77  storeSession, 
_77  subscribe, 
_77  getSnapshot, 
_77  clearSession,
_77} from '../util/session-vault';
_77
_77const Tab1: React.FC = () => {
_77  const session = useSyncExternalStore(subscribe, getSnapshot);
_77
_77  const storeClicked = async (): Promise<void> => {
_77    await storeSession({
_77      email: 'test@ionic.io',
_77      firstName: 'Tessa',
_77      lastName: 'Testsmith',
_77      accessToken: '4abf1d79-143c-4b89-b478-19607eb5ce97',
_77      refreshToken: '565111b6-66c3-4527-9238-6ea2cc017126',
_77    });
_77  };
_77
_77  return (
_77    <IonPage>
_77      <IonHeader>
_77        <IonToolbar>
_77          <IonTitle>Tab 1</IonTitle>
_77        </IonToolbar>
_77      </IonHeader>
_77      <IonContent fullscreen>
_77        <IonHeader collapse="condense">
_77          <IonToolbar>
_77            <IonTitle size="large">Tab 1</IonTitle>
_77          </IonToolbar>
_77        </IonHeader>
_77        
_77        <IonList>
_77          <IonItem>
_77              <IonButton expand="block" onClick={storeClicked}>Store</IonButton>

Upon clicking the "Clear" button, the session data will be removed from the vault and will no longer render.

Updating the Vault Type

We are currently using a "Secure Storage" vault, but there are several other vault types. In this section, we will explore the DeviceSecurity, InMemory, and SecureStorage types.

Setting the Vault Type

We can use the vault's updateConfig() method to change the type of vault that the application is using.

src/util/session-vault.ts


_59import { 
_59  BrowserVault,
_59  Vault,
_59  VaultType,
_59  DeviceSecurityType,
_59} from '@ionic-enterprise/identity-vault';
_59import { createVault } from './vault-factory';
_59import { Session } from '../models/Session';
_59
_59const vault: Vault | BrowserVault = createVault();
_59let session: Session | null = null;
_59let listeners: any[] = [];
_59
_59export const initializeVault = async (): Promise<void> => {
_59  await vault.initialize({
_59    key: 'io.ionic.gettingstartedivreact',
_59    type: VaultType.SecureStorage,
_59    deviceSecurityType: DeviceSecurityType.None,
_59  });
_59
_59  await getSession()
_59};
_59
_59export const getSnapshot = (): Session | null => {
_59  return session;
_59}
_59
_59export const subscribe = (listener: any) => {
_59  listeners = [...listeners, listener];
_59  return () => {
_59    listeners = listeners.filter((l) => l !== listener);
_59  };
_59};
_59
_59export const emitChange = () => {
_59  for (let listener of listeners) {
_59    listener();
_59  }
_59};
_59
_59export const storeSession = async (newSession: Session): Promise<void> => {
_59  await vault.setValue('session', newSession);
_59  session = newSession;
_59  emitChange();
_59}
_59
_59export const getSession = async (): Promise<void> => {
_59  if (session === null) {
_59    if (await vault.isEmpty()) session = null; 
_59    else session = await vault.getValue<Session>('session');
_59  }
_59  emitChange()
_59};
_59
_59export const clearSession = async (): Promise<void> => {
_59  await vault.clear();
_59  session = null;
_59  emitChange();
_59}

Here is the session-vault.ts we've created thus far.

src/util/session-vault.ts


_64import { 
_64  BrowserVault,
_64  Vault,
_64  VaultType,
_64  DeviceSecurityType,
_64} from '@ionic-enterprise/identity-vault';
_64import { createVault } from './vault-factory';
_64import { Session } from '../models/Session';
_64
_64export type UnlockMode =
_64  | 'BiometricsWithPasscode'
_64  | 'InMemory'
_64  | 'SecureStorage';
_64
_64const vault: Vault | BrowserVault = createVault();
_64let session: Session | null = null;
_64let listeners: any[] = [];
_64
_64export const initializeVault = async (): Promise<void> => {
_64  await vault.initialize({
_64    key: 'io.ionic.gettingstartedivreact',
_64    type: VaultType.SecureStorage,
_64    deviceSecurityType: DeviceSecurityType.None,
_64  });
_64
_64  await getSession()
_64};
_64
_64export const getSnapshot = (): Session | null => {
_64  return session;
_64}
_64
_64export const subscribe = (listener: any) => {
_64  listeners = [...listeners, listener];
_64  return () => {
_64    listeners = listeners.filter((l) => l !== listener);
_64  };
_64};
_64
_64export const emitChange = () => {
_64  for (let listener of listeners) {
_64    listener();
_64  }
_64};
_64
_64export const storeSession = async (newSession: Session): Promise<void> => {
_64  await vault.setValue('session', newSession);
_64  session = newSession;
_64  emitChange();
_64}
_64
_64export const getSession = async (): Promise<void> => {
_64  if (session === null) {
_64    if (await vault.isEmpty()) session = null; 
_64    else session = await vault.getValue<Session>('session');
_64  }
_64  emitChange()
_64};
_64
_64export const clearSession = async (): Promise<void> => {
_64  await vault.clear();
_64  session = null;
_64  emitChange();
_64}

The UnlockMode specifies the logical combinations of settings we wish to support within our application.

src/util/session-vault.ts


_68import { 
_68  BrowserVault,
_68  Vault,
_68  VaultType,
_68  DeviceSecurityType,
_68} from '@ionic-enterprise/identity-vault';
_68import { createVault } from './vault-factory';
_68import { Session } from '../models/Session';
_68
_68export type UnlockMode =
_68  | 'BiometricsWithPasscode'
_68  | 'InMemory'
_68  | 'SecureStorage';
_68
_68const vault: Vault | BrowserVault = createVault();
_68let session: Session | null = null;
_68let listeners: any[] = [];
_68
_68export const initializeVault = async (): Promise<void> => {
_68  await vault.initialize({
_68    key: 'io.ionic.gettingstartedivreact',
_68    type: VaultType.SecureStorage,
_68    deviceSecurityType: DeviceSecurityType.None,
_68  });
_68
_68  await getSession()
_68};
_68
_68export const getSnapshot = (): Session | null => {
_68  return session;
_68}
_68
_68export const subscribe = (listener: any) => {
_68  listeners = [...listeners, listener];
_68  return () => {
_68    listeners = listeners.filter((l) => l !== listener);
_68  };
_68};
_68
_68export const emitChange = () => {
_68  for (let listener of listeners) {
_68    listener();
_68  }
_68};
_68
_68export const storeSession = async (newSession: Session): Promise<void> => {
_68  await vault.setValue('session', newSession);
_68  session = newSession;
_68  emitChange();
_68}
_68
_68export const getSession = async (): Promise<void> => {
_68  if (session === null) {
_68    if (await vault.isEmpty()) session = null; 
_68    else session = await vault.getValue<Session>('session');
_68  }
_68  emitChange()
_68};
_68
_68export const clearSession = async (): Promise<void> => {
_68  await vault.clear();
_68  session = null;
_68  emitChange();
_68}
_68
_68export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_68  
_68};

Add an updateUnlockMode() function. Take a single argument for the mode.

src/util/session-vault.ts


_71import { 
_71  BrowserVault,
_71  Vault,
_71  VaultType,
_71  DeviceSecurityType,
_71  IdentityVaultConfig,
_71} from '@ionic-enterprise/identity-vault';
_71import { createVault } from './vault-factory';
_71import { Session } from '../models/Session';
_71
_71export type UnlockMode =
_71  | 'BiometricsWithPasscode'
_71  | 'InMemory'
_71  | 'SecureStorage';
_71
_71const vault: Vault | BrowserVault = createVault();
_71let session: Session | null = null;
_71let listeners: any[] = [];
_71
_71export const initializeVault = async (): Promise<void> => {
_71  await vault.initialize({
_71    key: 'io.ionic.gettingstartedivreact',
_71    type: VaultType.SecureStorage,
_71    deviceSecurityType: DeviceSecurityType.None,
_71  });
_71
_71  await getSession()
_71};
_71
_71export const getSnapshot = (): Session | null => {
_71  return session;
_71}
_71
_71export const subscribe = (listener: any) => {
_71  listeners = [...listeners, listener];
_71  return () => {
_71    listeners = listeners.filter((l) => l !== listener);
_71  };
_71};
_71
_71export const emitChange = () => {
_71  for (let listener of listeners) {
_71    listener();
_71  }
_71};
_71
_71export const storeSession = async (newSession: Session): Promise<void> => {
_71  await vault.setValue('session', newSession);
_71  session = newSession;
_71  emitChange();
_71}
_71
_71export const getSession = async (): Promise<void> => {
_71  if (session === null) {
_71    if (await vault.isEmpty()) session = null; 
_71    else session = await vault.getValue<Session>('session');
_71  }
_71  emitChange()
_71};
_71
_71export const clearSession = async (): Promise<void> => {
_71  await vault.clear();
_71  session = null;
_71  emitChange();
_71}
_71
_71export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_71  const newConfig = { ...(vault.config as IdentityVaultConfig) };
_71
_71  await vault.updateConfig(newConfig);
_71};

The vault's updateConfig() method takes a full vault configuration object. We can grab our current config and cast it to IdentityVaultConfig to signify that we know the value is not undefined at this point. The new config will be used in the updateConfig() method.

src/util/session-vault.ts


_86import { 
_86  BrowserVault,
_86  Vault,
_86  VaultType,
_86  DeviceSecurityType,
_86  IdentityVaultConfig,
_86} from '@ionic-enterprise/identity-vault';
_86import { createVault } from './vault-factory';
_86import { Session } from '../models/Session';
_86
_86export type UnlockMode =
_86  | 'BiometricsWithPasscode'
_86  | 'InMemory'
_86  | 'SecureStorage';
_86
_86const vault: Vault | BrowserVault = createVault();
_86let session: Session | null = null;
_86let listeners: any[] = [];
_86
_86export const initializeVault = async (): Promise<void> => {
_86  await vault.initialize({
_86    key: 'io.ionic.gettingstartedivreact',
_86    type: VaultType.SecureStorage,
_86    deviceSecurityType: DeviceSecurityType.None,
_86  });
_86
_86  await getSession()
_86};
_86
_86export const getSnapshot = (): Session | null => {
_86  return session;
_86}
_86
_86export const subscribe = (listener: any) => {
_86  listeners = [...listeners, listener];
_86  return () => {
_86    listeners = listeners.filter((l) => l !== listener);
_86  };
_86};
_86
_86export const emitChange = () => {
_86  for (let listener of listeners) {
_86    listener();
_86  }
_86};
_86
_86export const storeSession = async (newSession: Session): Promise<void> => {
_86  await vault.setValue('session', newSession);
_86  session = newSession;
_86  emitChange();
_86}
_86
_86export const getSession = async (): Promise<void> => {
_86  if (session === null) {
_86    if (await vault.isEmpty()) session = null; 
_86    else session = await vault.getValue<Session>('session');
_86  }
_86  emitChange()
_86};
_86
_86export const clearSession = async (): Promise<void> => {
_86  await vault.clear();
_86  session = null;
_86  emitChange();
_86}
_86
_86export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_86  const newConfig = { ...(vault.config as IdentityVaultConfig) };
_86
_86  switch (mode) {
_86    case 'BiometricsWithPasscode': {
_86      newConfig.type = VaultType.DeviceSecurity;
_86      break;
_86    }
_86    case 'InMemory': {
_86      newConfig.type = VaultType.InMemory;
_86      break;
_86    }
_86    default: {
_86      newConfig.type = VaultType.SecureStorage;
_86      break;
_86    }
_86  }
_86
_86  await vault.updateConfig(newConfig);
_86};

Update the type based on the specified mode.

src/util/session-vault.ts


_89import { 
_89  BrowserVault,
_89  Vault,
_89  VaultType,
_89  DeviceSecurityType,
_89  IdentityVaultConfig,
_89} from '@ionic-enterprise/identity-vault';
_89import { createVault } from './vault-factory';
_89import { Session } from '../models/Session';
_89
_89export type UnlockMode =
_89  | 'BiometricsWithPasscode'
_89  | 'InMemory'
_89  | 'SecureStorage';
_89
_89const vault: Vault | BrowserVault = createVault();
_89let session: Session | null = null;
_89let listeners: any[] = [];
_89
_89export const initializeVault = async (): Promise<void> => {
_89  await vault.initialize({
_89    key: 'io.ionic.gettingstartedivreact',
_89    type: VaultType.SecureStorage,
_89    deviceSecurityType: DeviceSecurityType.None,
_89  });
_89
_89  await getSession()
_89};
_89
_89export const getSnapshot = (): Session | null => {
_89  return session;
_89}
_89
_89export const subscribe = (listener: any) => {
_89  listeners = [...listeners, listener];
_89  return () => {
_89    listeners = listeners.filter((l) => l !== listener);
_89  };
_89};
_89
_89export const emitChange = () => {
_89  for (let listener of listeners) {
_89    listener();
_89  }
_89};
_89
_89export const storeSession = async (newSession: Session): Promise<void> => {
_89  await vault.setValue('session', newSession);
_89  session = newSession;
_89  emitChange();
_89}
_89
_89export const getSession = async (): Promise<void> => {
_89  if (session === null) {
_89    if (await vault.isEmpty()) session = null; 
_89    else session = await vault.getValue<Session>('session');
_89  }
_89  emitChange()
_89};
_89
_89export const clearSession = async (): Promise<void> => {
_89  await vault.clear();
_89  session = null;
_89  emitChange();
_89}
_89
_89export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_89  const newConfig = { ...(vault.config as IdentityVaultConfig) };
_89
_89  switch (mode) {
_89    case 'BiometricsWithPasscode': {
_89      newConfig.type = VaultType.DeviceSecurity;
_89      newConfig.deviceSecurityType = DeviceSecurityType.Both;
_89      break;
_89    }
_89    case 'InMemory': {
_89      newConfig.type = VaultType.InMemory;
_89      newConfig.deviceSecurityType = DeviceSecurityType.None;
_89      break;
_89    }
_89    default: {
_89      newConfig.type = VaultType.SecureStorage;
_89      newConfig.deviceSecurityType = DeviceSecurityType.None;
_89      break;
_89    }
_89  }
_89
_89  await vault.updateConfig(newConfig);
_89};

Update the deviceSecurityType based on the value of the type.

Here is the session-vault.ts we've created thus far.

The UnlockMode specifies the logical combinations of settings we wish to support within our application.

Add an updateUnlockMode() function. Take a single argument for the mode.

Update the type based on the specified mode.

Update the deviceSecurityType based on the value of the type.

src/util/session-vault.ts


_59import { 
_59  BrowserVault,
_59  Vault,
_59  VaultType,
_59  DeviceSecurityType,
_59} from '@ionic-enterprise/identity-vault';
_59import { createVault } from './vault-factory';
_59import { Session } from '../models/Session';
_59
_59const vault: Vault | BrowserVault = createVault();
_59let session: Session | null = null;
_59let listeners: any[] = [];
_59
_59export const initializeVault = async (): Promise<void> => {
_59  await vault.initialize({
_59    key: 'io.ionic.gettingstartedivreact',
_59    type: VaultType.SecureStorage,
_59    deviceSecurityType: DeviceSecurityType.None,
_59  });
_59
_59  await getSession()
_59};
_59
_59export const getSnapshot = (): Session | null => {
_59  return session;
_59}
_59
_59export const subscribe = (listener: any) => {
_59  listeners = [...listeners, listener];
_59  return () => {
_59    listeners = listeners.filter((l) => l !== listener);
_59  };
_59};
_59
_59export const emitChange = () => {
_59  for (let listener of listeners) {
_59    listener();
_59  }
_59};
_59
_59export const storeSession = async (newSession: Session): Promise<void> => {
_59  await vault.setValue('session', newSession);
_59  session = newSession;
_59  emitChange();
_59}
_59
_59export const getSession = async (): Promise<void> => {
_59  if (session === null) {
_59    if (await vault.isEmpty()) session = null; 
_59    else session = await vault.getValue<Session>('session');
_59  }
_59  emitChange()
_59};
_59
_59export const clearSession = async (): Promise<void> => {
_59  await vault.clear();
_59  session = null;
_59  emitChange();
_59}

Why the `UnlockMode`?

One natural question from above may be "why create an UnlockMode type when you can pass in the VaultType and figure things out from there?" The answer to that is that any time you incorporate a third-party library into your code like this, you should create an "adapter" service that utilizes the library within the domain of your application.

This has two major benefits:

It insulates the rest of the application from change. If the next major version of Identity Vault has breaking changes that need to be addressed, the only place in the code they need to be addressed is in this service. The rest of the code continues to interact with the vault via the interface defined by the service.
It reduces vendor tie-in, making it easier to swap to different libraries in the future if need be.

The ultimate goal is for the only modules in the application directly import from @ionic-enterprise/identity-vault to be services like this one that encapsulate operations on a vault.

Setting the `deviceSecurityType` Value

The deviceSecurityType property only applies when the type is set to DeviceSecurity. We could use any of the following DeviceSecurityType values:

Biometrics: Use the system's default biometric option to unlock the vault.
SystemPasscode: Use the system's designated system passcode (PIN, Pattern, etc.) to unlock the vault.
Both: Primarily use the biometric hardware to unlock the vault, but use the system passcode as a backup for cases where the biometric hardware is not configured or biometric authentication has failed.

For our application, we will just keep it simple and use Both when using DeviceSecurity vault. This is a very versatile option and makes the most sense for most applications.

With vault types other than DeviceSecurity, always use DeviceSecurityType.None.

Update the `Tab1` Page

We can now add some buttons to the Tab1Page in order to try out the different vault types. Update the src/pages/Tab1.tsx as shown below.

src/pages/Tab1.tsx


_114import { 
_114  IonButton,
_114  IonContent, 
_114  IonHeader, 
_114  IonItem, 
_114  IonLabel, 
_114  IonList, 
_114  IonPage, 
_114  IonTitle, 
_114  IonToolbar,
_114} from '@ionic/react';
_114import { useSyncExternalStore } from 'react';
_114import './Tab1.css';
_114import { 
_114  storeSession, 
_114  subscribe, 
_114  getSnapshot, 
_114  clearSession,
_114  updateUnlockMode,
_114} from '../util/session-vault';
_114
_114const Tab1: React.FC = () => {
_114  const session = useSyncExternalStore(subscribe, getSnapshot);
_114
_114  const storeClicked = async (): Promise<void> => {
_114    await storeSession({
_114      email: 'test@ionic.io',
_114      firstName: 'Tessa',
_114      lastName: 'Testsmith',
_114      accessToken: '4abf1d79-143c-4b89-b478-19607eb5ce97',
_114      refreshToken: '565111b6-66c3-4527-9238-6ea2cc017126',
_114    });
_114  };
_114
_114  return (
_114    <IonPage>
_114      <IonHeader>
_114        <IonToolbar>
_114          <IonTitle>Tab 1</IonTitle>
_114        </IonToolbar>
_114      </IonHeader>
_114      <IonContent fullscreen>
_114        <IonHeader collapse="condense">
_114          <IonToolbar>
_114            <IonTitle size="large">Tab 1</IonTitle>
_114          </IonToolbar>
_114        </IonHeader>
_114        
_114        <IonList>
_114          <IonItem>
_114            <IonLabel>
_114              <IonButton expand="block" onClick={storeClicked}>Store</IonButton>
_114            </IonLabel>
_114          </IonItem>
_114
_114          <IonItem>
_114            <IonLabel>
_114              <IonButton 
_114                expand="block" 
_114                color="secondary" 
_114                onClick={() => updateUnlockMode('BiometricsWithPasscode')}
_114              >
_114                Use Biometrics
_114              </IonButton>
_114            </IonLabel>
_114          </IonItem>
_114
_114          <IonItem>
_114            <IonLabel>
_114              <IonButton 
_114                expand="block" 
_114                color="secondary" 
_114                onClick={() => updateUnlockMode('InMemory')}
_114              >
_114                Use In Memory
_114              </IonButton>
_114            </IonLabel>
_114          </IonItem>
_114
_114          <IonItem>

Build the application and run it on a device upon which you have biometrics enabled. Perform the following steps for each type of vault:

Press the "Store" button to put data in the vault.
Choose a vault type via one of the "Use" buttons.
Close the application (do not just put it in the background, but close it).
Restart the application.

You should see the following results:

"Use Biometrics": On an iPhone with FaceID, this will fail. We will fix that next. On all other devices, however, a biometric prompt will be displayed to unlock the vault. The data will be displayed once the vault is unlocked.
"Use In Memory": The data is no longer set. As the name implies, there is no persistence of this data.
"Use Secure Storage": The stored data is displayed without unlocking.

Native Configuration

If you tried the tests above on an iPhone with Face ID, your app should have crashed upon restarting when using a biometric vault. If you run npx cap sync you will see what is missing.


_10[warn] Configuration required for @ionic-enterprise/identity-vault.
_10       Add the following to Info.plist:
_10       <key>NSFaceIDUsageDescription</key>
_10       <string>Use Face ID to authenticate yourself and login</string>

Open the ios/App/App/Info.plist file and add the specified configuration. The actual string value can be anything you want, but the key must be NSFaceIDUsageDescription.

ios/App/App/Info.plist


_51<?xml version="1.0" encoding="UTF-8"?>
_51<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
_51<plist version="1.0">
_51  <dict>
_51    <key>CFBundleDevelopmentRegion</key>
_51    <string>Use Face ID to authenticate yourself and login</string>

Biometrics should work on the iPhone at this point.

Locking and Unlocking the Vault

Going forward we will begin exploring functionality that only works when the application is run on a device. As such, you should begin testing on a device instead of using the development server.

Right now, the only way to "lock" the vault is to close the application. In this section we will look at a couple of other ways to lock the vault as well as ways to unlock it.

Manually Locking the Vault

In src/util/session-vault.ts, wrap the vault's lock() method so we can use it in our Tab1Page.

src/util/session-vault.ts


_95import { 
_95  BrowserVault,
_95  Vault,
_95  VaultType,
_95  DeviceSecurityType,
_95  IdentityVaultConfig,
_95} from '@ionic-enterprise/identity-vault';
_95import { createVault } from './vault-factory';
_95import { Session } from '../models/Session';
_95
_95export type UnlockMode =
_95  | 'BiometricsWithPasscode'
_95  | 'InMemory'
_95  | 'SecureStorage';
_95
_95const vault: Vault | BrowserVault = createVault();
_95let session: Session | null = null;
_95let listeners: any[] = [];
_95
_95export const lockSession = async (): Promise<void> => {

Add a lock button in src/pages/Tab1.tsx.

src/pages/Tab1.tsx


_123import { 
_123  IonButton,
_123  IonContent, 
_123  IonHeader, 
_123  IonItem, 
_123  IonLabel, 
_123  IonList, 
_123  IonPage, 
_123  IonTitle, 
_123  IonToolbar,
_123} from '@ionic/react';
_123import { useSyncExternalStore } from 'react';
_123import './Tab1.css';
_123import { 
_123  storeSession, 
_123  subscribe, 
_123  getSnapshot, 
_123  clearSession,
_123  updateUnlockMode,
_123  lockSession,
_123} from '../util/session-vault';
_123
_123const Tab1: React.FC = () => {
_123  const session = useSyncExternalStore(subscribe, getSnapshot);
_123
_123  const storeClicked = async (): Promise<void> => {
_123    await storeSession({
_123      email: 'test@ionic.io',
_123      firstName: 'Tessa',
_123      lastName: 'Testsmith',
_123      accessToken: '4abf1d79-143c-4b89-b478-19607eb5ce97',
_123      refreshToken: '565111b6-66c3-4527-9238-6ea2cc017126',
_123    });
_123  };
_123
_123  return (
_123    <IonPage>
_123      <IonHeader>
_123        <IonToolbar>
_123          <IonTitle>Tab 1</IonTitle>
_123        </IonToolbar>
_123      </IonHeader>
_123      <IonContent fullscreen>
_123        <IonHeader collapse="condense">
_123          <IonToolbar>
_123            <IonTitle size="large">Tab 1</IonTitle>
_123          </IonToolbar>
_123        </IonHeader>
_123        
_123              <IonButton expand="block" color="warning" onClick={lockSession}>

When we press the "Lock" button, the session data is no longer displayed. The actual status of the vault depends on the last "unlock mode" button pressed prior to locking the vault.

"Use Biometrics": The vault has been locked and the session data will not be accessible until it is unlocked.
"Use In Memory": The session data no longer exists.
"Use Secure Storage": The session data is in the vault, but is not locked.

Unlocking the Vault

To verify the behaviors noted above, you need to be able to unlock the vault. To do this you can use the vault's unlock() method or you can perform an operation that requires the vault to be unlocked. When we unlock the vault, we need to restore the session data in our page, so we can just use our getSession() function. When it calls the vault's getValue(), the getValue() will attempt to unlock the vault.

Add the following code to src/pages/Tab1.tsx:

src/pages/Tab1.tsx


_132import { 
_132  IonButton,
_132  IonContent, 
_132  IonHeader, 
_132  IonItem, 
_132  IonLabel, 
_132  IonList, 
_132  IonPage, 
_132  IonTitle, 
_132  IonToolbar,
_132} from '@ionic/react';
_132import { useSyncExternalStore } from 'react';
_132import './Tab1.css';
_132import { 
_132  storeSession, 
_132  subscribe, 
_132  getSnapshot, 
_132  clearSession,
_132  updateUnlockMode,
_132  lockSession,
_132  getSession,
_132} from '../util/session-vault';
_132
_132const Tab1: React.FC = () => {
_132  const session = useSyncExternalStore(subscribe, getSnapshot);
_132
_132  const storeClicked = async (): Promise<void> => {
_132    await storeSession({
_132      email: 'test@ionic.io',
_132      firstName: 'Tessa',
_132      lastName: 'Testsmith',
_132      accessToken: '4abf1d79-143c-4b89-b478-19607eb5ce97',
_132      refreshToken: '565111b6-66c3-4527-9238-6ea2cc017126',
_132    });
_132  };
_132
_132  return (
_132    <IonPage>
_132      <IonHeader>
_132        <IonToolbar>
_132          <IonTitle>Tab 1</IonTitle>
_132        </IonToolbar>
_132      </IonHeader>
_132      <IonContent fullscreen>
_132              <IonButton expand="block" color="warning" onClick={getSession}>

We can now use the "Lock" and "Unlock" buttons to verify the behavior of each of our unlock modes.

Locking in the Background

We can manually lock our vault, but it would be nice if the vault locked for us automatically. This can be accomplished by setting lockAfterBackgrounded which will lock the vault when the application is resumed, if the app was backgrounded for the configured amount of time. We can configure this by doing two actions when initializing the vault:

Set the lockAfterBackgrounded value in the config. This value is specified in milliseconds.
Set the onLock callback so the session is cleared on lock.

src/util/session-vault.ts


_101import { 
_101  BrowserVault,
_101  Vault,
_101  VaultType,
_101  DeviceSecurityType,
_101  IdentityVaultConfig,
_101} from '@ionic-enterprise/identity-vault';
_101import { createVault } from './vault-factory';
_101import { Session } from '../models/Session';
_101
_101export type UnlockMode =
_101  | 'BiometricsWithPasscode'
_101  | 'InMemory'
_101  | 'SecureStorage';
_101
_101const vault: Vault | BrowserVault = createVault();
_101let session: Session | null = null;
_101let listeners: any[] = [];
_101
_101    lockAfterBackgrounded: 2000,

Architectural Considerations

Construction vs. Initialization

Have a look at the src/util/session-vault.ts file. Notice that it is very intentional about separating construction and initialization. This is very important.

Identity Vault allows you to pass the configuration object via the new Vault(cfg) constructor. This, however, will make asynchronous calls which makes construction indeterminate.

Always use a pattern of:

Construct the vault via new Vault() (default constructor, no configuration).
Pass the configuration to the vault.initialize(cfg) function.
Perform the initialization itself prior to mounting the application and make sure that the code is properly awaiting its completion.

Our code is currently automatically unlocking the vault upon startup due to our getSession function being invoked as part of our initialization logic. This is OK for our app, but it could be a problem if we had situations where multiple calls to get data from a locked vault all happened simultaneously. Always make sure you are controlling the vault lock status in such situations to ensure that only one unlock attempt is being made at a time.

We will see various strategies for this in later tutorials. You can also refer to our troubleshooting guide for further guidance.

Initial Vault Type Configuration

When we first initialize the vault we use the following configuration:


_10  await vault.initialize({
_10    key: 'io.ionic.gettingstartedivreact',
_10    type: VaultType.SecureStorage,
_10    deviceSecurityType: DeviceSecurityType.None,
_10    lockAfterBackgrounded: 2000,
_10  });

It is important to note that this is an initial configuration. Once a vault is created, it (and its current configuration) persist between invocations of the application. Thus, if the configuration of the vault is updated by the application, the updated configuration will be read when the application is reopened. For example, if the lockAfterBackgrounded has been updated to 5000 milliseconds, then when we start the application again with the vault already existing, lockAfterBackgrounded will remain set to 5000 milliseconds. The configuration we pass here is only used if we later destroy and re-create this vault.

Notice that we are specifying a type of VaultType.SecureStorage. It is best to use either VaultType.SecureStorage or VaultType.InMemeory when calling initialize() to avoid the potential of creating a vault of a type that cannot be supported. We can always update the type later after and the updated type will "stick." We want to start, however, with an option that will always word regardless of the device's configuration.

Single Vault vs Multiple Vaults

Identity Vault is ideal for storing small chunks of data such as authentication information or encryption keys. Our sample application contains a single vault. However, it may make sense to use multiple vaults within your application's architecture.

Ask yourself the following questions:

What type of data is stored?
Under what conditions should the data be available to the application?

Let's say the application is storing the following information:

The authentication session data.
A set of encryption keys.

You can use a single vault to store this data if all of the following are true:

You only want to access the vault via a single service.
The requirements for when the data is accessible is identical.

You should use multiple vaults to store this data if any of the following are true:

You logically want to use different services for different types of data.
You logically would like to use different services to access different types of data.
The requirements for when the data is accessible differs in some way. For example, perhaps the authentication information is locked behind a biometric key while access to the encryption keys requires a custom set in-app code to be entered.

If you decide to use multiple vaults, a best-practice is to create a separate service for each vault. That is, in the interest of proper organization within your code, each vault service should only manage a single vault.

Getting Started with Identity Vault

Generate the Application

Install Identity Vault

Create the Session Model

Create the Utility Files

`vault-factory`

`session-vault`

Create and Initialization the Vault

Store a Value

Get a Value

Remove the Session from the Vault

Updating the Vault Type

Setting the Vault Type

Why the `UnlockMode`?

Setting the `deviceSecurityType` Value

Update the `Tab1` Page

Native Configuration

Locking and Unlocking the Vault

Manually Locking the Vault

Unlocking the Vault

Locking in the Background

Architectural Considerations

Construction vs. Initialization

Control Unlocking on Startup and Navigation

Initial Vault Type Configuration

Single Vault vs Multiple Vaults

Contents

Generate the Application​

Install Identity Vault​

Create the Session Model​

Create the Utility Files​

vault-factory​

session-vault​

Create and Initialization the Vault​

Store a Value​

Get a Value​

Remove the Session from the Vault​

Updating the Vault Type​

Setting the Vault Type​

Why the UnlockMode?​

Setting the deviceSecurityType Value​

Update the Tab1 Page​

Native Configuration​

Locking and Unlocking the Vault​

Manually Locking the Vault​

Unlocking the Vault​

Locking in the Background​

Architectural Considerations​

Construction vs. Initialization​

Control Unlocking on Startup and Navigation​

Initial Vault Type Configuration​

Single Vault vs Multiple Vaults​

Contents

Generate the Application

Install Identity Vault

Create the Session Model

Create the Utility Files

`vault-factory`

`session-vault`

Create and Initialization the Vault

Store a Value

Get a Value

Remove the Session from the Vault

Updating the Vault Type

Setting the Vault Type

Why the `UnlockMode`?

Setting the `deviceSecurityType` Value

Update the `Tab1` Page

Native Configuration

Locking and Unlocking the Vault

Manually Locking the Vault

Unlocking the Vault

Locking in the Background

Architectural Considerations

Construction vs. Initialization

Control Unlocking on Startup and Navigation

Initial Vault Type Configuration

Single Vault vs Multiple Vaults