Gigya Job Openings

Swift v1.x TFA Library

Skip to end of metadata
Go to start of metadata

Description

The Gigya Swift TFA package provides the ability to integrate native Two Factor Authentication flows within your Swift application without using the ScreenSets feature.

Current supported TFA providers are: Email, Phone, TOTP & Push.

In order to use Two Factor Authentication for your site please please read:

Risk Based Authentication

 

Integration

In order to integrate the Gigya Swift TFA package you will need to download the latest library from our download site and add the file to your Embedded Binaries section.

The Swift TFA package is not a stand alone library. Please make sure you have have already integrated our Swift SDK.

 

Two Factor Authentication interruptions

When using login/register flows, you are able to override two additional callback methods within the GigyaLoginResult class:

switch result {
case .success(let data):
    // Success
case .failure(let error):
    guard let interruption = error.interruption else { return }
    // Evaluage interruption.
    switch interruption {
    case .pendingTwoFactorRegistration(let response, let inactiveProviders, let factory):
        // The login/register flow was interrupted with error 403102 (Account Pending TFA Registration)
    case .pendingTwoFactorVerification(let response, let activeProviders, let factory):
        // The login/register flow was interrupted with error 403101 (Account Pending TFA Verification)
    default:
        break
    }
}

These callbacks are called interruption callbacks. Their main purpose is to inform the client that a Two Factor Authentication interruption has happened. In addition they provide the user with the relevant data needed to resolve the interruption in the same context they were initiated.

Initial interruption data

response: GigyaResponseModel - The initial interruption response received by the login/register attempt.
inactiveProviders: [TFAProviderModel] - A list containing the Two Factor Authentication providers available for registration.
activeProviders: [TFAProviderModel] - A list containing the registered Two Factor Authentication providers for this account.
resolverFactory: TFAResolverFactory - A provided factory class which allows you to fetch the appropriate resolver class in order to continue the login/register flow.

All resolver flows will end with redirecting the finalized logged in/registered account to the original "success" case.

In addition, at the end of each successful flow a "resolved" case will be called in order to give an optional logic check point if any other application tasks are needed to be performed.

 

Email Verification

Resolving email verification Two Factor Authentication is done using the RegisteredEmailsResolver class.

Email verification requires you to have a valid registered email account.

Code example for email verification flow. Note that this is just a partial representation of the flow and will require additional UI intervention.

let registeredEmailsResolver = resolverFactory.getResolver(for: RegisteredEmailsResolver.self)
registeredEmailsResolver?.getRegisteredEmails(completion: registeredEmailsResult(result:))
  
func registeredEmailsResult(result: TFARegisteredEmailsResult) {
    switch result {
    case .registeredEmails(let emails):
        registeredEmailsResolver?.sendEmailCode(with: selectedEmail, registeredEmailsResult(result:))
    case .emailVerificationCodeSent(let resolver):
        resolver.verifyCode(provider: .email, verificationCode: code, completion: { result in
            switch result {
            case .resolved:
                // Flow completed.
            case .invalidCode:
                // Invalid code inserted. Try again.
            case .failed(let error):
                // handle error.
            }
        })
    case .error(let error):
            // handle error.
        }
    }

 

 

 

Phone Registration

Resolving phone Two Factor Authentication registration is done using the RegisterPhoneResolver class.

Code example for phone registration flow. Note that this is just a partial representation of the flow and will require additional UI intervention.

let registerPhoneResolver = resolverFactory.getResolver(for: RegisterPhoneResolver.self)
registerPhoneResolver.registerPhone(phone: number, completion: registerPhoneResult(result:))
 
func registerPhoneResult(result: TFARegisterPhonesResult) {
    switch result {
    case .verificationCodeSent(let resolver):
        // Verification code was sent to registered phone number. At this point you should update your UI to support verification input.
        // After UI has been updated and the verification code is available, you are able to use:
        resolver.verifyCode(provider: .phone, verificationCode: code, completion: { result in
            switch result {
            case .resolved:
                // Flow completed.
            case .invalidCode:
                // Invalid code inserted. Try again.
            case .failed(let error):
                // handle error.
            }
        })
    case .error(let error):
        // handle error.
    }
}

 

 

 

Phone Verification

Resolving phone Two Factor Authentication verification is done using the RegisteredPhonesResolver class.

Code example for phone verification flow. Note that this is just a partial representation of the flow and will require additional UI intervention.

let registeredPhonesResolver = resolverFactory.getResolver(for: RegisteredPhonesResolver.self)
registeredPhonesResolver.getRegisteredPhones(completion: registeredPhonesResult(result:))
 
func registeredPhonesResult(result: TFARegisteredPhonesResult) {
    switch result {
    case .registeredPhones(let phones):
        // Display list of registered phones to the user so he will be able to choose where to send verification code sms/voice call.
        // After user chooses call:
        registeredPhonesResolver.sendVerificationCode(with: phone, method: .sms /* can be use .sms or .voice */, completion: registeredPhonesResult(result:))
    case .verificationCodeSent(let resolver):
        // Verification code successfully sent.
        // You are now able to verify the code received calling:
        resolver.verifyCode(provider: .phone, verificationCode: code, rememberDevice: false /* set true to remember device */, completion: { result in
            switch result {
            case .resolved:
                // Flow completed.
            case .invalidCode:
                // Invalid code inserted. Try again.
            case .failed(let error):
                // handle error.
            }
        })
    case .error(let error):
        // handle error.
    }
}

 

 

 

TOTP Registration

Resolving TOTP Two Factor Authentication registration is done using the RegisterTotpResolver class.

Code example for TOTP registration flow. Note that this is just a partial representation of the flow and will require additional UI intervention.

let registerTOTPResolver = resolverFactory.getResolver(for: RegisterTotpResolver.self)
registerTOTPResolver.registerTotp(completion: registerTotpResult(result:))
 
func registerTotpResult(result: TFARegisterTotpResult) {
    switch result {
    case .QRCodeAvilabe(let image, let resolver):
        // UIImage object QR code is available. Display for the user to scan.
        // Once the user scans the code and a verification code is available via the authenticator application you are able to call:
        verifyTotpResolver.verifyTOTPCode(verificationCode: code, rememberDevice: false /* set true to save device */, completion: { (result) in
            switch result {
            case .resolved:
                // Flow completed.
            case .invalidCode:
                // Verification code invalid. Display error and try again.
            case .failed(let error):
                // Handle error.
            }
        })
    case .error(let error):
        // Handle error.
    }
}

 

 

 

TOTP Verification

Resolving TOTP Two Factor Authentication verification is done using the VerifyTotpResolver class.

Code example for TOTP verification flow. Note that this is just a partial representation of the flow and will require additional UI intervention.

let verifyTOTPResolver = resolverFactory.getResolver(for: VerifyTotpResolver.self)
  
// At this point the code is already available to the user using his preferred authenticator application.
verifyTotpResolver.verifyTOTPCode(verificationCode: code, rememberDevice: false /* set true to save device */, completion: { (result) in
    switch result {
    case .resolved:
        // Flow completed.
    case .invalidCode:
        // Verification code invalid. Display error and try again.
    case .failed(let error):
        // Handle error.
    }
})

 

 

 

Push TFA

The push TFA feature allows you to secure your login using push notifications to any registered devices. 

RBA - Push Notifications

This feature currently uses all registered mobile devices to verify any login process made from a website for a specific account.

*Mobile login with push TFA is not currently implemented.

 

Messaging service

Using Google Firebase 

An active Firebase account is needed in order to integrate the push TFA service.

Instructions on how to add Firebase into your iOS application can be found here.

Add Firebase to your iOS project

 

Setting up your application to use cloud messaging

Once you have your Firebase up and running, you are able to register your application in the cloud messaging tab of your project settings page.

  1. Go to your Firebase console and select your project and open project settings as shown:



  2. Select the "Cloud Messaging" tag and copy your Server key.



  3. Use the copied Server key and update your site console RBA settings.

 

Adding The Gigya messaging service

  1. Enable remote notifications.
    1. Go to your project target -> Capabilities -> Background Modes -> Remote notifications (Enable if needed).



  2. Allow Firebase to send foreground notifications.
    1. After you called FirebaseApp.configure() add the follow line:

      FirebaseApp.configure()
      // Add this line
      Messaging.messaging().shouldEstablishDirectChannel = true
  3. Add Firebase delegate
    1. The Gigya server requires the push token to be sent to it in order to send push notifications to your client devices. In order to do so, add the following to your AppDelegate.swift:

      // MessagingDelegate implementation as shown in Firebase documentation.
      func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String) {
          print("Firebase registration token: \(fcmToken)")
          let dataDict:[String: String] = ["token": fcmToken]
      
          NotificationCenter.default.post(name: Notification.Name("FCMToken"), object: nil, userInfo: dataDict)
      
          GigyaTfa.shared.updatePushToken(key: fcmToken)
      }
      
      // Foreground notification receive
      func messaging(_ messaging: Messaging, didReceive remoteMessage: MessagingRemoteMessage) {
          GigyaTfa.shared.foregrundNotification(with: remoteMessage.appData)
      }
  4. Handling push notifications.
    1. In order to let the SDK handle incoming TFA push notifications, add the following to you AppDelegate.swift as well.

      func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
          // Enable Gigya's handling of the TFA notification.
          GigyaTfa.shared.recivePush(userInfo: userInfo, completion: completionHandler)
      }
  5. Notification interaction.
    1. Gigya's TFA notifications require action confirmations. Whether it is to approve or deny the opt-in or login process. In order to open the actions alert confirmation you will need to add the following to your AppDelegate.swift.

      @available(iOS 10.0, *)
      extension AppDelegate: UNUserNotificationCenterDelegate {
          func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
              // tap on notification interaction
              GigyaTfa.shared.verifyPushTfa(with: response)
          }
      }

 

The Push TFA Flow

Opt-In process

In order for a client to opt-in to use the push TFA feature you will need to add the option to opt-in after the user have successfully logged in.

GigyaTfa.shared.OptiInPushTfa { (result) in
    switch result {
    case .success:
        // Step one of the opt-in process has been completed.
        // Wait for approval push notification and to complete flow.
    case .failure(let error):
        // Handle error.
    }
}

 

Verification push should look as following:

 

Tap on the push -> Approve in order to finalize the opt-in process. 

You should receive another notification to indicate the flow has been successfully completed.

 

Verification process

Once you are opt-in to use the Push TFA service, once your client will login to his account on the website an approval notification will be sent to all registered devices (which have completed the opt-in process).

The approval push should look as follows:

 

 

Once you choose to Approve your client will be logged into the system.

 

Biometric Authentication

End User & Biometric Authentication

The biometric fingerprint feature is a security encryption on top of an existing session of your app, therefore, calling any biometric operations requires a valid session.

 

The supported end user flow for the biometric authentication feature is:

  • An end user logs in.
  • An end user opts in to biometric authentication.
    • This will require the end user to verify his fingerprint.
  • The app is locked or being cleared from memory.
  • The end user is required to unlock the app in order to restore his session.
    • This will require the end user to verify his fingerprint.
  • The end user opts out of biometric authentication

 

Authentication flow

In order to use biometric authentication, the following must apply:

  • The device has a Passcode.
  • The device has a TouchID/FaceID available.

 

Available authentication methods:

  • Opt-In - Opts-in the existing session to use fingerprint authentication.
  • Opt-Out - Opts-out the existing session from using fingerprint authentication.
  • Lock - Locks the existing session until unlocking it. No authentication based actions can be done while the session is locked.
  • Unlock - Unlocks the session so the user can continue to make authentication based actions.

Example of biometric authentication flow:

/*
Use authentication action
*/
  
gigya.biometric.optIn { (result) in
    switch result {
    case .success:
        // Action success
    case .failure:
        // Action failed
    }
}

 

Prompt and FaceID

In order to use FaceID in a compatible device, you must include following key to your Info.plist file.

NSFaceIDUsageDescription = (String) "Your custom message"

 

Additionally, when you want to set a custom text in Touch ID prompt , you can include the following key:

GigyaTouchIDMessage = (String) "Your custom message" (default = "Please authenticate to proceed”).

 

Additional Information

Risk Based Authentication

 

 

 

 

 

  • No labels