Configure an Android app for OATH MFA

PingOne Advanced Identity Cloud PingAM Android

This page guides you through configuring your Android application to support OATH-based Multi-Factor Authentication (MFA) using the OATH module.

It covers dependency setup, OATH client initialization, credential management, passcode generation, and custom storage options.

Step 1. Adding core dependencies

To add the core dependencies for OATH MFA:

In the Project tree view of your Android Studio project, open the build.gradle.kts file.

In the dependencies section, add the OATH module:

implementation("com.pingidentity.sdks:mfa:oath:2.0.0")

Step 2. Initializing the OATH Client

To use the OATH module you must initialize the OATH client in your application.

You can use the default OATH client configuration, or provide your own configuration using a DSL-style builder.

Default OATH client configuration

To use the default OATH client configuration, call the OathClient() method with no additional parameters.

When using the default configuration you will also need initialize the client, by using the initialize() method:

Initializing the OATH client with default config

val oathClient = OathClient()

// Initialize the client
oathClient.initialize()

Custom OATH client Configuration

To customize the OATH client configuration, call the OathClient() method and pass the custom configuration as parameters.

When you pass a custom configuration the OathClient() also initializes the client, without having to manually call an initialize method:

Initializing the OATH client with custom config

val oathClient = OathClient {
    enableCredentialCache = true
    // Any other configuration options
}

The properties you can use to customize OATH client configuration are as follows:

enableCredentialCache: Whether to enable in-memory caching of credentials.

By default, this is set to false for security reasons, as an attacker could potentially access cached credentials from memory dumps.
timeout: The timeout for network operations, in seconds.

Default value is 15 seconds.
storage: The storage implementation to use for OATH credentials.

If null, the default SQLOathStorage is used.

Learn more in Customizing credential storage.
policyEvaluator: The policy evaluator to use for credential policy validation.

If null, the default MfaPolicyEvaluator is used.
logger: The logger instance used for logging messages.

Defaults to the global logger instance.

Learn more in Logging.

Step 3. Managing OATH credentials

The OATH 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 details about how to generate the HOTP or TOTP key.

Creating OATH credentials

The OATH module lets the user register their device for OATH-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 directly in the callback output by the OATH Registration node.

Use the addCredentialFromUri() method to create OATH credentials and register an MFA device:

onSuccess
getOrThrow
getOrNull

Creating OATH credentials using onSuccess

// Obtain OATH URI from journey callback or QR code
val uri = "otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA1&digits=6&period=30"

// Create OATH credentials using onSuccess
oathClient.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}")
}

Creating OATH credentials using getOrThrow

// Obtain OATH URI from journey callback or QR code
val uri = "otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA1&digits=6&period=30"

// Create OATH credentials using getOrThrow
try {
    val credential = oathClient.addCredentialFromUri(uri).getOrThrow()
    // Use credential
} catch (e: Exception) {
    // Handle exception
}

Creating OATH credentials using getOrNull

// Obtain OATH URI from journey callback or QR code
val uri = "otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA1&digits=6&period=30"

// Create OATH credentials using getOrNull
val credential = oathClient.addCredentialFromUri(uri).getOrNull()
if (credential != null) {
    // Use credential
} else {
    // Handle null case
}

Getting OATH credentials

You can get a list of all the registered OATH credentials, or get an individual credential, by passing the credential ID as a parameter.

All OATH credentials
Specific OATH credential

Getting all OATH credentials

oathClient.getCredentials().onSuccess { credentials ->
    if (credentials.isEmpty()) {
        showMessage("No credentials found")
    } else {
        displayCredentials(credentials)
    }
}

Getting a specific OATH credential

oathClient.getCredential(credentialId).onSuccess { credential ->
    if (credential != null) {
        // Credential found, use it
        displayCredential(credential)
    } else {
        // Credential not found
        showMessage("Credential not found")
    }
}

Updating OATH 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:

Updating an OATH credential

// Change display properties
credential.displayAccountName = "Babs Jensen"
credential.displayIssuer = "Example.com Checking Account"

oathClient.saveCredential(credential).onSuccess { updatedCredential ->
    // Handle successful update
    showMessage("Credential updated")
}.onFailure { exception ->
    // Handle failure
    showError("Failed to update credential: ${exception.message}")
}

Deleting OATH credentials

Use the deleteCredential() method to remove individual credentials from the client device. Pass the credential ID into the method as a parameter:

Deleting an OATH credential

// Remove a credential by ID
oathClient.deleteCredential(credentialId).onSuccess { isDeleted ->
    if (isDeleted) {
        showMessage("Credential deleted")
    } else {
        showMessage("Credential not found")
    }
}.onFailure { exception ->
    showError("Failed to delete credential: ${exception.message}")
}

Step 4. Generating OATH-based one-time passcodes

To perform OATH-based multi-factor authentication the user needs to enter the correct one-time passcode.

Your client app needs to generate these one-time passcodes and display them to the user.

Generating HOTP codes

Use the generateCode method to create an HOTP code using the details within the specified credential:

Generating an HOTP for an OATH credential

// Generate code for a credential by its ID
oathClient.generateCode(credentialId).onSuccess { code ->
    // Implement displaying the generated code
    displayCode(code)
}.onFailure { exception ->
    // Handle error
    showError("Failed to generate code: ${exception.message}")
}

Generating TOTP codes

For TOTP codes, the code object you generate contains timing and progress information that you can use to customize the user interface:

Generating a TOTP with timing and progress information

// Generate code with timing info for a credential
oathClient.generateCodeWithValidity(credentialId).onSuccess { codeInfo ->
    // Implement displaying the generated code
    displayCode(codeInfo.code)
    // Implement showing how long the code has been valid for
    updateProgressBar(codeInfo.progress)
    // Implement a countdown before generating a new code
    startCountdown(codeInfo.timeRemaining)
}.onFailure { exception ->
    // Handle error
    showError("Failed to generate code: ${exception.message}")
}

Step 5. Closing the OATH client

You can close the client, clean up any temporary files, and regain the memory used by calling the close() method:

Closing an OATH client

// Close the OATH client and clean up
oathClient.close()

Handling errors

The OATH module uses Kotlin’s Result API for error handling, which provides a functional approach to error handling:

Handling errors using the Result API

// Using onSuccess/onFailure
oathClient.addCredentialFromUri(uri)
    .onSuccess { credential ->
        // Success path
    }
    .onFailure { exception ->
        when (exception) {
            is IllegalArgumentException -> // Handle invalid URI format
            is MfaException -> // Handle general MFA errors
            else -> // Handle other exceptions
        }
    }

// Using fold for combined handling
oathClient.addCredentialFromUri(uri).fold(
    onSuccess = { credential ->
        // Handle success
    },
    onFailure = { exception ->
        // Handle failure
    }
)

// Using runCatching for additional operations
runCatching {
    oathClient.addCredentialFromUri(uri).getOrThrow()
}.onSuccess { credential ->
    // Do something with credential
}.onFailure { exception ->
    // Handle error
}

Customizing credential storage

The OATH 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 OathStorage interface.

Customizing the default SQLite-based storage

The OATH module uses the SQLOathStorage implementation for storing OATH credentials by default.

You can customize this SQLite-based default as follows:

Customizing the SQLOathStorage implementation

// Create a custom storage instance with specific parameters
val customStorage = SQLOathStorage {
    context = applicationContext
    databaseName = "my_custom_oath_db.db"
    passphraseProvider = NonePassphraseProvider()
}

// Create the client with the custom storage
val oathClient = OathClient {
    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 the credential whenever possible.

Implementing your own storage mechanism

You can implement a custom storage solution as alternative to the default SQLOathStorage by implementing the OathStorage interface:

Implementing custom OATH credential storage

class MyCustomStorage : OathStorage {
    override fun initialize() {
        // Initialize your custom storage
    }

    override fun close() {
        // Close storage
    }

    override fun clear() {
        // Remove all data
    }

    override fun storeOathCredential(credential: OathCredential) {
        // Store credential data
    }

    override fun retrieveOathCredential(credentialId: String): OathCredential? {
        // Retrieve credential data
        return null
    }

    override fun getAllOathCredentials(): List<OathCredential> {
        // Retrieve all credentials of a type
        return emptyList()
    }

    override fun removeOathCredential(credentialId: String): Boolean {
        // Delete credential data
        return true
    }

    override fun clearOathCredentials() {
        // Clear all credentials of a type
    }
}

For an example implementation that uses Android’s SharedPreferences for storage, refer to SharedPrefsOathStorage in the ping-android-sdk repo.

The SharedPrefsOathStorage implementation is for demonstration purposes only, and should not be used for storing potentially sensitive data such as OATH credentials.

Orchestration SDKs