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 and biometric storage 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 library OktaStorage (opens new window) available through CocoaPods (opens new window).

To install the library, add the following line to your Podfile:

pod 'OktaStorage'

Now install the dependency and open the auto-generated workspace file:

pod install

Create an instance of OktaSecureStorage in your code:

let secureStorage = OktaSecureStorage()

Store tokens

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

oktaOidc.signInWithBrowser(from: self, callback: { stateManager, error in

    if let error = error {
        // handle error
        return
    }

    let authStateData = try? NSKeyedArchiver.archivedData(withRootObject: stateManager, requiringSecureCoding: false)
    guard let authStateData = authStateData else {
        // handle error
        return
    }
    
    do {
        try secureStorage.set(data: authStateData,
                              forKey: "okta_user",
                              behindBiometrics: secureStorage.isTouchIDSupported() ||
                                                secureStorage.isFaceIDSupported())
        } catch let error as NSError {
            // handle error
        }
})

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:

do {
    try oktaStorage.delete("jdoe")
} catch let error {
    // Handle error
}

Retrieve refresh token

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

DispatchQueue.global().async {
    do {
        let authStateData = try secureStorage.getData(key: "okta_user")
        guard let stateManager = try? NSKeyedUnarchiver.unarchiveTopLevelObjectWithData(authStateData) as? OktaOidcStateManager else {
            return
        }
    } catch let error as NSError {
        // handle error
    }
}

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

stateManager?.renew { updatedTokenManager, error in
    if let error = error else {
        // handle error
        return
    }

    // use updatedTokenManager
}