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:
_10type: VaultType.CustomPasscode,_10deviceSecurityType: 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:
_18import { ModalController } from '@ionic/angular';_18_18...snip..._18_18private vault = new Vault( ...snip... );_18_18private async onPasscodeRequest(isPasscodeSetRequest: boolean) {_18 const dlg = await this.modalController.create({_18 backdropDismiss: false,_18 component: MyCustomPasscodeDialog,_18 componentProps: {_18 isPasscodeSetRequest_18 },_18 });_18 dlg.present();_18 const { data } = await dlg.onDidDismiss();_18 this.vault.setCustomPasscode(data || '');_18}
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:
_35import { useIonModal } from '@ionic/react';_35_35...snip..._35_35// Important!_35// The line below must reside _outside_ of any React hooks/components_35let handlePasscodeRequest: (data: any) => void = () => {};_35_35// The remainder of this code should reside in a React hook/component_35...snip..._35const [isSetPasscodeMode, setIsSetPasscodeMode]_35 = useState<boolean>(false);_35_35const [present, dismiss] = useIonModal(MyCustomPasscodeDialog, {_35 isSetPasscodeMode,_35 onDismiss: (data: any) => handlePasscodeRequest(data),_35});_35_35vault.onPasscodeRequested(async (isSetPasscodeMode) => {_35 return new Promise((resolve) => {_35 handlePasscodeRequest = (data: any) => {_35 vault.setCustomPasscode(data || '');_35 setIsSetPasscodeMode(false);_35 setShowModal(false);_35 resolve();_35 };_35 setIsSetPasscodeMode(isSetPasscodeMode);_35 setShowModal(true);_35 });_35});_35_35useEffect(() => {_35 showModal ? present() : dismiss();_35 // eslint-disable-next-line react-hooks/exhaustive-deps_35}, [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:
_18import { modalController } from '@ionic/vue';_18_18...snip..._18_18const vault = new Vault( ...snip... );_18_18vault.onPasscodeRequested(async (isPasscodeSetRequest: boolean) => {_18 const dlg = await modalController.create({_18 backdropDismiss: false,_18 component: MyCustomPasscodeDialog,_18 componentProps: {_18 isPasscodeSetRequest_18 },_18 });_18 dlg.present();_18 const { data } = await dlg.onDidDismiss();_18 vault.setCustomPasscode(data || '');_18});
A reference application that implements the same workflow can be found here.