Ionic Enterprise Identity Vault
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.
Overview
Implementation Video Walkthrough
Configuring the Vault
In the constructor of your User
service, the vault is configured by providing options to the super()
call:
@Injectable()
export class User extends IonicIdentityVaultUser {
constructor(public http: Http, public platform: Platform, public app: App) {
super(platform, {
// Whether to enable biometrics automatically when the user logs in
enableBiometrics: true,
// Lock the app if it is terminated and re-opened
lockOnClose: false,
// Lock the app after N milliseconds of inactivity
lockAfter: 5000,
// Obscure the app when the app is backgrounded (most apps will want
// to set this to false unless sensitive financial data is being displayed)
hideScreenOnBackground: true
})
}
}
(See more detailed explanations of the super()
call below.)
Modify login/signup methods
By default, the user service contains mock login
and signup
methods. You should modify
those to call your login and signup API endpoints, respectively.
User Lifecycle
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.
User service initialization
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 user.ts
: onSessionRestored()
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.
Lock 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,
the 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.
Log out
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.
The 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.
Automatically adding your token to requests
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 demo/src/services/http-interceptor.ts
.
Working with multiple authentication tokens
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.
Function & Callback Documentation
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:
Examples from services/user.ts
in Demo project
super(platform, options)
This call should be made inside of your User classes constructor, please see the available options above.
@Injectable()
export class User extends IonicIdentityVaultUser {
constructor(public http: Http, public platform: Platform, public app: App) {
super(platform, {
// Whether to enable biometrics automatically when the user logs in
enableBiometrics: true,
// Lock the app if it is terminated and re-opened
lockOnClose: false,
// Lock the app after N milliseconds of inactivity
lockAfter: 5000,
// Obscure the app when the app is backgrounded (most apps will want
// to set this to false unless sensitive financial data is being displayed)
hideScreenOnBackground: true
})
}
}
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 false
.
onVaultLocked()
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
like to.
export class User extends IonicIdentityVaultUser {
// ...
onVaultLocked() {
// Clear our in-memory token
this.token = null;
const nav = this.app.getRootNavs()[0];
if (nav) {
nav.setRoot(LoginPage);
}
}
}
onSessionRestored()
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 lockAfter
.
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.
export class User extends IonicIdentityVaultUser {
// ...
onSessionRestored(token: string) {
this.token = token;
}
}
saveSession(username/email, token)
saveSession()
can be called to save and secure your token
whenever you get a new one, such as in your login
or signup
functions. This method is made available by extending IonicIdentityVaultUser
.
export class User extends IonicIdentityVaultUser {
// ...
login(email, password){
// Make a request to your server that returns a token
const fakeToken = 'token';
this.saveSession(email, fakeToken);
}
}
getVault()
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()
vault.clear()
removes any stored tokens from the Identity Vault, this should be called on logout for instance.
export class User extends IonicIdentityVaultUser {
// ...
async logout() {
// Send a request to your server that invalidates the users session / token.
const vault = await this.getVault();
vault.clear();
}
}
vault.lock()
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.
export class User extends IonicIdentityVaultUser {
// ...
async lockout() {
// Send a request to your server that invalidates the users session / token.
const vault = await this.getVault();
vault.lock();
}
}
Examples from pages/settings/settings.ts
in Demo project
Injecting your User into Pages
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.
import { User } from '../../services/user';
@Component({
selector: 'page-settings',
templateUrl: 'settings.html'
})
export class SettingsPage {
constructor(public user: User) {
// this.user is now a thing!
}
}
ready()
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.
export class SettingsPage {
async ionViewDidEnter() {
await this.user.ready();
// Now we can call user functions!
}
}
getBiometricType()
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.
export class SettingsPage {
_biometricType: string = null;
async ionViewDidEnter() {
await this.user.ready();
this._biometricType = this.user.getBiometricType();
}
getBiometricType() {
// An example function that turns the returned biometric type into something
// that looks nice for your UI.
if (!this._biometricType) { return null; }
switch (this._biometricType.toLowerCase()) {
case 'touchid': return 'TouchID';
case 'faceid': return 'FaceID';
case 'fingerprint': return 'Fingerprint';
}
return '';
}
}
isBiometricsEnabled()
isBiometricsEnabled()
returns a boolean for whether or not Biometrics is indeed turned on for your user.
export class SettingsPage {
enableBiometrics: boolean = false;
async ionViewDidEnter() {
await this.user.ready();
this.enableBiometrics = this.user.isBiometricsEnabled();
}
}
setBiometricsEnabled(boolean)
setBiometricsEnabled()
allows you to change whether or not Biometrics is currently turned on for the user. In this example, we've
attached enableBiometrics
as the ngModel
on a Toggle input:
export class SettingsPage {
enableBiometrics: boolean = false;
async ionViewDidEnter() {
await this.user.ready();
this.enableBiometrics = this.user.isBiometricsEnabled();
}
onEnableBiometricsChange() {
this.user.setBiometricsEnabled(enableBiometrics);
}
}
Mocking for Testing
The Cordova plugin provided can be mocked to enable testing and in-browser development.
We have provided an example mock in ~/path/to/enterprise-auth/demo/src/services/auth-mock.ts
, copy
it to your project and then, in your User
service, override getPlugin()
to return the mock:
import { IonicIdentityVaultUser } from 'ionic-enterprise-identity-vault';
import { IonicNativeAuthMock } from './auth-mock';
@Injectable()
class MockUser extends IonicIdentityVaultUser {
// ...
getPlugin() {
return IonicNativeAuthMock;
}
// ...
}