The Android TFA package provides the ability to integrate native Two Factor Authentication flows within your Android application without using the ScreenSets feature.
Current supported TFA providers are:
In order to use Two Factor Authentication for your site please please read:
In order to integrate the Gigya TFA package you will need to download the latest library from our download site and add the file to your app/lib/ folder.
After adding the library, update your application build.gradle file accordingly.
The Android TFA package is not a stand alone library. Please make sure you have have already integrated the Gigya Android SDK v4.x.
Two Factor Authentication interruptions
When using login/register flows, you are able to override two additional callback methods within the GigyaLoginCallback class:
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: GigyaApiRespone - The initial interruption response received by the login/register attempt.
inactiveProviders: List<TFAProviderModel> - A list containing the Two Factor Authentication providers available for registration.
activeProviders: List<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.
- The TFA package contains various Fragment classes which you can use in order to resolve various Two Factor Authentication flows. All of which are implemented in the provided sample application.
All resolver flows will end with redirecting the finalized logged-in/registered account to the original "onSuccess" callback. In addition, at the end of each successful flow an "onResolved" callback will be called in order to give an optional logic check point if any other application tasks are needed to be performed.
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. A complete sample is available in the provided TFAEmailVerificationFragment class.
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. A complete sample is available in the provided TFAPhoneRegistrationFragment class.
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. A complete sample is available in the provided TFAPhoneVerificationFragment class.
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. A complete sample is available in the provided TOTPRegistrationFragment class.
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. A complete sample is available in the provided TOTPVerificationFragment class.
The push TFA feature allows you to secure your login using push notifications to any registered devices.
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 available.
In order to add the push TFA feature to your application you will need a working push notification/messaging service.
Currently we support only Google Firebase.
Add the following dependencies to your build.gradle file:
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 Android application can be found here: https://firebase.google.com/docs/android/setup
It is not possible to add a registered Google project into a running Firebase project (even if you have just opened a new one). If you already have a registered Google project you will need to link it to Firebase.
To do this, first make sure you are logged in with the same account your Android project is registered to and then link it by choosing the project from your registered projects when creating a new Firebase 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.
- Go to your Firebase console. select your project and open project settings as shown:
- Select the "Cloud Messaging" tag and copy your Server key.
- Use the copied Server key and update your CDC console RBA settings.
Adding Gigya's messaging service
- Adding the messaging service
The Android SDK provides a GigyaFirebaseMessagingService class for you. In order to integrate it please add the following to your AndroidManifest.xml.
Our GigyaFirebaseMessaingService extends the provided FIrebaseMessaingService. If your application already uses the FirebaseMessagingService your will you will need to make your class extend the GigyaFirebaseMessaingService.
In order for all flows to remain intact make sure to call the relevant super methods:
- Adding the TFAPushReceiver & the relevant content activity
The push TFA notification contains a content pending intent (setContentIntent) which will trigger an Activity to open in order to handle the notification content. You will have to declare that activity in your AndroidManifest.xml. The Android SDK already provides you with a template PushTFAActivity class which handles the content intent for you and will display the relevant action UI & handle the selection.
In order to use the provided PushTFAActivity class please add the following to your AndroidManifest.xml file:
Additionally, all action-based push notifications will add the relevant buttons to the notification body. In order to allow the SDK to handle these actions please register the following Broadcast Receiver:
Available customization options
The Android SDK provides some customization options for you if you wish to add a your personal touch to the notificaitons or the content activity.
In order to apply customization you will have to extend the GigyaFirebaseMessaingService class with your own custom service, making sure to register your own service in the AndroidManifest.xml file instead of the GigyaFirebaseMessagingService class.
Available customization overrides:
Push TFA Flow
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.
Verification push should look as following:
Select Approve in order to finalize the opt-in process.
You should receive another notification to indicate the flow has been successfully completed.
Once you opt-in to use the Push TFA service your client will login to his account on the website and 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.
Push TFA messages are sent using PendingIntent.FLAG_CANCEL_CURRENT flag. This is done to avoid approving or disapproving push notification data which may contain invalid tokens.
Push TFA authentication with fingerprint encrypted session
Push TFA actions are session dependent. Therefore, when your session in encrypted using a fingerprint, you must authenticate the user in order to complete the notification authentication flow.
The Android TFA library & The Android Biometric libraries are two independent libraries and do not depend on on the other. However, to achieve the right authentication flow please follow these steps:
When using biometric session encryption, your TFA notification will not contain Approve/Deny buttons. Action handing will be done via notification click using an extension of the PushTFAActivity.class.
1 Create an Activity extension class for your TFA action handling
You will need to evaluate the session state when your extension activity starts. If the session is encrypted using the "FINGERPRINT" tag. You will first need to unlock it before displaying the action alert.
Additionally, If the session was previously locked it is recommended to lock it again after approving the push action to avoid irregular behaviours.
Example taken from sample application used to combine the biometric support and the push TFA feature.
2 Create a custom extension class for the GigyaFirebaseMessagingService class
An extension service class is needed in order to define your custom TFA activity.
Don't forget to correctly declare your extension classes in your AndroidManifest.xml.
Example taken from the provided sample application: