Class to manage application authentication. More...

Description

Application authentication enables a user to set an application password or PIN during setup which is then required to subsequently login to the application. Requiring an application password further protects access to the runtime's Secure Storage and helps control authorized access when the device is off-line. This class provides methods to set, change and submit a password.

Biometrics may optionally be used as a means of authentication in order to improve the user experience. An application password must be created first so that in the case biometrics fails the user can fall back to enter their password. This class provides an easy to use interface to setup and prompt the user for their biometrics. An interface is also provided to confirm if the device supports biometrics that is deemed to be sufficiently secure.

The following diagrams illustrate how an application could utilize these methods.

Setup

Steps to initialize runtime when application is setup for the first time or after the user has forgotten their password.

Sign In may be prompted prior to the user setting an application password, however the IDP token should be provided to the runtime whilst in the REGISTRATION Initialization state.

Login

Steps required for a user to login.

As secure storage is only accessible after the user has entered a valid password, a developer could optionally store a key or tokens to facilitate access to a server without needing to first prompt the user to enter their full login credentials.

Change Password

A user may change their existing password or PIN. See changePassword().

Forgot Password

If the user forgets their application password it is necessary to call SecurityControl.deactivate to deactivate the runtime and perform the setup flow again. Consequentiality any data stored in Secure Storage would need to be repopulated from the server.

Note that for Android API levels below 28 biometric use may need the following user permission set in the manifest

<uses-permission android:name="android.permission.USE_FINGERPRINT"/>

Public Member Functions
boolean	setPassword (String password)
	Call this method to set the application password. More...

void	enterPassword (String password)
	Provide the correct application password to unlock the application. More...

boolean	validatePassword (String password)
	Enter a password for validation. More...

void	changePassword (String oldPassword, String newPassword)
	Call this method to change the password. More...

boolean	isBiometricsAvailable ()
	Determine if biometric authentication is available on the device. More...

boolean	isBiometricsSetup ()
	Determine if biometric authentication is ready to be used in the application. More...

boolean	setupBiometrics ()
	Call to setup biometrics. More...

boolean	setupBiometrics (String title, String message, String cancelButtonText)
	Call to setup biometrics and override default text. More...

boolean	promptBiometrics ()
	Prompt the user to authenticate using biometrics. More...

boolean	promptBiometrics (String title, String message, String cancelButtonText)
	Prompt the user to authenticate using biometrics and override default text. More...

void	deactivateBiometrics ()
	Call this method to disable biometric authentication. More...

boolean	hasBiometryBeenInvalidatedByChange ()
	Call this method to determine if biometry is deactivated due to a profile change. More...

Member Function Documentation

◆ setPassword()

boolean setPassword ( String password )

Call this method to set the application password when the library is in Initialization State 'AUTHENTICATION_SETUP_REQUIRED'. This should be used for initial setting only, subsequent changes should be done via changePassword().

Using a blank or null value for the password will result in a no-op.

Returns: false if the password is already set, true otherwise

◆ enterPassword()

void enterPassword ( String password )

Call this method to provide the correct application password and to unlock the application. This is required when the Initialization State is 'AUTHENTICATION_REQUIRED'.

◆ validatePassword()

boolean validatePassword ( String password )

Call this function to provide the correct application password for validation purposes

The password will be validated against the application password. Should only be called after the application is unlocked

“Using a blank or null value for the password will result in a no-op.”

Returns: true if the password is correct, false if incorrect (or used before the application is unlocked)

◆ changePassword()

void changePassword	(	String	oldPassword,
		String	newPassword
	)

Call this method to change the password previously set. Using a blank or null value for the password will result in a no-op.

◆ isBiometricsAvailable()

boolean isBiometricsAvailable ( )

Determine if biometric authentication is available to use within the application. This comprises of the following checks:

Does the device have one or more biometric sensor.
Has the user enrolled their biometrics, e.g. face or fingerprint scan.

Returns: true if the device supports biometric authentication and the user has enabled it and false otherwise.

◆ isBiometricsSetup()

boolean isBiometricsSetup ( )

Biometric authentication will be setup and ready for use after calling setupBiometrics() and before calling deactivateBiometrics(). This means the secure file system is ready to be unlocked after successfully validating the user's biometrics with `promptBiometrics()`.

There are other events which could prevent use of biometrics after it has been successfully setup. A system event, such as a user changing their biometric profile, e.g. adding or removing an identity or fingerprint, will invalidate the current biometric secured keys. To determine if this is the case, use `hasBiometryBeenInvalidatedByChange()`. In this event, it would be best practice to inform the user that the device fingerprint or face enrolment has changed and to prompt the authorized user for their application password before calling setupBiometrics() again.

Returns: true if the secure file system is ready to be unlocked using promptBiometrics() and false otherwise.

◆ setupBiometrics() [1/2]

boolean setupBiometrics ( )

Must be called before calling promptBiometrics(). Setup will fail if biometrics is not available on the device, see isBiometricsAvailable() or if the runtime is in 'AUTHENTICATION_SETUP_REQUIRED' Initialization state. A password for the secure store must first be created using setPassword().

The following screenshot shows the text and prompt displayed when setting up biometrics.

The strings will be localized in a subsequent beta release. Alternatively use the other variant of this method which includes parameters to customize the strings.

◆ setupBiometrics() [2/2]

boolean setupBiometrics	(	String	title,
		String	message,
		String	cancelButtonText
	)

Use this method instead of setupBiometrics() in order to customize the title, message and buttons shown in the setup biometrics prompt.

Parameters

title	Title displayed in the prompt.
message	Short message displayed below the title.
cancelButtonText	The text used for the button to cancel setup.

◆ promptBiometrics() [1/2]

boolean promptBiometrics ( )

Call this method to prompt the user for biometric authentication such as a fingerprint.

The following screenshot shows an example biometric prompt.

The strings will be localized in a subsequent beta release. Alternatively use the other variant of this method which includes parameters to customize the strings.

◆ promptBiometrics() [2/2]

boolean promptBiometrics	(	String	title,
		String	message,
		String	cancelButtonText
	)

Use this method instead of promptBiometrics() in order to customize the title, message and cancel button shown in the biometrics prompt.