Authentication Flow for Android
casan142saas
The Authentication flow takes place when the user performs a transaction that requires authentication. In the 3-D Secure context, the transaction can be an online purchase transaction. In the non-3-D Secure context (or banking context), the transaction can be a user action such as changing the registered mobile number by using the online banking application.
This section covers the following topics:
For information about the APIs mentioned in these topics, see API Reference for Android.
Steps in the Authentication Flow
Summary of Steps in the Authentication Flow
An administrator can enable one of the following types of authentication for an enterprise.
Summary of Steps in the User Authentication Flow
The user sets a user PIN during the Activation flow. This PIN is the basis for user authentication. The following steps summarize the user authentication process during a transaction:
- The app prompts the user to accept or reject the transaction.
- Suppose the user accepts the transaction.
- If biometric authentication is supported by the SDK and is enabled by the user, then the user is prompted user to submit the biometric. Otherwise, the user is prompted to submit the user PIN.Note: User PIN authentication is always enabled by default. The user cannot disable user PIN authentication.
- If the user submits the biometric, then the OS verifies the biometric and uncovers the user PIN.
- The SDK uses the user PIN to unlock the HOTP credential for user authentication and generate an OTP.
- The SDK sends the OTP to the server.
- The server verifies the OTP and then approves the transaction.
Summary of Steps in the Device Authentication Flow
A device PIN is automatically generated during the Activation flow. This PIN is the basis for device authentication. The following steps summarize the device authentication process during a transaction:
- The user is prompted to accept or reject the transaction.
- Suppose the user accepts the transaction.An authentication prompt is not displayed to the user at any point during this process.
- The SDK uses the device PIN to unlock the HOTP credential for device authentication and generate an OTP.
- The SDK sends the OTP to the server.
- The server verifies the OTP and then approves the transaction.
Steps in the User Authentication Flow When Biometric Authentication and Mobile Push Notification Are Enabled
The following steps take place when the user performs a transaction for which biometric authentication is applied. In this sample scenario, the user has enabled biometric authentication and has also enabled push notification on her mobile.
- The user receives push notification on the mobile.
- When the user taps the push notification or opens the app, the transaction details are displayed. If transaction data signing is enabled, then these transaction parameters are kept ready for OTP generation by the SDK.
- The user taps YES to indicate that she wants to proceed with the transaction.
- Because both PIN authentication and biometric authentication are enabled, the user is prompted to select an authentication type.
- In our example, the user selects biometric authentication.
- The app displays the biometric authentication prompt.
- After the user successfully completes biometric authentication, the app displays a success message.

Steps in the User Authentication Flow When Fallback to PIN Authentication Takes Place
The following steps take place when the user fails to clear biometric authentication.
- If the user fails the first biometric authentication attempt, then the SDK displays the biometric authentication prompt again. In addition, the SDK also displays the PIN authentication option.
After the user fails biometric authentication the third time, the app displays the prompt to submit the PIN. The biometric authentication option is no longer available at this point. - The user submits the PIN.
- After the PIN submitted by the user is verified, the app displays a success message.
Steps in the User Authentication Flow When Biometric Authentication Is Not Enabled
The following steps show how PIN authentication is applied if the user has not enabled biometric authentication on her mobile. This is regardless of whether Mobile Push Notification is enabled.
- When the user taps the push notification or opens the app, the transaction details are displayed. If transaction data signing is enabled, then these transaction parameters are kept ready for OTP generation by the SDK.
- The app prompts the user to submit the PIN.
- After the PIN submitted by the user is verified, the app displays a success message.
Steps in the User Authentication Flow When Mobile Push Notification Is Not Enabled
The following steps show how biometric or PIN authentication is applied if the user has disabled push notifications on her mobile:
- The user reaches the authentication stage of a transaction.
- The user logs in to the app and selects the option to get details of all transactions that are awaiting authentication. If transaction data signing is enabled, then these transaction parameters are kept ready for OTP generation by the SDK.
- The SDK fetches the details of the transaction.
- The app prompts the user to accept or reject the transaction.
- In our sample scenario, the user accepts the transaction.
- If biometric authentication is enabled, then the app prompts the user to complete biometric authentication. Otherwise, the app prompts the user to complete PIN authentication.
- After the user successfully completes authentication, the system allows the transaction to proceed.
Steps in the Device Authentication Flow
The following steps show how device authentication is applied. Push notifications may or may not be enabled on the user's mobile.
- The user reaches the authentication stage of a transaction.
- Depending on whether push notifications are enabled or disabled, the user uses the appropriate feature to display details of the transaction. If transaction data signing is enabled, then these transaction parameters are kept ready for OTP generation by the SDK.
- The SDK fetches the details of the transaction.
- The app prompts the user to accept or reject the transaction.
- In our sample scenario, the user accepts the transaction.
- After device authentication is completed, the system allows the transaction to proceed.
Steps in the App Login Flow
The following steps take place during the App Login flow. In this flow, the user is authenticated before she is allowed to log in to the banking app on her mobile.
The App Login flow is an alternative to using the Transaction Authentication flow for authenticating the Login action. This flow can be implemented using the CA Strong Authentication SDK.
- The user opens the login page of the mobile app.
- The mobile app prompts the user to submit the PIN or biometric.
- The user submits the PIN or biometric.
- The PIN or biometric is verified.
- The app allows the user to log in.
Sequence Diagram for the Authentication Flow
Sequence Diagram for the Transaction Authentication Flow When Mobile Push Notification Is Enabled
The following diagram shows the sequence of API calls that take place during the Transaction Authentication flow. This flow is initiated when the user conducts a transaction outside the authenticator app. Push notification is used to inform the user about the transaction that is awaiting authentication.

Sequence Diagram for the Transaction Authentication Flow When Mobile Push Notification Is Not Enabled
The following diagram shows the sequence of API calls that take place during the Transaction Authentication flow. This flow is initiated when the user conducts a transaction outside the authenticator app. Push notification is not enabled on the user's mobile.

Sequence Diagram for the App Login Flow
The following diagram shows the sequence of API calls that take place during the App Login flow.

Authentication Flow Diagram
The following flow diagram shows the sequence of API calls that take place when CA Strong Authentication is applied during the Transaction Authentication flow and App Login flow.
Important!
An enterprise can configure user authentication or device authentication for users. Android - Transaction Flow

Sample Code for the Authentication Flow
Sample Code for the Transaction Authentication Flow When Mobile Push Notification Is Enabled or Not Enabled
If push notification is enabled, then the push notification sent through FCM contains information in the following format. You directly pass this information in a getTransaction API call to the SDK. This is shown later in this section.
{ "sa_transaction_id": "<sa_transaction_id>", "account_id": "<account_id>", "account_type": "<account_type>" }
The following is sample code for the Transaction Authentication flow. This code covers the scenario in which push notification is enabled and also the scenario in which push notification is not enabled.
////Create an object of the AuthenticationHandler class. //Note: Check for more error codes that can be returned by the SDK in this release. AuthenticationHandler handler = new AuthenticationHandler((<YourActivityName>.this); //If the user has not received push notification and has opened or refreshed the app to see all pending transaction, then use the following getTransaction call to the SDK. This call will return one of the pending transactions from the server. //Check whether to get the specific transaction //If the user has received push notification and clicked the notification, then use the following getTransaction call to the SDK. This call will return the transaction for which the user clicked the push notification. The parameters that are passed in this call are available as part of the push notification. TransactionDetailsResponse response = NULL; if (isValidString(sa_transation_id) && isValidString(account_id) && isValidString(account_type)) { //In the following API call, the parameters are the values received from the push notification. response = handler.getTransaction(sa_transation_id, account_id, account_type); } else { // The following API call is made if the user performs a "pull" operation--when push notification is not enabled response = handler.getTransaction(); } //Check whether the response is not null. if (response != null) { //Check whether the status is not null. if (response.getStatus() != null) { if (response.getStatus().equals(M3DSConstants.FAILURE)) { //Check whether CA Strong Authentication has been activated for at least one account if (response.getErrorCode().equals(M3DSConstants.ERROR_NO_ACTIVE_ACCOUNTS)) { //Prompt the user to activate CA Strong Authentication for the account. } //Check whether there are no transactions that require authentication. else if (response.getErrorCode().equals(M3DSConstants.ERROR_NO_TRANSACTION_AVAILABLE)) { //Display a message corresponding to the status variable in the response } //Check whether the user has Internet connectivity. else if (response.getErrorCode().equals(M3DSConstants.ERROR_NETWORK_UNAVAILABLE)) { // Display a message stating that there is no Internet connectivity. } //Check whether the server is not responding. else if (response.getErrorCode().equals(M3DSConstants.ERROR_SERVER_UNREACHABLE)) { // Display an appropriate message. } //Check whether an SDK error was encountered. else if (response.getErrorCode().equals(M3DSConstants.ERRROR_INTERNAL_READWRITE)) { // Display an appropriate message. } //Check whether any other SDK error was encountered. else if (response.getErrorCode().equals(M3DSConstants.ERROR_SDK_INTERNAL)) { // Display an appropriate message. } else { //Display an error message to the user. } } //Check whether there is a transaction that requires authentication. else if (response.getStatus().equals(M3DSConstants.SUCCESS)) { // Display the transaction details to the user. String titleAndMessage = response.getTransactionMessage(); // At this point, titleAndMessage contains the HTML snippet that encapsulates the Push Body Heading Message and Push Body Passage Message. These two messages are part of the Push Notification templates defined by the administrator. // Also, display the Yes and No buttons to enable the user to accept or reject the transaction. // If the user taps the Yes button, then extract the AuthenticationType from the transactionDetails response object ArrayList<AuthenticationType> enabledAuthTypes = response.getAuthenticationTypes(); // Display list of enabledAuthTypes to user, so that user can select an auth type // Based on the user selection, call the corresponding auth type API if (userSelectedAuthType == DEVICE_PIN_AUTH) { // With DEVICE_PIN_AUTH, the user only has to tap the Yes button. No authentication challenge is displayed. AuthenticationResponse authResponse = handler.authenticateUsingConsent(response); } else if (userSelectedAuthType == USER_PIN_AUTH) { // With USER_PIN_AUTH, the user has to tap the Yes button and also complete an authentication challenge is displayed. AuthenticationResponse authResponse = handler.authenticateUsingUserPin(response, userPin); if(authResponse.getStatus().equals(M3DSConstants.FAILURE) && authResponse.getAttemptAgain()){ //Prompt the PIN page again and ask user to enter the PIN }else{ //Complete the transaction } } else { // Create fingerprint authenticator object FingerPrintAuthenticator fingerPrintAuthenticator = new FingerPrintAuthenticator(authenticateTransactionCallbackObject, activityContext, transactionDetailsResponseObject); fingerPrintAuthenticator.authenticate(); //Handle the response in callback methods in the class in which you had implemented AuthenticateTransactionCallback interface } //Display a message based on the value of the status variable of the AuthenticationResponse object } } else { //Display an error message to the user. } } else { // Display an error message to the user. }}
Sample Code for Canceling the Authentication Flow
The following is sample code for canceling authentication. This code is common to both Android Fingerprint Authentication and User PIN scenarios.
//Create an object of the AuthenticationHandler class.AuthenticationHandler handler = new AuthenticationHandler(<YourActivityName>.this);//If the user taps the "No" button to reject a transaction, then cancel transaction.CancelTransactionResponse cancelTransactionResponse = handler.cancelTransaction (response);//If the response is valid, then display a message based on the value of the status variable of the//CancelTransactionResponse object.
Sample Code for the App Login Flow
The following is sample code for the App Login flow:
//Create an object of the AuthenticationHandler class.//Note: Check for more error codes that can be returned by the SDK in this release.AuthenticationHandler handler = new AuthenticationHandler((<YourActivityName>.this);boolean isPinSetup = handler.isPinSetup();if (isPinSetup) {// App collects the PIN from the user.VerifyPinResponse verifyPinResponse = handler.verifyPin(Pin);if (verifyPinResponse.getStatus().equals("SUCCESS")) {String transactionId = verifyPinResponse.getTransactionId();// App passes transactionId to the bank's server.// Based on the response from the bank's server, app allows (or denies) the user to log in.} else {// If there are more PIN attempts left, then app prompts the user to resubmit the PIN. Otherwise, the app denies login.}} else {// App prompts the user to activate CA Strong Authentication for the account.}
Sample Code for the App Redirection Flow
Fetching RequestorAppURL
The following is sample code for fetching RequestorAppURL:
AuthenticationHandler handler = new AuthenticationHandler(TransactionScreen.this); TransactionDetailsResponse transactionDetailsResponse; transactionDetailsResponse = handler.getTransaction() String requestorAppUrl = transactionDetailsResponse.getRequestorAppURL();
Switching Issuer App to Merchant App
The following is sample code to redirect Issuer App to Issuer App:
switchApp.setOnClickListener(new View.OnClickListener() { @Override public void onClick(View view) { String packageName = requestorAppUrl; Intent intent = getPackageManager().getLaunchIntentForPackage(packageName); if (intent == null) { Toast.makeText(LastScreen.this, "App is not present on the device.", +Toast.LENGTH_SHORT).show(); } else { startActivity(intent); } } });