Skip to content

TSQBiometricAuth is a lib to enable biometric authentication via simple ViewController usage.

License

Notifications You must be signed in to change notification settings

townsquad/TSQBiometricAuth

Repository files navigation

TSQBiometricAuth

Version License Platform

open-cancel open-error-success

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á, [email protected]

License

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