Authentication Flow for iOS

casan221saas
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 iOS.
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:
  1. The app prompts the user to accept or reject the transaction.
  2. Suppose the user accepts the transaction.
  3. 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.
  4. If the user submits the biometric, then the OS verifies the biometric and uncovers the user PIN.
  5. The SDK uses the user PIN to unlock the HOTP credential for user authentication and generate an OTP.
  6. The SDK sends the OTP to the server.
  7. 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:
  1. The user is prompted to accept or reject the transaction.
  2. Suppose the user accepts the transaction.
    An authentication prompt is not displayed to the user at any point during this process.
  3. The SDK uses the device PIN to unlock the HOTP credential for device authentication and generate an OTP.
  4. The SDK sends the OTP to the server.
  5. 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.
  1. The user receives push notification on the mobile.
  2. 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.
    Authentication_01_Transaction_Details.jpg
  3. The user taps Yes to indicate that she wants to proceed with the transaction.
  4. Because both PIN authentication and biometric authentication are enabled, the user is prompted to select an authentication type.
    Authentication_02_Auth_Types.jpg
  5. In our example, the user selects biometric authentication.
  6. The app displays the biometric authentication prompt.
    Authentication_03_Touch_ID_Prompt.jpg
  7. After the user successfully completes biometric authentication, the app displays a success message.
    Authentication_04_Success_Message.jpg
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:
  1. If the user fails a certain number (specified by the OS) of biometric authentication attempts, then the SDK displays the PIN authentication option in addition to the biometric authentication option.
    Fallback_01_Invalid_Touch_ID.jpg
    If the user fails the maximum number (specified by the OS) of biometric authentication attempts, the app displays the prompt to submit the PIN. The biometric authentication option is no longer available at this point.
  2. When the user selects the PIN option, the app displays the prompt to submit the PIN.
    Fallback_02_Submit_PIN.jpg
  3. The user submits the PIN.
  4. 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 biometric authentication is not enabled:
  1. 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.
    Authentication_01_Transaction_Details.jpg
  2. The app prompts the user to submit the PIN.
    Fallback_02_Submit_PIN.jpg
  3. 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:
  1. The user reaches the authentication stage of a transaction.
  2. 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.
  3. The SDK fetches the details of the transaction.
  4. The app prompts the user to accept or reject the transaction.
  5. In our sample scenario, the user accepts the transaction.
  6. 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.
  7. 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.
  1. The user reaches the authentication stage of a transaction.
  2. 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.
  3. The SDK fetches the details of the transaction.
  4. The app prompts the user to accept or reject the transaction.
  5. In our sample scenario, the user accepts the transaction.
  6. 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.
  1. The user opens the login page of the mobile app.
  2. The mobile app prompts the user to submit the PIN or biometric.
  3. The user submits the PIN or biometric.
  4. The PIN or biometric is verified.
  5. 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.
iOS_Transaction_Authentication_MPN.png
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.
iOS_Transaction_Authentication_Non_MPN.png
Sequence Diagram for the App Login Flow
The following diagram shows the sequence of API calls that take place during the App Login flow.
iOS_Login_Authentication.png
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. For information about these authentication types and the scenarios in which an enterprise would want to apply them, see Integrating the CA Strong Authentication SDK.
iOS - Authentication Flow
iOS - Authentication 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>"
}
Sample Code for Getting Transaction Details from the Server
The following is sample code for getting transaction details from the server and displaying these details in the app:
AuthenticationHandler *authHandler =[[ AuthenticationHandler alloc] init];
//In the following API call, the parameters are the values received from the push notification.
TransactionDetailsResponse *txndetailsObj=[authHandler getTransaction :transactionId :accountId :accountType]; // transactionId, accountId, and accountType are obtained from the push notification
if ([[txndetailsObj Status] isEqualToString:FAILURE]) {
// If CA Strong Authentication has not been activated for any account, then
// app prompts the user to activate CA Strong Authentication for this account.
}
else if([[txndetailsObj Status] isEqualToString:SUCCESS]){
// App displays a message stating that no transaction is available.
}
else{
// App displays an appropriate error message based on the errorCode variable of the returned object.
}
Sample Code for Authenticating the Transaction
The following is sample code for authenticating the transaction.
// Check whether to get the specific transaction TransactionDetailsResponse *txndetailsObj; AuthenticationHandler *m3dsobject=[[AuthenticationHandler alloc] init]; if(saTransactionId == nil || accountId == nil || accountType == nil) { // The following API call is made if the user performs a "pull" operation--when push notification // is not enabled txndetailsObj=[m3dsobject getTransaction]; } else { //In the following API call, the parameters are the values received from the push notification. // 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. txndetailsObj=[m3dsobject getTransaction:saTransactionId AccountId:accountId AccountType:accountType]; } //After user taps Yes button on the app //App gets the available authentication types for this transaction AuthenticationResponse *authenticationResponse=nil; NSMutableArray * authenticationTypes = [txndetailsObj authenticationTypes]; if([authenticationTypes count] > 1) { // App displays the list of authentication types // to user to select from // NOTE : the array contains AuthenticationType enums // int value wrapped in NSNumber object, the int value // should be extracted from NSNumber object // before comparing it with the AuthenticationType enum // e.g. // if([[authTypes objectAtIndex:0] intValue] //(AuthenticationType)BIOMETRIC_AUTH) } else { // Single authentication type is present, // call the respective APIs based on the final authentication //type } if(finalAuthenticationType == (AuthenticationType) DEVICE_PIN_AUTH) { // With DEVICE_PIN_AUTH, the user only has to tap the Yes button. // No authentication challenge is displayed. authenticationResponse = [authHandler authenticateUsingConsent:txndetailsObj]; } else if(finalAuthenticationType == (AuthenticationType) BIOMETRIC_AUTH) { // With BIOMETRIC_AUTH, the user has to tap the Yes button and also complete // the biometric authentication challenge. [authHandler authenticateUsingTouchID:txndetailsObj SuccessHandler:^(AuthenticationResponse * authenticationResponse){ // Verify authenticateResponse.status value if ([authenticationResponse.status isEqualToString: @"SUCCESS"]) { //Show Successful Authentication Message to User. } else { // Show failure message based on the authenticationResponse.errorCode } }FailureHandler:^(AuthenticationResponse * authenticationResponse) { //Show Failure Authentication Message to User. }FallbackHandler:^(void) { // Prompt the User to enter PIN and Authenticate the User // using that PIN. authenticationResponse = [authHandler authenticateUsingUserPin:txndetailsObj:UserPIN]; }CancelHandler:^(void) { // User pressed the Cancel while // authentication, App can take // appropriate action. }]; } else if (finalAuthenticationType == (AuthenticationType) USER_PIN_AUTH) { // With USER_PIN_AUTH, the user has to tap the Yes button and also complete the // PIN authentication challenge. // User PIN authentication is required // Prompt the user for the PIN. // Call the authenticateUsingUserPin API. authenticationResponse = [authHandler authenticateUsingUserPin:txndetailsObj:UserPIN]; }
Sample Code for Canceling the Transaction
The following is sample code for canceling the transaction:
AuthenticationHandler *authHandler=[[AuthenticationHandler alloc] init];
CancelTransactionResponse * cancelTransactionResponse = [
authHandler
cancelTransaction:txndetailsObj];
// App displays a message based on the value of the errorCode variable of cancelTransactionResponse.
...
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 *authHandler =[[ AuthenticationHandler alloc] init];
if([authHandler isPINSetup]) {
// App collects the PIN from the user.
VerifyPINResponse *verifyPinResponse = [authHandler verifyPIN:pin];
// If transaction data signing is enabled, then replace the preceding API call with the following one. propertyDict is a dictionary that has the TXN_SIGNING_KEY key.
// The value of this key must be the transaction data.
// The TXN_SIGNING_KEY is defined in the "Header.h" header file, which should be included so that this key can be used.
// VerifyPINResponse *verifyPinResponse = [authHandler verifyPIN:pin PropertyDict:propertyDict];
if ([[verifyPinResponse status] isEqualToString:@"SUCCESS"]] ) {
NSString* transactionId = [verifyPinResponse transactionId];
// 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.
}