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.

Application Authentication Setup Diagram

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.

Application Authentication Login Diagram

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(_:) or changePassword(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(_:) or changePassword(from:to:). Should only be called after the application is unlocked

    Declaration

    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 and false 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 calling disableBiometrics(). This means the secure file system is ready to be unlocked after successfully validating the users biometrics with promptBiometrics(_: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 in BiometricAuthenticationErrorCode. 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.

    Declaration

    Swift

    public func isBiometricsSetup() -> Bool

    Return Value

    true if the secure file system is ready to be unlocked using promptBiometrics() and false 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 in authenticationSetupRequired. A password for the secure store must first be created using setPassword(_:).

    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() or canEvaluatePolicy:error: in this block, because doing so could lead to deadlock.

  • Enumeration for handling errors when using biometric authentication.

    See more

    Declaration

    Swift

    @objc
    public enum BiometricAuthenticationErrorCode : Int