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 exists
const existingVault = vaults.find(vault => vault.key === config.key);

// Return the Vault if it exists
if(existingVault) return existingVault;

// Otherwise, create a new Vault with the provided configuration
return 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.