TSQBiometricAuth

Description

TSBiometricAuth is a library to make biometric authentication simple. It embeds Apple's LocalAuthentication framework and notifies authentication result via a Delegate.

Requirements

iOS 9.0

Swift 4.1

RxSwift 4.2

Installation

TSQBiometricAuth is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'TSQBiometricAuth'

Example

To run the example project, clone the repo, and run pod install from the Example directory first. Open ExampleViewController to see the full code needed to implement biometric authentication.

Usage

• Import the library into your project:

  import TSQBiometricAuth

• Instantiate the TSQBioAuthViewController, like so:

  let vc = TSQBioAuth.instantiateTSQBioAuthViewController(...)

• Customize it and choose how you want to "listen" to the authentication state changes.

Customization

Customize the UI and behaviour of TSQBioAuthViewController through its init parameters, below is a list of them:

Param name	Type	Description
displayMessage	String	Message shown to the users while asking for their touchID/faceID.
leftButtonConfiguration	TSQButtonConfiguration	Defines the left button configuration.
rightButtonConfiguration	TSQButtonConfiguration	Defines the right button configuration.
dismissWhenAuthenticationSucceeds	Bool	Defines whether TSQBioAuthViewController should be automatically dismissed when the authentication succeeds. Default: true
dismissWhenUserCancels	Bool	Defines whether TSQBioAuthViewController should be automatically dismissed when the users choose to cancel the authentication proccess (by tapping on the left button). Default: true
logoImage	UIImage	Image presented at the center of the screen
logoImageConfiguration	TSQImageConfiguration	Defines the logoImage configuration.
backgroundImage	UIImage	Background image at ViewController. Default: nil
backgroundImageConfiguration	TSQImageConfiguration	Defines the backgroundImage configuration. Default: nil
backgroundColor	UIColor	The ViewController's background color. Default: nil

TSQButtonConfiguration

Simple wrapper to configure a UIButton.

Param name	Type	Default value
cornerRadius	CGFloat	5
borderColor	UIColor	.white
borderWidth	CGFloat	1
backgroundColor	UIColor	.white
height	CGFloat	40
text	String	""
textColor	UIColor	.black
font	UIFont	.systemFont(ofSize: 14.0)

TSQImageConfiguration

Simple wrapper to configure a UIImage.

Param name	Type	Default value
height	CGFloat	80
width	CGFloat	80
xOffset	CGFloat	0
yOffset	CGFloat	0
contentMode	UIViewContentMode	.scaleToFill

Listening to autentication state changes

There are 2 ways to do so, through the delegate or Rx subscription.

WARNING Due to Apple's LAErrors classification, when the user chooses to cancel the authentication it will return an error with code LAError.Code.userCancel. However, TSQBioAuthViewController doesn't dismiss itself when this occurs, since the apps that have biometric authentication do not dismiss the View Controller responsible for the authentication flow when this happens. IF you choose to handle the errors by yourself, beware of this specific scenario.

Delegate

After instantiating TSQBioAuthViewController, set its delegate and make sure the current ViewController conforms to TSQBioAuthenticationDelegate. Like so:

class CurrentViewController: UIViewController {
    ...
    private func setupBiometricAuthentication() {
        let bioAuthVC = TSQBioAuth.instantiateTSQBioAuthViewController(...)
        bioAuthVC.delegate = self
        ...
    }
}

extension CurrentViewController: TSQBioAuthenticationDelegate {
    func authenticationFailed(withErrorCode errorCode: Int) {
        switch errorCode {
        case LAError.Code.userCancel.rawValue:
            print("User cancelled")
        default:
            print("Authentication Failed with error: \(errorCode)")
        }
    }
    
    func authenticationSucceeded() {
        print("Authentication Succeeded")
    }
    
    func authenticationDisabledByUserChoice() {
        print("Authentication Disabled by User Choice")
    }
}

Rx Subscription

After instantiating TSQBioAuthViewController, subscribe to authenticationState and react to changes in the state:

class CurrentViewController: UIViewController {
    ...
    private let disposeBag = DisposeBag()
    private func setupBiometricAuthentication() {
        let bioAuthVC = TSQBioAuth.instantiateTSQBioAuthViewController(...)
        bioAuthVC.authenticationState.subscribe(onNext: { (state) in
            switch state {
            case .success:
                print("Authentication Succeeded")
            case .error(code: let errorCode):
                switch errorCode {
                case LAError.Code.userCancel.rawValue:
                    print("User cancelled")
                default:
                    print("Authentication Failed with error: \(errorCode)")
                }
            case .disabledByUserChoice:
                print("Authentication Disabled by User Choice")
            }
        }).disposed(by: self.disposeBag)
        ...
    }
}

Error Handling

Since TSQBioAuthViewController already handles the errors involved in authentication, there is no obligation to implement authenticationFailed(withErrorCode errorCode: Int) (delegate) or include the case .error(code: let errorCode): (Rx subscription).

If you want to handle the errors by yourself, please refer to LAErrors.

Authors

Kévin Cardoso de Sá, kevin@townsq.com.br

License

TSQBiometricAuth is available under the MIT license. See the LICENSE file for more info.