Integrate mobile push authenticator

The CyberArk Identity Android SDK provides highly secure and trusted multi-factor authentication (MFA) to your web app using the mobile push authenticator. Use the SDK to integrate the mobile push authenticator into the android mobile app and leverage the CyberArk Identity's mobile push authentication mechanism and deliver push notifications to a user’s pre-registered device using FCM (Firebase Cloud Messaging). Using push notifications, users can immediately allow or deny access to web applications.

📘
Prerequisites

An access token should be generated for the user and it should be used to send the API calls for device enrollment. The access token can be generated using the OIDC authorization code with PKCE grant.

The mobile device has to be enrolled to CyberArk Identity to leverage the QR code authenticator. The Android SDK provides the capability to enroll the device to CyberArk Identity.

Setup your custom FCM server on the CyberArk Identity

How it works?

Integrate the mobile push authenticator into your app

Follow the below steps to integrate the mobile push authenticator into an Android app:

Step 1: Get FCM token from Firebase (FCMTokenUtil.kt)

FirebaseMessaging.getInstance().token
    .addOnCompleteListener(OnCompleteListener { task ->
        if (!task.isSuccessful) {
            Log.w(TAG, "Fetching FCM registration token failed", task.exception)
            return@OnCompleteListener
}

        // Get new FCM registration token
        val token = task.result
        Log.d(TAG, "Recieved token $token")           
    })

Step 2: Upload FCM token to CyberArk server (FCMService.kt)

val sendFCMTokenModel: SendFCMTokenModel? =
    CyberArkAuthProvider.sendFCMToken(setupFCMUrl())
        .start(applicationContext, token, accessTokenData)
                    .start(applicationContext, token, accessTokenData)

Step 3: Configure FCM Service (FCMService.kt)

Parse remote message:

val notificationDataModel: NotificationDataModel =
CyberArkAuthProvider.parseRemoteNotification(remoteMessage.data).start()

Verify application state and show notification:

/**
 * if application is in foreground process the notification in activity
 */
if (AppUtils.isAppOnForeground()) {
    Log.i(TAG, "FCMService() App in foreground")
    val intent = Intent(this, NotificationActivity::class.java)
    intent.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP)
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    intent.putExtra(FCMReceiver.NOTIFICATION_DATA, notificationDataModel)
    startActivity(intent)
} else {
    /**
     * if the application is in the background build and show Notification
     */
    Log.i(TAG, "FCMService() App in background")
    FCMManager(this).sendNotification(notificationDataModel)
}

Step 4: Build Notifications (FCMManager.kt)

val notificationBuilder = NotificationCompat.Builder(context, channelId)
    .setSmallIcon(R.drawable.ic_launcher_identity_foreground)
    .setContentTitle(notificationDataModel.Title)
    .setContentText(notificationDataModel.Message)
    .addAction(denyAction(notificationDataModel))
    .addAction(approveAction(notificationDataModel))
    .setAutoCancel(true)
    .setContentIntent(bodyAction(notificationDataModel))
    .setSound(defaultSoundUri)
    .setPriority(NotificationCompat.PRIORITY_MAX)
    .setDefaults(NotificationCompat.DEFAULT_ALL)
    .setStyle(NotificationCompat.BigTextStyle().bigText(notificationDataModel.Message))
  notificationManager.notify(
    notificationDataModel.CommandUuid.hashCode(),
    notificationBuilder.build()
)

Perform an Approve action:

val approveIntent = Intent(context, FCMReceiver::class.java)
approveIntent.action = FCMReceiver.ACTION_APPROVE
approveIntent.putExtra(FCMReceiver.NOTIFICATION_DATA, notificationDataModel)

Perform a Deny action:

val denyIntent = Intent(context, FCMReceiver::class.java)
denyIntent.action = FCMReceiver.ACTION_DENY
denyIntent.putExtra(FCMReceiver.NOTIFICATION_DATA, notificationDataModel)

Perform a Body action:

val intent = Intent(context, NotificationActivity::class.java)
intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
intent.putExtra(FCMReceiver.NOTIFICATION_DATA, notificationDataModel)

Step 5: Handle the Push Notification MFA challenge (NotificationActivity.kt)

Submit the OTP code and notification payload to the CyberArk server as shown below.

val submitOTPModel = CyberArkAuthProvider.submitOTP(setupFCMUrl(context))
    .start(context, accessTokenData, otpEnrollModel, notificationPayload)