AppAuthentication
@objc
public class AppAuthentication : NSObject
Class to manage application authentication.
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 functions 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.
The following diagrams illustrate how an application could utilize these functions.
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(from:to:)
Forgot Password
If the user forgets their application password it is necessary to call 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.
-
The
AppAuthentication
singleton instance.Declaration
Swift
public static let shared: AppAuthentication
-
Initial setup of a password for secure filesystem
Call this function to set the application password when the library is in
authenticationSetupRequired
.Important
This should be used for initial setting only, subsequent changes should be done via
changePassword(from:to:)
.Declaration
Swift
public func setPassword(_ password: String) -> Bool
Parameters
password
The password to be set.
Return Value
false
if the password is already set,true
otherwise. -
Enter a password for secure filesystem access.
Call this function to provide the correct application password and to unlock the application. This is required when the
authenticationRequired
.The password will be validated against password set in the
setPassword(_:)
orchangePassword(from:to:)
.Declaration
Swift
public func enterPassword(_ password: String)
Parameters
password
The password to be validated
-
Enter a password for validation.
Call this function to provide the correct application password for validation purposes
The password will be validated against password set in the
setPassword(_:)
orchangePassword(from:to:)
. Should only be called after the application is unlockedDeclaration
Swift
public func validatePassword(_ password: String) -> Bool
Parameters
password
The password to be validated
Return Value
true
if the password is correct,false
if incorrect (or used before the application is unlocked) -
Change the password for the secure filesystem access
Call this function to change the password previously set.
Declaration
Swift
public func changePassword(from oldPassword: String, to newPassword: String)
Parameters
oldPassword
The old password you want to change.
newPassword
The new password you want to have.
-
Determine if biometric authentication is available to use within the application. This comprises of the following checks:
- Does the device have a biometric sensor, e.g. Face ID or Touch ID.
- Has the user enrolled their biometrics, e.g. face or fingerprint scan.
Has the user permitted the application to use biometrics.
Declaration
Swift
public func isBiometricsAvailable() -> Bool
Return Value
true
if the device supports biometric authentication and the user has enabled it andfalse
otherwise. -
Determine if biometric authentication is ready to be used in the application.
Biometric authentication will be setup and ready for use after calling
setupBiometrics()
and before callingdisableBiometrics()
. This means the secure file system is ready to be unlocked after successfully validating the users biometrics withpromptBiometrics(_:reply:)
.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, look for the case
invalidated
inBiometricAuthenticationErrorCode
. 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 callingsetupBiometrics()
again.Declaration
Swift
public func isBiometricsSetup() -> Bool
Return Value
true
if the secure file system is ready to be unlocked using promptBiometrics() andfalse
otherwise. -
Must be called before calling promptBiometrics(). Setup will fail if biometrics is not available on the device see
isBiometricsAvailable()
or if the runtime is inauthenticationSetupRequired
. A password for the secure store must first be created usingsetPassword(_:)
.To support devices with Face ID an NSFaceIDUsageDescription must also be added to your applications plist. See Apple developer documentation
Declaration
Swift
public func setupBiometrics() -> Bool
-
Invalidates current biometric secured keys. Afterwards calling
promptBiometrics(_:reply:)
will do nothing.Declaration
Swift
public func disableBiometrics() -> Bool
-
Prompt the user for authentication via their biometrics.
Declaration
Swift
public func promptBiometrics(_ localizedReason: String, reply: @escaping (Bool, Error?) -> Void)
Parameters
localizedReason
The reason for requesting authentication, which displays in the authentication dialog presented to the user.
reply
A closure that is executed after attempting to authenticate the user is finished. This is done on a private queue in an unspecified threading context. You must not call
isBiometricsAvailable()
orcanEvaluatePolicy:error:
in this block, because doing so could lead to deadlock. -
Enumeration for handling errors when using biometric authentication.
See moreDeclaration
Swift
@objc public enum BiometricAuthenticationErrorCode : Int