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 three 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-store: A custom hook that manages the state of the session within the application.
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-store`

Create a file named src/util/vault-store.ts that wraps the useSyncExternalStore hook.

src/util/vault-store.ts


_10import { Session } from '../models/Session';
_10
_10interface SessionState {
_10  session?: Session | null;
_10}
_10
_10let data: SessionState = {};

This part of the application's state consists of the session.

src/util/vault-store.ts


_10import { Session } from '../models/Session';
_10
_10interface SessionState {
_10  session?: Session | null;
_10}
_10
_10let data: SessionState = {};
_10const getSnapshot = (): SessionState => data;

useSyncExternalStore requires a getSnapshot that returns the current state.

src/util/vault-store.ts


_14import { Session } from '../models/Session';
_14
_14interface SessionState {
_14  session?: Session | null;
_14}
_14
_14let data: SessionState = {};
_14const getSnapshot = (): SessionState => data;
_14
_14const subscribers = new Set<() => void>();
_14const subscribe = (notify: () => void): (() => void) => {
_14  subscribers.add(notify);
_14  return () => subscribers.delete(notify);
_14};

useSyncExternalStore also requires the subscribers to be managed.

src/util/vault-store.ts


_19import { Session } from '../models/Session';
_19
_19interface SessionState {
_19  session?: Session | null;
_19}
_19
_19let data: SessionState = {};
_19const getSnapshot = (): SessionState => data;
_19
_19const subscribers = new Set<() => void>();
_19const subscribe = (notify: () => void): (() => void) => {
_19  subscribers.add(notify);
_19  return () => subscribers.delete(notify);
_19};
_19
_19export const setState = (update: Partial<SessionState>): void => {
_19  data = Object.freeze({ ...data, ...update });
_19  subscribers.forEach((notify) => notify());
_19};

Export a setState function to use to update the state from other parts of our app.

src/util/vault-store.ts


_24import { useSyncExternalStore } from 'react';
_24import { Session } from '../models/Session';
_24
_24interface SessionState {
_24  session?: Session | null;
_24}
_24
_24let data: SessionState = {};
_24const getSnapshot = (): SessionState => data;
_24
_24const subscribers = new Set<() => void>();
_24const subscribe = (notify: () => void): (() => void) => {
_24  subscribers.add(notify);
_24  return () => subscribers.delete(notify);
_24};
_24
_24export const setState = (update: Partial<SessionState>): void => {
_24  data = Object.freeze({ ...data, ...update });
_24  subscribers.forEach((notify) => notify());
_24};
_24
_24export const useSession = () => {
_24  return useSyncExternalStore(subscribe, getSnapshot);
_24};

Export our custom useSession hook.

This part of the application's state consists of the session.

useSyncExternalStore requires a getSnapshot that returns the current state.

useSyncExternalStore also requires the subscribers to be managed.

Export a setState function to use to update the state from other parts of our app.

Export our custom useSession hook.

src/util/vault-store.ts


_10import { Session } from '../models/Session';
_10
_10interface SessionState {
_10  session?: Session | null;
_10}
_10
_10let data: SessionState = {};

`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';
_10import { Session } from '../models/Session';
_10import { setState } from './session-store';

Create and Initialize 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';
_10import { Session } from '../models/Session';
_10import { setState } from './session-store';
_10
_10const vault: Vault | BrowserVault = createVault();

Create the vault using our factory function.

src/util/session-vault.ts

src/main.tsx


_24import { 
_24  BrowserVault,
_24  Vault,
_24  VaultType,
_24  DeviceSecurityType,
_24} from '@ionic-enterprise/identity-vault';
_24import { createVault } from './vault-factory';
_24import { Session } from '../models/Session';
_24import { setState } from './session-store';
_24
_24const vault: Vault | BrowserVault = createVault();
_24let session: Session | null = null;
_24
_24export const initializeVault = async (): Promise<void> => {
_24  try {
_24    await vault.initialize({
_24      key: 'io.ionic.gettingstartedivreact',
_24      type: VaultType.SecureStorage,
_24      deviceSecurityType: DeviceSecurityType.None,
_24    });
_24  } catch (e: unknown) {
_24    await vault.clear();
_24  }
_24};

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.

If the initialize() fails the best thing to do with the vault is to clear it.

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.

If the initialize() fails the best thing to do with the vault is to clear it.

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';
_10import { Session } from '../models/Session';
_10import { setState } from './session-store';
_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 a function to session-vault to store a session, using setState from session-store to update the state.
Add a button to our Tab1 page to store a fake session.

First, create a function to store the 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.

src/util/session-vault.ts


_28import { 
_28  BrowserVault,
_28  Vault,
_28  VaultType,
_28  DeviceSecurityType,
_28} from '@ionic-enterprise/identity-vault';
_28import { createVault } from './vault-factory';
_28export const storeSession = async (session: Session): Promise<void> => {

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 our custom useSession hook.

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 { useSession } from '../util/session-store';
_64import './Tab1.css';
_64import { storeSession } from '../util/session-vault';
_64
_64const Tab1: React.FC = () => {
_64  const { session } = useSession();
_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


_36import { 
_36  BrowserVault,
_36  Vault,
_36  VaultType,
_36  DeviceSecurityType,
_36} from '@ionic-enterprise/identity-vault';
_36import { createVault } from './vault-factory';
_36import { Session } from '../models/Session';
_36import { setState } from './session-store';
_36
_36const vault: Vault | BrowserVault = createVault();
_36
_36export const initializeVault = async (): Promise<void> => {
_36  try {
_36    await vault.initialize({
_36      key: 'io.ionic.gettingstartedivreact',
_36      type: VaultType.SecureStorage,
_36      deviceSecurityType: DeviceSecurityType.None,
_36    });
_36  } catch (e: unknown) {
_36    await vault.clear();
_36  }
_36};
_36
_36export const storeSession = async (session: Session): Promise<void> => {
_36  await vault.setValue('session', session);
_36  setState({ session });
_36};
_36
_36export const restoreSession = async (): Promise<void> => {
_36  let session: Session | null = null;
_36  if (!(await vault.isEmpty())) {
_36    session = await vault.getValue<Session>('session');
_36  }
_36  setState({ session });
_36};

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


_38import { 
_38  BrowserVault,
_38  Vault,
_38  VaultType,
_38  DeviceSecurityType,
_38} from '@ionic-enterprise/identity-vault';
_38import { createVault } from './vault-factory';
_38import { Session } from '../models/Session';
_38import { setState } from './session-store';
_38
_38const vault: Vault | BrowserVault = createVault();
_38
_38export const initializeVault = async (): Promise<void> => {
_38  try {
_38    await vault.initialize({
_38      key: 'io.ionic.gettingstartedivreact',
_38      type: VaultType.SecureStorage,
_38      deviceSecurityType: DeviceSecurityType.None,
_38    });
_38  } catch (e: unknown) {
_38    await vault.clear();
_38  }
_38
_38  await restoreSession();
_38};
_38
_38export const storeSession = async (session: Session): Promise<void> => {
_38  await vault.setValue('session', session);
_38  setState({ session });
_38};
_38
_38export const restoreSession = async (): Promise<void> => {
_38  let session: Session | null = null;
_38  if (!(await vault.isEmpty())) {
_38    session = await vault.getValue<Session>('session');
_38  }
_38  setState({ session });
_38};

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

src/util/session-vault.ts


_36import { 
_36  BrowserVault,
_36  Vault,
_36  VaultType,
_36  DeviceSecurityType,
_36} from '@ionic-enterprise/identity-vault';
_36import { createVault } from './vault-factory';
_36import { Session } from '../models/Session';
_36import { setState } from './session-store';
_36
_36const vault: Vault | BrowserVault = createVault();
_36
_36export const initializeVault = async (): Promise<void> => {
_36  try {
_36    await vault.initialize({
_36      key: 'io.ionic.gettingstartedivreact',
_36      type: VaultType.SecureStorage,
_36      deviceSecurityType: DeviceSecurityType.None,
_36    });
_36  } catch (e: unknown) {
_36    await vault.clear();
_36  }
_36};
_36
_36export const storeSession = async (session: Session): Promise<void> => {
_36  await vault.setValue('session', session);
_36  setState({ session });
_36};
_36
_36export const restoreSession = async (): Promise<void> => {
_36  let session: Session | null = null;
_36  if (!(await vault.isEmpty())) {
_36    session = await vault.getValue<Session>('session');
_36  }
_36  setState({ session });
_36};

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


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

Add a "Clear" button to the Tab1 page.

src/pages/Tab1.tsx


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

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

Update 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


_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';
_43import { setState } from './session-store';
_43
_43const vault: Vault | BrowserVault = createVault();
_43
_43export const initializeVault = async (): Promise<void> => {
_43  try {
_43    await vault.initialize({
_43      key: 'io.ionic.gettingstartedivreact',
_43      type: VaultType.SecureStorage,
_43      deviceSecurityType: DeviceSecurityType.None,
_43    });
_43  } catch (e: unknown) {
_43    await vault.clear();
_43  }
_43
_43  await restoreSession();
_43};
_43
_43export const storeSession = async (session: Session): Promise<void> => {
_43  await vault.setValue('session', session);
_43  setState({ session });
_43};
_43
_43export const restoreSession = async (): Promise<void> => {
_43  let session: Session | null = null;
_43  if (!(await vault.isEmpty())) {
_43    session = await vault.getValue<Session>('session');
_43  }
_43  setState({ session });
_43};
_43
_43export const clearSession = async (): Promise<void> => {
_43  await vault.clear();
_43  setState({ session: null });
_43}

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

src/util/session-vault.ts


_48import { 
_48  BrowserVault,
_48  Vault,
_48  VaultType,
_48  DeviceSecurityType,
_48} from '@ionic-enterprise/identity-vault';
_48import { createVault } from './vault-factory';
_48import { Session } from '../models/Session';
_48import { setState } from './session-store';
_48
_48export type UnlockMode =
_48  | 'BiometricsWithPasscode'
_48  | 'InMemory'
_48  | 'SecureStorage';
_48
_48const vault: Vault | BrowserVault = createVault();
_48
_48export const initializeVault = async (): Promise<void> => {
_48  try {
_48    await vault.initialize({
_48      key: 'io.ionic.gettingstartedivreact',
_48      type: VaultType.SecureStorage,
_48      deviceSecurityType: DeviceSecurityType.None,
_48    });
_48  } catch (e: unknown) {
_48    await vault.clear();
_48  }
_48
_48  await restoreSession();
_48};
_48
_48export const storeSession = async (session: Session): Promise<void> => {
_48  await vault.setValue('session', session);
_48  setState({ session });
_48};
_48
_48export const restoreSession = async (): Promise<void> => {
_48  let session: Session | null = null;
_48  if (!(await vault.isEmpty())) {
_48    session = await vault.getValue<Session>('session');
_48  }
_48  setState({ session });
_48};
_48
_48export const clearSession = async (): Promise<void> => {
_48  await vault.clear();
_48  setState({ session: null });
_48}

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

src/util/session-vault.ts


_52import { 
_52  BrowserVault,
_52  Vault,
_52  VaultType,
_52  DeviceSecurityType,
_52} from '@ionic-enterprise/identity-vault';
_52import { createVault } from './vault-factory';
_52import { Session } from '../models/Session';
_52import { setState } from './session-store';
_52
_52export type UnlockMode =
_52  | 'BiometricsWithPasscode'
_52  | 'InMemory'
_52  | 'SecureStorage';
_52
_52const vault: Vault | BrowserVault = createVault();
_52
_52export const initializeVault = async (): Promise<void> => {
_52  try {
_52    await vault.initialize({
_52      key: 'io.ionic.gettingstartedivreact',
_52      type: VaultType.SecureStorage,
_52      deviceSecurityType: DeviceSecurityType.None,
_52    });
_52  } catch (e: unknown) {
_52    await vault.clear();
_52  }
_52
_52  await restoreSession();
_52};
_52
_52export const storeSession = async (session: Session): Promise<void> => {
_52  await vault.setValue('session', session);
_52  setState({ session });
_52};
_52
_52export const restoreSession = async (): Promise<void> => {
_52  let session: Session | null = null;
_52  if (!(await vault.isEmpty())) {
_52    session = await vault.getValue<Session>('session');
_52  }
_52  setState({ session });
_52};
_52
_52export const clearSession = async (): Promise<void> => {
_52  await vault.clear();
_52  setState({ session: null });
_52};
_52
_52export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_52  
_52};

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

src/util/session-vault.ts


_54import { 
_54  BrowserVault,
_54  Vault,
_54  VaultType,
_54  DeviceSecurityType,
_54} from '@ionic-enterprise/identity-vault';
_54import { createVault } from './vault-factory';
_54import { Session } from '../models/Session';
_54import { setState } from './session-store';
_54
_54export type UnlockMode =
_54  | 'BiometricsWithPasscode'
_54  | 'InMemory'
_54  | 'SecureStorage';
_54
_54const vault: Vault | BrowserVault = createVault();
_54
_54export const initializeVault = async (): Promise<void> => {
_54  try {
_54    await vault.initialize({
_54      key: 'io.ionic.gettingstartedivreact',
_54      type: VaultType.SecureStorage,
_54      deviceSecurityType: DeviceSecurityType.None,
_54    });
_54  } catch (e: unknown) {
_54    await vault.clear();
_54  }
_54
_54  await restoreSession();
_54};
_54
_54export const storeSession = async (session: Session): Promise<void> => {
_54  await vault.setValue('session', session);
_54  setState({ session });
_54};
_54
_54export const restoreSession = async (): Promise<void> => {
_54  let session: Session | null = null;
_54  if (!(await vault.isEmpty())) {
_54    session = await vault.getValue<Session>('session');
_54  }
_54  setState({ session });
_54};
_54
_54export const clearSession = async (): Promise<void> => {
_54  await vault.clear();
_54  setState({ session: null });
_54};
_54
_54export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_54  const newConfig = { ...(vault.config as IdentityVaultConfig) };
_54
_54  await vault.updateConfig(newConfig);
_54};

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


_69import { 
_69  BrowserVault,
_69  Vault,
_69  VaultType,
_69  DeviceSecurityType,
_69} from '@ionic-enterprise/identity-vault';
_69import { createVault } from './vault-factory';
_69import { Session } from '../models/Session';
_69import { setState } from './session-store';
_69
_69export type UnlockMode =
_69  | 'BiometricsWithPasscode'
_69  | 'InMemory'
_69  | 'SecureStorage';
_69
_69const vault: Vault | BrowserVault = createVault();
_69
_69export const initializeVault = async (): Promise<void> => {
_69  try {
_69    await vault.initialize({
_69      key: 'io.ionic.gettingstartedivreact',
_69      type: VaultType.SecureStorage,
_69      deviceSecurityType: DeviceSecurityType.None,
_69    });
_69  } catch (e: unknown) {
_69    await vault.clear();
_69  }
_69
_69  await restoreSession();
_69};
_69
_69export const storeSession = async (session: Session): Promise<void> => {
_69  await vault.setValue('session', session);
_69  setState({ session });
_69};
_69
_69export const restoreSession = async (): Promise<void> => {
_69  let session: Session | null = null;
_69  if (!(await vault.isEmpty())) {
_69    session = await vault.getValue<Session>('session');
_69  }
_69  setState({ session });
_69};
_69
_69export const clearSession = async (): Promise<void> => {
_69  await vault.clear();
_69  setState({ session: null });
_69};
_69
_69export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_69  const newConfig = { ...(vault.config as IdentityVaultConfig) };
_69
_69  switch (mode) {
_69    case 'BiometricsWithPasscode': {
_69      newConfig.type = VaultType.DeviceSecurity;
_69      break;
_69    }
_69    case 'InMemory': {
_69      newConfig.type = VaultType.InMemory;
_69      break;
_69    }
_69    default: {
_69      newConfig.type = VaultType.SecureStorage;
_69      break;
_69    }
_69  }
_69
_69  await vault.updateConfig(newConfig);
_69};

Update the type based on the specified mode.

src/util/session-vault.ts


_72import { 
_72  BrowserVault,
_72  Vault,
_72  VaultType,
_72  DeviceSecurityType,
_72} from '@ionic-enterprise/identity-vault';
_72import { createVault } from './vault-factory';
_72import { Session } from '../models/Session';
_72import { setState } from './session-store';
_72
_72export type UnlockMode =
_72  | 'BiometricsWithPasscode'
_72  | 'InMemory'
_72  | 'SecureStorage';
_72
_72const vault: Vault | BrowserVault = createVault();
_72
_72export const initializeVault = async (): Promise<void> => {
_72  try {
_72    await vault.initialize({
_72      key: 'io.ionic.gettingstartedivreact',
_72      type: VaultType.SecureStorage,
_72      deviceSecurityType: DeviceSecurityType.None,
_72    });
_72  } catch (e: unknown) {
_72    await vault.clear();
_72  }
_72
_72  await restoreSession();
_72};
_72
_72export const storeSession = async (session: Session): Promise<void> => {
_72  await vault.setValue('session', session);
_72  setState({ session });
_72};
_72
_72export const restoreSession = async (): Promise<void> => {
_72  let session: Session | null = null;
_72  if (!(await vault.isEmpty())) {
_72    session = await vault.getValue<Session>('session');
_72  }
_72  setState({ session });
_72};
_72
_72export const clearSession = async (): Promise<void> => {
_72  await vault.clear();
_72  setState({ session: null });
_72};
_72
_72export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_72  const newConfig = { ...(vault.config as IdentityVaultConfig) };
_72
_72  switch (mode) {
_72    case 'BiometricsWithPasscode': {
_72      newConfig.type = VaultType.DeviceSecurity;
_72      newConfig.deviceSecurityType = DeviceSecurityType.Both;
_72      break;
_72    }
_72    case 'InMemory': {
_72      newConfig.type = VaultType.InMemory;
_72      newConfig.deviceSecurityType = DeviceSecurityType.None;
_72      break;
_72    }
_72    default: {
_72      newConfig.type = VaultType.SecureStorage;
_72      newConfig.deviceSecurityType = DeviceSecurityType.None;
_72      break;
_72    }
_72  }
_72
_72  await vault.updateConfig(newConfig);
_72};

Update the deviceSecurityType based on the value of the type.

src/util/session-vault.ts


_73import { 
_73  BrowserVault,
_73  Vault,
_73  VaultType,
_73  DeviceSecurityType,
_73} from '@ionic-enterprise/identity-vault';
_73import { createVault } from './vault-factory';
_73import { Session } from '../models/Session';
_73import { setState } from './session-store';
_73
_73export type UnlockMode =
_73  | 'BiometricsWithPasscode'
_73  | 'InMemory'
_73  | 'SecureStorage';
_73
_73const vault: Vault | BrowserVault = createVault();
_73
_73export const initializeVault = async (): Promise<void> => {
_73  try {
_73    await vault.initialize({
_73      key: 'io.ionic.gettingstartedivreact',
_73      type: VaultType.SecureStorage,
_73      deviceSecurityType: DeviceSecurityType.None,
_73    });
_73  } catch (e: unknown) {
_73    await vault.clear();
_73    await setUnlockMode('SecureStorage');
_73  }
_73
_73  await restoreSession();
_73};
_73
_73export const storeSession = async (session: Session): Promise<void> => {
_73  await vault.setValue('session', session);
_73  setState({ session });
_73};
_73
_73export const restoreSession = async (): Promise<void> => {
_73  let session: Session | null = null;
_73  if (!(await vault.isEmpty())) {
_73    session = await vault.getValue<Session>('session');
_73  }
_73  setState({ session });
_73};
_73
_73export const clearSession = async (): Promise<void> => {
_73  await vault.clear();
_73  setState({ session: null });
_73};
_73
_73export const updateUnlockMode = async (mode: UnlockMode): Promise<void> => {
_73  const newConfig = { ...(vault.config as IdentityVaultConfig) };
_73
_73  switch (mode) {
_73    case 'BiometricsWithPasscode': {
_73      newConfig.type = VaultType.DeviceSecurity;
_73      newConfig.deviceSecurityType = DeviceSecurityType.Both;
_73      break;
_73    }
_73    case 'InMemory': {
_73      newConfig.type = VaultType.InMemory;
_73      newConfig.deviceSecurityType = DeviceSecurityType.None;
_73      break;
_73    }
_73    default: {
_73      newConfig.type = VaultType.SecureStorage;
_73      newConfig.deviceSecurityType = DeviceSecurityType.None;
_73      break;
_73    }
_73  }
_73
_73  await vault.updateConfig(newConfig);
_73};

If the vault fails to initialize reset it to be a SecureStorage vault since it does not rely on the device level security settings. You could also use InMemory if desired.

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.

If the vault fails to initialize reset it to be a SecureStorage vault since it does not rely on the device level security settings. You could also use InMemory if desired.

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';
_43import { setState } from './session-store';
_43
_43const vault: Vault | BrowserVault = createVault();
_43
_43export const initializeVault = async (): Promise<void> => {
_43  try {
_43    await vault.initialize({
_43      key: 'io.ionic.gettingstartedivreact',
_43      type: VaultType.SecureStorage,
_43      deviceSecurityType: DeviceSecurityType.None,
_43    });
_43  } catch (e: unknown) {
_43    await vault.clear();
_43  }
_43
_43  await restoreSession();
_43};
_43
_43export const storeSession = async (session: Session): Promise<void> => {
_43  await vault.setValue('session', session);
_43  setState({ session });
_43};
_43
_43export const restoreSession = async (): Promise<void> => {
_43  let session: Session | null = null;
_43  if (!(await vault.isEmpty())) {
_43    session = await vault.getValue<Session>('session');
_43  }
_43  setState({ session });
_43};
_43
_43export const clearSession = async (): Promise<void> => {
_43  await vault.clear();
_43  setState({ session: null });
_43}

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


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

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.

Lock and Unlock 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


_78import { 
_78  BrowserVault,
_78  Vault,
_78  VaultType,
_78  DeviceSecurityType,
_78} from '@ionic-enterprise/identity-vault';
_78import { createVault } from './vault-factory';
_78import { Session } from '../models/Session';
_78import { setState } from './session-store';
_78
_78export type UnlockMode =
_78  | 'BiometricsWithPasscode'
_78  | 'InMemory'
_78  | 'SecureStorage';
_78
_78const vault: Vault | BrowserVault = createVault();
_78
_78export const initializeVault = async (): Promise<void> => {
_78  try {
_78export const lockSession = async (): Promise<void> => {

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

src/pages/Tab1.tsx


_121import { 
_121  IonButton,
_121  IonContent, 
_121  IonHeader, 
_121  IonItem, 
_121  IonLabel, 
_121  IonList, 
_121  IonPage, 
_121  IonTitle, 
_121  IonToolbar,
_121} from '@ionic/react';
_121import { useSession } from '../util/session-store';
_121import './Tab1.css';
_121import { 
_121  storeSession, 
_121  clearSession,
_121  updateUnlockMode,
_121  lockSession,
_121} from '../util/session-vault';
_121
_121const Tab1: React.FC = () => {
_121  const { session } = useSession();
_121
_121  const storeClicked = async (): Promise<void> => {
_121    await storeSession({
_121      email: 'test@ionic.io',
_121      firstName: 'Tessa',
_121      lastName: 'Testsmith',
_121      accessToken: '4abf1d79-143c-4b89-b478-19607eb5ce97',
_121      refreshToken: '565111b6-66c3-4527-9238-6ea2cc017126',
_121    });
_121  };
_121
_121  return (
_121    <IonPage>
_121      <IonHeader>
_121        <IonToolbar>
_121          <IonTitle>Tab 1</IonTitle>
_121        </IonToolbar>
_121      </IonHeader>
_121      <IonContent fullscreen>
_121        <IonHeader collapse="condense">
_121          <IonToolbar>
_121            <IonTitle size="large">Tab 1</IonTitle>
_121          </IonToolbar>
_121        </IonHeader>
_121        
_121        <IonList>
_121          <IonItem>
_121              <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 restoreSession() 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


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

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


_83import { 
_83  BrowserVault,
_83  Vault,
_83  VaultType,
_83  DeviceSecurityType,
_83} from '@ionic-enterprise/identity-vault';
_83import { createVault } from './vault-factory';
_83import { Session } from '../models/Session';
_83import { setState } from './session-store';
_83
_83export type UnlockMode =
_83  | 'BiometricsWithPasscode'
_83  | 'InMemory'
_83  | 'SecureStorage';
_83
_83const vault: Vault | BrowserVault = createVault();
_83
_83export const initializeVault = async (): Promise<void> => {
_83  try {
_83      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 restoreSession 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-store`

`session-vault`

Create and Initialize the Vault

Store a Value

Get a Value

Remove the Session from the Vault

Update the Vault Type

Setting the Vault Type

Why the `UnlockMode`?

Setting the `deviceSecurityType` Value

Update the `Tab1` Page

Native Configuration

Lock and Unlock 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-store​

session-vault​

Create and Initialize the Vault​

Store a Value​

Get a Value​

Remove the Session from the Vault​

Update the Vault Type​

Setting the Vault Type​

Why the UnlockMode?​

Setting the deviceSecurityType Value​

Update the Tab1 Page​

Native Configuration​

Lock and Unlock 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-store`

`session-vault`

Create and Initialize the Vault

Store a Value

Get a Value

Remove the Session from the Vault

Update the Vault Type

Setting the Vault Type

Why the `UnlockMode`?

Setting the `deviceSecurityType` Value

Update the `Tab1` Page

Native Configuration

Lock and Unlock 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