© 2018, Drifty, Inc. All rights reserved. Reproduction and distribution of this material is prohibited.

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

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>;
}
Made with Slides.com