Unlock a mobile app with biometrics

Note: This document is written for Okta Classic Engine. If you are using Okta Identity Engine, contact your Okta account team for guidance or ask on our forum. See Identify your Okta solution to determine your Okta version.

This guide discusses how to integrate biometric authentication like Face ID and Touch ID to your mobile apps that use Okta.

---

Learning outcomes

• Handle biometric challenges for your users, storing and retrieving tokens as required
• Delete access tokens when no longer required

What you need

An app to update with biometric unlock with Touch ID, Face ID, and Smart Lock. See Sign users into your mobile app using the redirect model guide.

Sample code

See the Browser sign-in sample (opens new window) for Classic Engine.

---

Overview

When you configure the Okta SDK with the offline_access scope, your mobile app gets a refresh token from Okta. The refresh token is long-lived and is used to keep the user signed in to your app.

The refresh token is used to get new access tokens. Access tokens allow your mobile app to make authenticated requests to your API, but are short-lived. As access tokens expire, the refresh token is used to obtain new access tokens.

By storing the refresh token on the device and encrypting it with a biometric challenge, you can safely keep the user signed in, but require the user to pass a biometric challenge to keep using the app. This means that the user must sign in with their password the first time, but can then use their fingerprint or face to unlock the app after that.

Add and configure packages

Add the Okta SDK to your app.

Use the Okta OIDC (opens new window) library available through Maven Central (opens new window).

To install the library, add the following to your build.gradle:

implementation 'com.okta.android:okta-oidc-android:1.0.19'

Store tokens

When the user finishes signing in and you receive tokens from Okta, store the refresh token with a biometric requirement.

First create an encryption manager and set it in the WebAuthBuilder like the following:

private GuardedEncryptionManager keyguardEncryptionManager = new GuardedEncryptionManager(this, Integer.MAX_VALUE);
...
...
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    config = new OIDCConfig.Builder()
        .clientId("{yourClientId}")
        .redirectUri("{redirectUri}")
        .endSessionRedirectUri("endSessionUri")
        .scopes("openid", "profile", "offline_access")
        .discoveryUri("{discoveryUri}")
        .create();

    webAuth = new Okta.WebAuthBuilder()
        .withConfig(config)
        .withContext(getApplicationContext())
        .withEncryptionManager(keyguardEncryptionManager)
        .create();
        }
}

This sets up the client to require that the device be authenticated in order to use the private key.

Discard access tokens

When you need to delete the access token from secure storage (for example, when an access token expires or a user wants to delete their account), do the following:

authClient.getSessionClient()
    .clear();

Retrieve refresh token

Present a biometric challenge to the user to get a new refresh token.

Set up utility methods to use the KeyguardManager as a challenge for device authentication.

private static final int REQUEST_CODE_CREDENTIALS = 1000;
...
...
private boolean isKeyguardSecure() {
    KeyguardManager keyguardManager =
        (KeyguardManager) getSystemService(Context.KEYGUARD_SERVICE);
    return keyguardManager.isKeyguardSecure();
}

private void showKeyguard() {
    KeyguardManager keyguardManager =
        (KeyguardManager) getSystemService(Context.KEYGUARD_SERVICE);
    Intent intent = null;
    if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.LOLLIPOP) {
        intent = keyguardManager.createConfirmDeviceCredentialIntent("Confirm credentials", "");
    }
    if (intent != null) {
        startActivityForResult(intent, REQUEST_CODE_CREDENTIALS);
    }
}

We require device authentication every time the user leaves the app, so put that check in onResume:

@Override
protected void onResume() {
    super.onResume();
    if (webAuth.getSessionClient.isAuthenticated() &&
        !keyguardEncryptionManager.isUserAuthenticatedOnDevice()) {
            showKeyguard();
        }
    }

Then, use the refresh token to get a new access token.

Override onActivityResult to get the results from the Keyguard.

@Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == REQUEST_CODE_CREDENTIALS && resultCode == RESULT_OK) {
            if (keyguardEncryptionManager.getCipher() == null) {
                keyguardEncryptionManager.recreateCipher();
            }
        } else {
            webAuth.handleActivityResult(requestCode, resultCode, data);
        }
    }

After RESULT_OK is returned, the device is authenticated and keyguardEncryptionManager is able to decrypt all of the encrypted data, including the access and refresh tokens.