Skip to main content
Version: 5.0

Vault Configuration

When your application creates a Vault on a device, the Vault sets an initial configuration. A Vault’s configuration can change during the lifetime of its use; for example, you may programmatically change a Vault’s type based on the biometric capabilities of a user’s device.

Changes made to a Vault’s configuration persist between sessions, and an existing Vault will not revert to the configuration set in the constructor.

How does the Vault constructor work?#

The construction of a Vault object looks something like this:

const vault = new Vault({  key: 'com.company.app.vault',  type: VaultType.DeviceSecurity,  /* Remaining configuration omitted for brevity */});

However, this does not mean that a new Vault is created on a device each time this statement runs. Nor does this mean that the Vault configuration is updated every time this statement runs.

Internally, the Vault constructor - new Vault(config: IdentityVaultConfig) - returns a reference to an existing Vault on the device where the key equals the key value defined. Otherwise, it creates a new Vault on the device with the configuration passed into the constructor.

The pseudocode of this logic looks like so:

// Query the device to see if a Vault already existsconst existingVault = vaults.find(vault => vault.key === config.key);
// Return the Vault if it existsif(existingVault) return existingVault;
// Otherwise, create a new Vault with the provided configurationreturn new Vault(config);

How do Vault configurations persist?#

Vaults exist on a device between app sessions, except in the case of Vaults configured to use VaultType.InMemory. Likewise, the configuration for a Vault persists between app sessions. An existing Vault will retain its current configuration and ignore the configuration passed into the Vault constructor - except for the key value for lookup purposes.

After your application creates a Vault, you can update its configuration by calling the updateConfig() method on the Vault reference object:

await vault.updateConfig({ ...vault.config, key: 'com.company.vault.app', type: VaultType.DeviceSecurity});

Any configuration updates made to a Vault persist until one of the following conditions are met:

  1. The application is uninstalled from the device, removing the Vault.
  2. The Vault is removed by invoking the clear() method on the Vault.
  3. A Vault’s configuration is updated by calling the updateConfig() method on the Vault.

How to configure based on device hardware#

As you develop your application, you’ll likely have to develop a strategy to dynamically configure one or more Vaults depending on the end user’s device’s hardware capabilities.

One strategy would be to create a Vault reference object with the least restrictive hardware measure allowed for your application:

const vault = new Vault({  key: 'com.company.app.vault',  type: VaultType.SecureStorage,  /* Remaining configuration omitted for brevity */});

Then use the Device API to determine the best Vault configuration for the end user:

const vault = new Vault({  key: 'com.company.app.vault',  type: VaultType.SecureStorage,  /* Remaining configuration omitted for brevity */});
const isBiometricsEnabled = await Device.isBiometricsEnabled();
if(isBiometricsEnabled) {  vault.updateConfig({     ...vault.config,     type: VaultType.DeviceSecurity,     deviceSecurityType: DeviceSecurityType.Both   });}

Understanding that the Vault will no longer use its initial configuration once created on the device, you can synchronously initialize a Vault then configure it after asynchronous events, such as your application’s sign-in process or an “opt-in to biometrics” button.