Step 5. Implementing the Push client for Android
PingOne Advanced Identity Cloud PingAM Android
This page guides you through implementing the Push client in your Android application to support Push-based Multi-Factor Authentication (MFA).
It covers dependency setup, Push client initialization, credential management, handling different push notification types, and custom storage options.
Adding core dependencies
To add the core dependencies for Push MFA:
-
In the Project tree view of your Android Studio project, open the
build.gradle.ktsfile. -
In the
dependenciessection, add the following:implementation("com.pingidentity.sdks:mfa:push:2.0.0") // Firebase dependencies for push notifications implementation("com.google.firebase:firebase-messaging:25.0.1")
Initializing the Push Client
To use the Push module, you must initialize the Push client in your application.
You can use the default Push client configuration or provide your own configuration using a DSL-style builder.
Default Push client configuration
To use the default Push client configuration, call the PushClient() method with no additional parameters.
When using the default configuration, you also need to initialize the client by using the initialize() method:
val pushClient = PushClient()
// Initialize the client
pushClient.initialize()
Custom Push client Configuration
To customize the Push client configuration, call the PushClient() method and pass the custom configuration as parameters.
When you provide a custom configuration, the PushClient() method also initializes the client, so you don’t need to call initialize() manually:
// Create with custom configuration using DSL-style builder
val pushClient = PushClient {
enableCredentialCache = true
timeout = 30
// Any other configuration options
}
The properties you can use to customize the Push client configuration are as follows:
- enableCredentialCache
-
Whether to enable in-memory caching of credentials.
By default, this is set to
falsefor security reasons, as an attacker could potentially access cached credentials from memory dumps. - timeout
-
The timeout for network operations, in seconds.
The default value is
15seconds. - storage
-
The storage implementation to use for Push credentials.
If
null, the defaultSQLPushStorageis used.Learn more in Customizing credential storage.
- policyEvaluator
-
The policy evaluator to use for credential policy validation.
If
null, the defaultMfaPolicyEvaluatoris used. - customPushHandlers
-
A map of custom push handlers that the module will use alongside the default handlers.
Learn more in Customizing Push notification handlers.
- notificationCleanupConfig
-
Configuration options for the automatic cleanup of push notifications.
Learn more in Cleaning up pending notifications.
- logger
-
The logger instance used for logging messages.
Defaults to the global logger instance.
Learn more in Logging.
Managing Push credentials
The Push module relies on a set of credentials that you can create, retrieve, update, and delete.
The credentials contain details such as the service and user they relate to, and the cryptographic keys needed to validate push notifications.
Creating Push credentials
The Push module lets the user register their device for Push-based multi-factor authentication (MFA).
The information required to register a device is contained in a specially-encoded URI, which your client application decodes to create the credentials.
This URI is often delivered by QR codes that the client can scan or is provided directly in the callback from the Push Registration node.
Use the addCredentialFromUri() method to create Push credentials and register an MFA device:
-
onSuccess
-
getOrThrow
// Obtain Push URI from journey callback or QR code
val uri = "pushauth://push/issuer:user@example.com?key=ABCDEFGHIJK&c=https://example.com/push"
// Create Push credentials using onSuccess
pushClient.addCredentialFromUri(uri).onSuccess { credential ->
// Handle the successfully created credential
println("Created credential: ${credential.issuer}")
}.onFailure { exception ->
// Handle error
println("Failed to add credential: ${exception.message}")
}
// Obtain Push URI from journey callback or QR code
val uri = "pushauth://push/issuer:user@example.com?key=ABCDEFGHIJK&c=https://example.com/push"
// Create Push credentials using getOrThrow
try {
val credential = pushClient.addCredentialFromUri(uri).getOrThrow()
// Use credential
} catch (e: Exception) {
// Handle exception
}
Getting Push credentials
You can get a list of all registered Push credentials or get an individual credential by passing its ID as a parameter.
-
All Push credentials
-
Specific Push credential
pushClient.getCredentials().onSuccess { credentials ->
if (credentials.isEmpty()) {
showMessage("No credentials found")
} else {
displayCredentials(credentials)
}
}
pushClient.getCredential(credentialId).onSuccess { credential ->
if (credential != null) {
// Credential found, use it
displayCredential(credential)
} else {
// Credential not found
showMessage("Credential not found")
}
}
Updating Push credentials
You can update the properties of a stored credential with new values by using the saveCredential() method. Pass the updated credential object into the method as a parameter:
// Change display properties
credential.displayAccountName = "Babs Jensen"
credential.displayIssuer = "Example.com Checking Account"
pushClient.saveCredential(credential).onSuccess { updatedCredential ->
// Handle successful update
showMessage("Credential updated")
}.onFailure { exception ->
// Handle failure
showError("Failed to update credential: ${exception.message}")
}
Deleting Push credentials
Use the deleteCredential() method to remove individual credentials from the client device. Pass the credential ID into the method as a parameter:
// Remove a credential by ID
pushClient.deleteCredential(credentialId).onSuccess { isDeleted ->
if (isDeleted) {
showMessage("Credential deleted")
} else {
showMessage("Credential not found")
}
}.onFailure { exception ->
showError("Failed to delete credential: ${exception.message}")
}
Updating device tokens
Under certain circumstances, the client operating system issues a new device token that your app needs to use for receiving push notifications.
What can cause the device token for push messages to change?
The device token used to receive push messages can change due to a number of circumstances:
- Uninstalling and reinstalling the client app
-
If the user uninstalls and then reinstalls the app, the OS regenerates the device token.
This is one of the most common reasons for a token change.
- Clearing app data
-
Clearing the application’s data by using the device settings causes the OS to issue a new device token upon next launch of the app.
- Revoking and regranting Push permission
-
The OS might issue a new device token if a user revokes and then re-enables push notifications.
- Push services expiring or invalidating tokens
-
The push services themselves, such as the Apple Push Notification service (APNs) or Google’s Firebase Cloud Messaging (FCM) service might invalidate device tokens for various reasons.
The OS issues a new device token upon next launch of the app if the push service invalidates the existing tokens.
- Updating the operating system
-
Occasionally, OS updates, especially major versions, might result in the push notification service issuing a new token.
Updating the OS can also clear app data, which would also mean the app requires a new device token on next launch.
- Updating or migrating apps
-
If you change the package or bundle IDs of your client app that uses push notification, or alter the signing keys, the OS might invalidate existing device tokens and issue a new one.
Similarly, if the user restores the app from backup, or migrates the app to a different device, the OS might issue a new device token, even if restoring the app to the same physical device.
The Push module provides methods for updating the device token associated with accounts it has registered to receive Push notifications. These methods also contact the server that registered the device to update it’s copy of the device token.
Failing to update the device token on both the client and the server will prevent push messages from arriving, which will cause authentication to fail.
|
Updating existing accounts with a new device token is only supported by the following server:
|
// Update the device token when it changes
val deviceToken = firebaseMessaging.getToken().await()
pushClient.setDeviceToken(deviceToken)
// Update the device token for a specific credential
pushClient.setDeviceToken(deviceToken, credentialId)
Responding to push notifications
When your client app receives a push notification from Firebase Cloud Messaging, you need to process it using the processNotification() method:
// When a push notification is received from Firebase
val messageData = remoteMessage.data
val notification = pushClient.processNotification(messageData)
// Show notification to user based on type
if (notification != null) {
when (notification.pushType) {
PushType.DEFAULT -> showDefaultNotification(notification)
PushType.CHALLENGE -> showChallengeNotification(notification)
PushType.BIOMETRIC -> showBiometricPrompt(notification)
}
}
The Push module supports three push notification types depending on your use case and provides methods for handling each one.
Responding to tap to accept notifications
The Tap to accept notification type displays an Accept and a Reject button for the user to choose how to proceed.
This is the default notification type.
Call the approveNotification() method to approve the push notification, or denyNotification to reject it:
// To approve
pushClient.approveNotification(notificationId)
.onSuccess { success ->
if (success) {
// Notify user of successful authentication
} else {
// Handle failure
}
}
.onFailure { error ->
// Handle error
}
// To deny
pushClient.denyNotification(notificationId)
.onSuccess { success ->
if (success) {
// Notify user of successful denial
} else {
// Handle failure
}
}
.onFailure { error ->
// Handle error
}
Responding to display challenge code notifications
The Display Number Challenge notification type displays a number that the user must match on their device, either by entering the value or selecting it from multiple options.
Use the approveChallengeNotification() method to return the response to the server:
// The user sees matching numbers on both login screen and mobile device
// They enter or select the challenge response
val challengeResponse = userSelectedResponse // e.g., "80"
pushClient.approveChallengeNotification(notificationId, challengeResponse)
.onSuccess { success ->
if (success) {
// Notify user of successful authentication
} else {
// Handle failure (possibly wrong challenge response)
}
}
.onFailure { error ->
// Handle error
}
Responding to biometrics to accept notifications
The Use Biometrics to Accept notification type initially displays the same Accept and a Reject buttons for the user to choose how to proceed.
If the user selects to accept the notification, the client device presents its biometric options for the user to authenticate with.
Use the approveBiometricNotification() method to respond to the notification:
// After successful biometric authentication
val authMethod = "fingerprint" // or "face", "iris", etc.
pushClient.approveBiometricNotification(notificationId, authMethod)
.onSuccess { success ->
if (success) {
// Notify user of successful authentication
} else {
// Handle failure
}
}
.onFailure { error ->
// Handle error
}
Managing stored notifications
The Push module stores all notifications, including any that are still pending a response.
Getting pending notifications
You can get a list of pending notifications that have not yet been approved or rejected by using the getPendingNotifications() method:
// Get all pending notifications
pushClient.getPendingNotifications().onSuccess { notifications ->
if (notifications.isNotEmpty()) {
// Display pending notifications to the user
displayPendingNotifications(notifications)
} else {
// No pending notifications
showEmptyState()
}
}.onFailure { error ->
// Handle error
showError("Failed to retrieve notifications: ${error.message}")
}
You can use the getNotification() method to get an individual pending notification by passing its ID as a parameter:
// Get a specific notification by ID
pushClient.getNotification(notificationId).onSuccess { notification ->
if (notification != null) {
// Display the notification details
showNotificationDetails(notification)
} else {
// Notification not found
showNotFoundMessage()
}
}.onFailure { error ->
// Handle error
showError("Failed to retrieve notification: ${error.message}")
}
Cleaning up pending notifications
The Push module provides automatic cleanup of push notifications by using the NotificationCleanupConfig class.
This helps prevent your app from accumulating too many push notification records, therefore improving performance and reducing storage usage.
You can customize notification cleanup by passing parameters to NotificationCleanupConfig:
// Create a client with custom notification cleanup configuration
val pushClient = PushClient {
// Configure notification cleanup
notificationCleanupConfig = NotificationCleanupConfig {
// Choose a cleanup mode: NONE, COUNT_BASED, AGE_BASED, or HYBRID
cleanupMode = NotificationCleanupConfig.CleanupMode.HYBRID
// Maximum notifications to keep when using COUNT_BASED or HYBRID mode
maxStoredNotifications = 50
// Maximum age in days for notifications when using AGE_BASED or HYBRID mode
maxNotificationAgeDays = 14
}
}
The properties you can provide are as follows:
- cleanupMode
-
The strategy the module uses to clean up notifications.
Choose from one of the following:
CleanupMode.NONE-
The module does not perform automatic cleanup of notifications.
CleanupMode.COUNT_BASED-
The module keeps a maximum number of notifications and deletes the oldest first when the limit is exceeded.
This is the default.
CleanupMode.AGE_BASED-
The module deletes notifications that are older than the specified number of days.
CleanupMode.HYBRID-
The module applies both count and age limits to the stored notifications.
- maxStoredNotifications
-
The maximum number of notifications to keep, if using the
COUNT_BASEDmode.If the number is exceeded, the module deletes the oldest notifications first to reach the threshold.
The default is
100. - maxNotificationAgeDays
-
The maximum number of days to keep a notification before removing it.
Defaults to
30.
You can choose to trigger notification cleanup on-demand rather than automatically by using the cleanupNotifications() method:
// Clean up notifications for all credentials
pushClient.cleanupNotifications()
.onSuccess { count ->
println("Removed $count old notifications")
}
// Clean up notifications for a specific credential
pushClient.cleanupNotifications(credentialId)
.onSuccess { count ->
println("Removed $count old notifications for credential $credentialId")
}
Closing the Push client
You can close the client, clean up any temporary files, and regain the memory used by calling the close() method:
// Close the Push client and clean up
pushClient.close()
Handling errors
The Push module uses Kotlin’s Result API for error handling, which provides a functional approach to error handling:
// Using onSuccess/onFailure
pushClient.addCredentialFromUri(uri)
.onSuccess { credential ->
// Success path
}
.onFailure { exception ->
when (exception) {
is IllegalArgumentException -> showError() // Handle invalid URI format
is MfaException -> showError() // Handle general MFA errors
is NetworkException -> showError() // Handle network connectivity issues
else -> showError() // Handle other exceptions
}
}
// Using fold for combined handling
pushClient.addCredentialFromUri(uri).fold(
onSuccess = { credential ->
// Handle success
},
onFailure = { exception ->
// Handle failure
}
)
// Using runCatching for additional operations
runCatching {
pushClient.addCredentialFromUri(uri).getOrThrow()
}.onSuccess { credential ->
// Do something with credential
}.onFailure { exception ->
// Handle error
}
Customizing credential storage
The Push module needs to store the credentials it uses on the client device.
By default, it uses an SQLite-based implementation, which you can customize.
You can also provide your own storage mechanism by implementing the PushStorage interface.
Customizing the default SQLite-based storage
The Push module uses the SQLPushStorage implementation for storing Push credentials by default.
You can customize this SQLite-based default as follows:
SQLPushStorage implementation// Create a custom storage instance with specific parameters
val customStorage = SQLPushStorage {
context = applicationContext
databaseName = "my_custom_push_db.db"
passphraseProvider = NonePassphraseProvider()
}
// Create the client with the custom storage
val pushClient = PushClient {
storage = customStorage
enableCredentialCache = true
}
The properties you can customize are as follows:
context-
The Android application context is a required property.
databaseName-
Optionally, rename the SQLite database.
databaseVersion-
Customize the database version.
The default is
1. passphraseProvider-
Specify a custom passphrase provider for encrypting the SQLite database.
-
Use
KeyStorePassphraseProvider()for encrypted storage using the Android KeyStore -
Use
NonePassphraseProvider()when you do not require the SQLite database to be encrypted.
We recommend you encrypt credentials whenever possible.
-
Implementing your own storage mechanism
You can implement a custom storage solution as an alternative to the default SQLPushStorage by implementing the PushStorage interface:
class MyCustomStorage : PushStorage {
override suspend fun storePushCredential(credential: PushCredential) {
// Implement storing the credential
}
override suspend fun retrievePushCredential(credentialId: String): PushCredential? {
// Implement retrieving a credential by ID
return null
}
override suspend fun removePushCredential(credentialId: String): Boolean {
// Implement deleting a credential by ID
return true
}
override suspend fun getAllPushCredentials(): List<PushCredential> {
// Implement listing all stored credentials
return emptyList()
}
override suspend fun storePushNotification(notification: PushNotification) {
// Implement storing a notification
}
override suspend fun retrievePushNotification(notificationId: String): PushNotification? {
// Implement retrieving a notification by ID
return null
}
override suspend fun removePushNotification(notificationId: String): Boolean {
// Implement deleting a notification by ID
return true
}
}
Customizing Push notification handlers
You can implement the PushHandler interface to support a custom push notification formats, if required:
class CustomPushHandler : PushHandler {
override fun canHandle(messageData: Map<String, String>): Boolean {
// Check if this handler can process the given payload
return payload.keys.contains("custom_push_key")
}
override fun parseMessage(messageData: Map<String, Any>): Map<String, Any> {
// Process the push payload and create a PushNotification
val notificationId = payload["message_id"] ?: return null
val issuer = payload["issuer"] ?: "Unknown"
val message = payload["message"] ?: "Authentication request"
// Populate and return a map associated with PushNotification fields
return mapOf(
"messageId" to notificationId,
"message" to message,
"issuer" to issuer,
"pushType" to PushType.DEFAULT // or CHALLENGE, BIOMETRIC based on payload
)
}
override fun sendApproval(
credential: PushCredential,
notification: PushNotification,
params: Map<String, Any>
): Boolean {
// Implement the approval logic
return runCatching {
// Make network request to approve the authentication
// ...
true
}
}
override suspend fun sendDenial(
credential: PushCredential,
notification: PushNotification,
params: Map<String, Any>
): Boolean {
// Implement the denial logic
return runCatching {
// Make network request to deny the authentication
// ...
true
}
}
override suspend fun setDeviceToken(
credential: PushCredential,
deviceToken: String,
params: Map<String, Any>
): Boolean {
// Implement the logic to set the device token for the credential
return runCatching {
// Make network request to register the device token
// ...
true
}
}
override suspend fun register(
credential: PushCredential,
params: Map<String, Any>,
): Boolean {
// Implement the registration logic
return runCatching {
// Make network request to register the credential
// ...
true
}
}
}
// Register your custom handler when initializing the PushClient
val pushClient = PushClient {
customHandlers = listOf(CustomPushHandler())
}