Identity Vault

History

In traditional authentication design, the user logs in frequently
The user's backend sessions timed out quickly

Things have changed...

Single-page apps can time out even though the user is active
Mobile apps aren't shared
Mobile operating systems have OS- and hardware-level ways of saving tokens

Mobile OS

Mobile hardware and operating system features let you save and lock a token at the hardware level
The user then uses biometrics, such as fingerprint or face recognition, to unlock and fetch the token

Typical flow

User enters credentials — name and password
Those are sent to backend
If valid, the server generates a long-lived token and returns it to the phone
Your code saves the token using OS native features
The user closes the app, which locks the token in the OS cache
A week later, the user opens the app
Your code tries to fetch the token, thus causing the OS to use biometrics to unlock the token
Subsequent backend calls include the token

"Protect your users with the most secure mobile biometric authentication available"

Identity Vault

In other words, identify vault makes it easy to incorporate those OS-level security features into your app!

Identity Vault

So what does that mean to a programmer?

Identity Vault is a native plugin that interacts with the phone's security APIs

VaultUser

VaultService

YourVaultUser

OS/Chip

VaultConfig

Your code uses the Identify Vault API to save and retrieve authentication tokens

VaultUser

VaultService

YourVaultUser

VaultConfig

OS/Chip

You call VaultUser methods, which in turn call VaultService

VaultUser

VaultService

YourVaultUser

VaultConfig

OS/Chip

VaultUser

VaultService

YourVaultUser

VaultConfig

OS/Chip

You call VaultUser methods, which in turn call VaultService

VaultUser

VaultService

YourVaultUser

VaultConfig

OS/Chip

VaultService knows how to talk to the native device

VaultUser

VaultService

YourVaultUser

VaultConfig

OS/Chip

Your code is free to get the token out of an unlocked vault

But once locked, only the user can open the vault using fingerprint or other biometrics

VaultUser

YourVaultUser

VaultConfig

OS/Chip

VaultService

VaultUser

YourVaultUser

VaultConfig

OS/Chip

VaultService

Authentication lifecycle

login(email,password)

this.saveSession(email,token);

From then on, each client call includes the token

getData()

✔︎

{}

this.saveSession(email,token);

What can happen?

The user can log out
The vault can become locked
The token can time-out on the server

Log out

logout()

this.logout();

login(email,password)

this.saveSession(email,token);

Note that users rarely log out. Normally, a user logs in once, and from then on uses biometrics to unlock the vault.

Vault becomes locked

app is closed
lockAfter:number

If the vault is locked, and you run getToken(), the user is prompted to unlock via biometrics

In other words, only the user can allow your code to get the token!

this.getStoredToken();

Or, the user can simply log in again and get a new token

login(email,password)

this.saveSession(email,token);

Token times out

The vault has a token but it's no longer good on the server

getData()

Unauthorized 401

this.logout();

Summary

Empty

Unlocked

Token

Locked

Token

Bad

Token

API

VaultUser

VaultService

YourVaultUser

OS/Chip

VaultConfig

export declare class IonicIdentityVaultUser {
    platform: {
        ready: () => Promise<any>;
    };
    constructor(platform: {
        ready: () => Promise<any>;
    }, vaultConfig: any);
    ready(): Promise<void>;

    onVaultLocked(): void;
    onSessionRestored(_token: any): void;

    getVault(): Promise<IonicNativeAuthVaultService>;

    saveSession(email: string, token: any): Promise<void>;
    getStoredEmail(): Promise<any>;
    getStoredToken(): Promise<any>;
    hasStoredToken(): Promise<boolean>;

    logout(): Promise<void>;
    lockOut(): Promise<void>;

}

export declare class IonicIdentityVaultUser {
    platform: {
        ready: () => Promise<any>;
    };
    constructor(platform: {
        ready: () => Promise<any>;
    }, vaultConfig: any);
    ready(): Promise<void>;

    onVaultLocked(): void;
    onSessionRestored(_token: any): void;

    getVault(): Promise<IonicNativeAuthVaultService>;

    saveSession(email: string, token: any): Promise<void>;
    getStoredEmail(): Promise<any>;
    getStoredToken(): Promise<any>;
    hasStoredToken(): Promise<boolean>;

    logout(): Promise<void>;
    lockOut(): Promise<void>;

}

export interface IonicNativeAuthVaultConfig {
    lockAfter?: number;
    secureOnBackground?: boolean;
    enableBiometrics?: boolean;
}

export declare class IonicIdentityVaultUser {
    platform: {
        ready: () => Promise<any>;
    };
    constructor(platform: {
        ready: () => Promise<any>;
    }, vaultConfig: any);
    ready(): Promise<void>;

    onVaultLocked(): void;
    onSessionRestored(_token: any): void;

    getVault(): Promise<IonicNativeAuthVaultService>;

    saveSession(email: string, token: any): Promise<void>;
    getStoredEmail(): Promise<any>;
    getStoredToken(): Promise<any>;
    hasStoredToken(): Promise<boolean>;

    logout(): Promise<void>;
    lockOut(): Promise<void>;

}

export declare class IonicIdentityVaultUser {
    platform: {
        ready: () => Promise<any>;
    };
    constructor(platform: {
        ready: () => Promise<any>;
    }, vaultConfig: any);
    ready(): Promise<void>;

    onVaultLocked(): void;
    onSessionRestored(_token: any): void;

    getVault(): Promise<IonicNativeAuthVaultService>;

    saveSession(email: string, token: any): Promise<void>;
    getStoredEmail(): Promise<any>;
    getStoredToken(): Promise<any>;
    hasStoredToken(): Promise<boolean>;

    logout(): Promise<void>;
    lockOut(): Promise<void>;

}

export declare class IonicIdentityVaultUser {
    platform: {
        ready: () => Promise<any>;
    };
    constructor(platform: {
        ready: () => Promise<any>;
    }, vaultConfig: any);
    ready(): Promise<void>;

    onVaultLocked(): void;
    onSessionRestored(_token: any): void;

    getVault(): Promise<IonicNativeAuthVaultService>;

    saveSession(email: string, token: any): Promise<void>;
    getStoredEmail(): Promise<any>;
    getStoredToken(): Promise<any>;
    hasStoredToken(): Promise<boolean>;

    logout(): Promise<void>;
    lockOut(): Promise<void>;

}

export declare class IonicIdentityVaultUser {
    platform: {
        ready: () => Promise<any>;
    };
    constructor(platform: {
        ready: () => Promise<any>;
    }, vaultConfig: any);
    ready(): Promise<void>;

    onVaultLocked(): void;
    onSessionRestored(_token: any): void;

    getVault(): Promise<IonicNativeAuthVaultService>;

    saveSession(email: string, token: any): Promise<void>;
    getStoredEmail(): Promise<any>;
    getStoredToken(): Promise<any>;
    hasStoredToken(): Promise<boolean>;

    logout(): Promise<void>;
    lockOut(): Promise<void>;

}

In case you're curious, here's the VaultService, although you'll probably never need to call these methods directly

export interface IonicNativeAuthVaultService {
    clear(): Promise<void>;
    lock(): Promise<void>;
    isLocked(): Promise<boolean>;
    hasStoredToken(): Promise<boolean>;
    getToken(): Promise<any>;
    getUsername(): Promise<any>;
    storeToken(username: string, token: string): Promise<void>;
}

Ionic Pro Programmer's

Introduction to

Identity Vault

Identity Vault

History

In traditional authentication design, the user logs in frequently

The user's backend sessions timed out quickly

Things have changed...

Single-page apps can time out even though the user is active

Mobile apps aren't shared

Mobile operating systems have OS- and hardware-level ways of saving tokens

Mobile OS

Mobile hardware and operating system features let you save and lock a token at the hardware level

The user then uses biometrics, such as fingerprint or face recognition, to unlock and fetch the token

Typical flow

User enters credentials — name and password

Those are sent to backend

If valid, the server generates a long-lived token and returns it to the phone

Your code saves the token using OS native features

The user closes the app, which locks the token in the OS cache

A week later, the user opens the app

Your code tries to fetch the token, thus causing the OS to use biometrics to unlock the token

Subsequent backend calls include the token

"Protect your users with the most secure mobile biometric authentication available"

Identity Vault

In other words, identify vault makes it easy to incorporate those OS-level security features into your app!

Identity Vault

So what does that mean to a programmer?

Identity Vault is a native plugin that interacts with the phone's security APIs

Your code uses the Identify Vault API to save and retrieve authentication tokens

You call VaultUser methods, which in turn call VaultService

You call VaultUser methods, which in turn call VaultService

VaultService knows how to talk to the native device

Your code is free to get the token out of an unlocked vault

But once locked, only the user can open the vault using fingerprint or other biometrics

Authentication lifecycle

From then on, each client call includes the token

What can happen?

The user can log out

The vault can become locked

The token can time-out on the server

Log out

Note that users rarely log out. Normally, a user logs in once, and from then on uses biometrics to unlock the vault.

Vault becomes locked

app is closed

lockAfter:number

If the vault is locked, and you run getToken(), the user is prompted to unlock via biometrics

In other words, only the user can allow your code to get the token!

Or, the user can simply log in again and get a new token

Token times out

The vault has a token but it's no longer good on the server

Summary

API

In case you're curious, here's the VaultService, although you'll probably never need to call these methods directly

Ionic Pro — Identity Vault

More from Max Rahder

Ionic Pro
Programmer's