The Ionic Enterprise Identity Vault ("the Vault") is a all-in-one frontend identity management system that uses security best practices and the latest in biometric authentication options available on iOS and Android.
The Vault manages secure user identity and session tokens, ensuring sensitive tokens are encrypted at rest, stored only in secure locations on the device, and unlocked only with biometric identity (TouchID/FaceID/fingerprint).
Without Ionic Enterprise Identity Vault, Ionic developers have to resort to combining third party Cordova plugins, often resulting in insecure setups due to the lack of correct implementation of biometric and at-rest encryption strategies.
In the constructor of your
User service, the vault is configured by providing options to the
(See more detailed explanations of the
super() call below.)
By default, the user service contains mock
signup methods. You should modify
those to call your login and signup API endpoints, respectively.
Apps manage user sessions in a variety of ways. We have provided a typical authentication
flow in the provided
demo, which has traditional login forms and the ability for the
user to enable biometric authentication in settings.
In the demo app, the user service is the first point of initialization for the user session. When the service is first loaded by Angular, it will query the vault for an unlocked token. An unlocked token is an in-memory token that indicates an active user session that is not locked out. For example, when using an app like Facebook, you can open and close the app repeatedly but still be logged in, this is considered "unlocked" in Vault terminology.
If the session is restored by the
User service, then
onSessionRestored will be called in your
User service with the restored token, provided it extends
IonicIdentityVaultUser. See the demo example in
Even for unlocked tokens, the vault is using security best practices, so you shouldn't store that token again yourself. The vault stores the token in a secure location so that it is encrypted at rest, only requiring biometric authentication if the vault is locked and the user locked out.
Depending on your configuration, the Vault can become
locked. For example, when using
lockAfter, the vault will be locked after the app is inactive beyond the
lockAfter threshold. When the vault is locked,
User service will have its
onVaultLocked() method called. In this method, you should
clear the session token, and navigate the user back to the login page. See the example in onVaultLocked()
When the vault is locked, the session token is still stored in the vault, but now it is stored such that it requires biometric authentication to access. This is hardware-level security that cannot be bypassed even in jailbroken devices.
Logging a user out removes their session and clears any stored tokens in the Vault. This should be used when the user wants to completely log out from the app, for example to switch to a different user.
User service provides a
logout() method that clears the vault. This will also trigger the lock out event in
onVaultLocked(), so your logic can remain the same.
If you'd like to automatically add your authorization token from your user service to every request, you can follow
along with the simple example at
Identity Vault also supports using an
object to store multiple tokens at once. This requires a few changes to your user service to make it use an
object instead of a string. Please see
demo/src/services/user-multitoken.js for an example.
Please note that this means
user.token becomes an object with the tokens you stored, so any time you use
user.token you'll also want to specify
whick key such as
user.token.mainToken. You may also need to modify
http-interceptor.ts from above to include the right tokens.
When extending a User service with
IonicIdentityVaultUser, this modifies your user
service and provides access to many methods both inside of your User class as well
as other portions of your app. If you haven't already, you should extend
IonicIdentityVaultUser and set up Identity Vault using the
super() call from above.
Here are all of the functions available to you, as well as callbacks and how they work:
services/user.ts in Demo project#
This call should be made inside of your User classes constructor, please see the available options above.
enableBiometrics defaults Biometrics to be turned on automatically when a user is logged in.
lockOnClose requires the user to reauthenticate (with login or biometrics) in order to access
their session token after completely closing the app on their device.
lockAfter specifies how long the app can be idle (in background) before the user is locked
out of the vault and required to re-authenticate. Set to
0 to allow long lived sessions,
appropriate for social network and non-financial apps.
hideScreenOnBackground obscures the app when backgrounded to avoid leaking sensitive information,
such as financial statements or balances. Most non-financial apps should set this to
onVaultLocked() is a callback that will be called whenever the Vault has become
locked (requiring the user to reauthenticate by logging in or using Biometrics). In this callback you should
clear the token from memory, and send the user back to your login page, or perform any other custom logic you'd
onSessionRestored() is a callback that will be called whenever the user has an unlocked token stored in the vault. This will be called when a user launches the app after some period of inactivity and their session is still active and the vault is not locked. This inactivity period can be configured using
Here you should also set the token in memory, and possibly also check to make sure that the token is still valid with your server.
saveSession() can be called to save and secure your token
whenever you get a new one, such as in your
signup functions. This method is made available by extending
getVault returns the Vault object asynchronously that you can then interact with in future calls.
Please see the following vault functions for examples:
vault.clear() removes any stored tokens from the Identity Vault, this should be called on logout for instance.
vault.lock() locks the user out of their current session until they reauthenticate by logging in or with biometrics.
This is effectively a "soft" logout, as the session/token may still be active on the server but the only way for the user to unlock the vault and use the app again is by providing biometric authentication.
pages/settings/settings.ts in Demo project#
Whenever you'd like to use your User Service on another page, you'll have to inject it into that page, making it available to other functions.
ready() is a function that returns when the User object and Identity Vault have loaded and are ready to access the
native functionality of the device. It should be used before attempting to use functions within a constructor or
ionViewDidEnter() for instance.
getBiometricType() returns the type of Biometrics that is available on your users physical device. This can be used
to update the UI to show the type in a settings page, for instance.
isBiometricsEnabled() returns a boolean for whether or not Biometrics is indeed turned on for your user.
setBiometricsEnabled() allows you to change whether or not Biometrics is currently turned on for the user. In this example, we've
enableBiometrics as the
ngModel on a Toggle input:
The Cordova plugin provided can be mocked to enable testing and in-browser development.
We have provided an example mock in
it to your project and then, in your
User service, override
getPlugin() to return the mock: