How to implement a custom passcode workflow

A Vault is configured to use a custom passcode as its locking mechanism when its type configuration property is set to VaultType.CustomPasscode. In this configuration, developers are responsible for implementing a user interface to prompt users to set, then enter, a custom passcode to lock and unlock the Vault.

This document will take you through the tasks required to leverage Ionic Framework's IonModal component to facilitate a custom passcode workflow.

Use the guide to help you adapt your custom passcode user interface for an existing project using Identity Vault.

Prerequisites

You will need an existing project that already creates an instance of a Vault. Should you not have one handy, we recommend starting with the end result of the "Getting Started" tutorial in the framework of your choice: Angular, React, or Vue.

The Vault should be configured to use a custom passcode as its locking mechanism.

You should also have a component you want to use as the UI for the custom passcode prompt. This guide describes how to plug a component into the IonModal API as part of the workflow, but does not provide such a component itself.

The basic principles

Use the custom passcode Vault configuration options

To set a Vault's locking mechanism to use a custom passcode, the configuration object must contain the following values:

type: VaultType.CustomPasscode,
deviceSecurityType: DeviceSecurityType.None,

The deviceSecurityType property may be omitted from the Vault's configuration object; it defaults to None.

Handle the onPasscodeRequested() Vault event

In this configuration a Vault will emit the onPasscodeRequested() event when:

• a passcode must be established in order to lock data within the Vault
• the Vault is in the process of unlocking and requires the correct passcode

Use this event to prompt users to supply or provide a custom passcode. The isPasscodeSetRequest parameter allows you to provide different experiences when a passcode must be established vs. when a passcode is requested to unlock the Vault.

Supply the passcode with the setCustomPasscode() method

To initially set a passcode, or provide one to unlock the Vault with, call the Vault's setCustomPasscode() method. Custom passcodes must be passed to the Vault as a string.

This method should be called before the onPasscodeRequested() handler resolves.

Refer to the Vault class's reference document for additional information on the methods above.

Angular

To implement the IonModal driven custom passcode workflow, use ModalController exported by @ionic/angular:

import { ModalController } from '@ionic/angular';

...snip...

private vault = new Vault( ...snip... );

private async onPasscodeRequest(isPasscodeSetRequest: boolean) {
  const dlg = await this.modalController.create({
    backdropDismiss: false,
    component: MyCustomPasscodeDialog,
    componentProps: {
      isPasscodeSetRequest
    },
  });
  dlg.present();
  const { data } = await dlg.onDidDismiss();
  this.vault.setCustomPasscode(data || '');
}

A reference application that implements the same workflow can be found here.

React

To implement the IonModal driven custom passcode workflow, use useIonModal exported by @ionic/react:

import { useIonModal } from '@ionic/react';

...snip...

// Important!
// The line below must reside _outside_ of any React hooks/components
let handlePasscodeRequest: (data: any) => void = () => {};

// The remainder of this code should reside in a React hook/component
...snip...
const [isSetPasscodeMode, setIsSetPasscodeMode]
  = useState<boolean>(false);

const [present, dismiss] = useIonModal(MyCustomPasscodeDialog, {
  isSetPasscodeMode,
  onDismiss: (data: any) => handlePasscodeRequest(data),
});

vault.onPasscodeRequested(async (isSetPasscodeMode) => {
  return new Promise((resolve) => {
    handlePasscodeRequest = (data: any) => {
      vault.setCustomPasscode(data || '');
      setIsSetPasscodeMode(false);
      setShowModal(false);
      resolve();
    };
    setIsSetPasscodeMode(isSetPasscodeMode);
    setShowModal(true);
  });
});

useEffect(() => {
  showModal ? present() : dismiss();
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, [showModal]);

A reference application that implements the same workflow can be found here.

Vue

To implement the IonModal driven custom passcode workflow, use modalController exported by @ionic/vue:

import { modalController } from '@ionic/vue';

...snip...

const vault = new Vault( ...snip... );

vault.onPasscodeRequested(async (isPasscodeSetRequest: boolean) => {
  const dlg = await modalController.create({
    backdropDismiss: false,
    component: MyCustomPasscodeDialog,
    componentProps: {
      isPasscodeSetRequest
    },
  });
  dlg.present();
  const { data } = await dlg.onDidDismiss();
  vault.setCustomPasscode(data || '');
});

A reference application that implements the same workflow can be found here.