Identity Vault

Ionic Identity Vault is an all-in-one frontend identity management system that combines 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).

Without Ionic 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. Learn more.

Installation#

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

Capacitor
Cordova

npm install @ionic-enterprise/identity-vault
npx cap sync

Update the native project config files:

// iOS - Info.plist
<key>NSFaceIDUsageDescription</key>
<string>Use Face ID to authenticate yourself and login</string>

// Android - No additional changes needed

Reference Apps#

The Identity Vault reference apps offer a complete login/logout experience that includes biometrics (Face ID with passcode as a fallback), secure token storage, background data hiding, and session timeouts. Two variants of the reference apps are available. The first variant demonstrates using Identity Vault to integrate with an existing generic authentication workflow. The second variant demonstrates using Identity Vault in conjuction with Auth Connect to provide a fully secured OAuth/OpenID Connect authentication workflow.

Configuring the Vault#

The IonicIdentityVaultUser class takes a generic session type which represents the type of the session you'll store in the vault. You can use the DefaultSession or extend the class to create a custom session. In the constructor of your Identity service, the vault is configured by providing options to the super() call:

interface MyCustomSession extends DefaultSession {
  // username & token are inherited
  email: string;
  age: number;
  nicknames: string[];
}

export class IdentityService extends IonicIdentityVaultUser<MyCustomSession> {

constructor(private http: HttpClient, private router: Router, platform: Platform) {
  super(platform, {
    authMode: AuthMode.BiometricAndPasscode, // Use biometrics auth with passcode fallback
    restoreSessionOnReady: false, // whether or not to immediately attempt to restore the session when the vault is ready
    unlockOnReady: false, // set true to auto prompt the user to unlock when vault is ready
    unlockOnAccess: true, // set to true to auto prompt the user to unlock on first read access
    lockAfter: 5000, // lock after 5 seconds in the background
    hideScreenOnBackground: true // when in app launcher mode hide the current screen and display the splashscreen
  });

  onVaultUnlocked(config: VaultConfig) {
    //Route to my home page
  }

  onVaultLocked() {
    //Route to my login page
  }

  async onPasscodeRequest(isPasscodeSetRequest: boolean) {
    // Display a custom Passcode prompt and return the passcode as a string
    // or return undefined to use the build in native prompts. isPasscodeSetRequest
    // is true when attempting to set a new passcode on the vault, you can use
    // it to do something like prompt the user twice for the pin.
  }

}

Automatically adding your token to requests#

If you'd like to automatically add your authorization token from your identity service to every request, you can see a simple example at in our demo repo.