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:
- The application is uninstalled from the device, removing the Vault.
- The Vault is removed by invoking the
clear()
method on the Vault. - 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.