Skip to main content
Version: 5.0

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/componentslet 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.