Custom authenticator integration guide

Identity Engine

Enable a mobile app to verify a user identity for an Okta custom authenticator.

---

Learning outcome

• Create a Custom Authenticator.
• Use the Devices SDK to turn your mobile app into a push authenticator.

What you need

• An Okta developer app

• Firebase Cloud Messaging (FCM) (opens new window)

• An Android app in your org. See the Okta Kotlin Mobile SDK (opens new window).

• (Optional) Access to the following APIs:
  • Apps (opens new window)
  • Push providers (opens new window)
  • Authenticator (opens new window)
  • MyAccount App authenticators (opens new window)
  • Authorization Servers (opens new window)

Sample code

See the Android Devices SDK sample app (opens new window).

---

About custom authentication and the Devices SDK

The Devices SDK allows you to embed push notifications and biometrics directly into your mobile app. As a result, you can control the entire authentication experience by keeping users on your mobile app for the entire sign-in process.

The Devices SDK implements the Custom Authenticator. The Custom Authenticator is another authenticator besides Okta Verify you can use for push notifications. In addition, by implementing a custom authentication flow in your app, you also help drive downloads of your app.

Get started

This guide walks you through the two main tasks needed to integrate with the Okta Devices SDK:

Create a Custom Authenticator

1. Create an OIDC web authentication client: Set up OAuth for your app.
2. Grant the required scopes: Grant the scopes that you need to create a Custom Authenticator.
3. Set up notification services: Set up

   Firebase Cloud Messaging (FCM)

   with your Okta org.
4. Add a Custom Authenticator: Create and brand a Custom Authenticator.
5. Set up a global session policy and authentication policy: Control who can access Okta and how.

Install and configure the Okta Devices SDK

1. Install the dependency: Add the Okta Devices SDK dependency to your build.gradle file.
2. Initialize the client: Create the SDK object to work with your Okta authenticator configuration.
3. Enroll the device: Register a device and optional biometrics with an account for use with the custom authenticator.
4. Respond to a challenge: Resolve a delivered challenge from the custom authenticator or retrieve an undelivered challenge. Refresh the FCM device registration token, remediate changed biometrics, and deregister the account on the device.

The following image shows what the Devices SDK enables for end users:

Create a Custom Authenticator

The following image shows the Devices SDK setup in the Admin Console:

Create an OIDC web authentication client

The simplest way to integrate authentication in your app is to use the Authorization code flow grant type and implement the OIDC protocol through a web browser. You need an access token to start the enrollment flow for the Devices SDK. For future sign-in attempts, consider using refresh tokens.

See the Android Devices SDK sample app (opens new window).

Note: For certain background interactions between the app and Okta's server, the JWT Bearer grant type (opens new window) is used. For more information, see Access Token Management.

Grant the required scopes

When you're ready to grant the required scopes, follow these steps:

1. Sign in to your Okta organization with your administrator account.
2. Select Applications > Applications to see a list of your app integrations.
3. Open your OpenID Connect client app.
4. On the Okta API Scopes tab, click Grant for the following scopes:
   • For access to both GET and POST/DELETE endpoints:
     • okta.myAccount.appAuthenticator.manage
   • For access to GET endpoints only:
     • okta.myAccount.appAuthenticator.read

Alternatively, you can grant scopes using the Grant consent to scope for app (opens new window) operation of the Apps API.

Set up notification services

1. In the Admin Console, go to Security > Device integrations.
2. Click Notification Services.
3. Click Add Notification Service, then select FCM.
4. Enter the required information:
   • Name: Enter a unique name for the FCM service.
   • Service account JSON: Enter your service account key in JSON format. You can use the Google Cloud Console, Google Cloud CLI, or one of the client libraries to create your service account key. See Creating and managing service account keys (opens new window).
5. Click Add.

After you’ve added a notification service, you can check for successful and failed push notifications sent to users in the System Log. See View push notification events (opens new window).

Alternatively, you can add a notification service using the Push Providers API (opens new window).

Add a Custom Authenticator

1. In the Admin Console, go to Security > Authenticators.
2. On the Setup tab, click Add Authenticator.
3. Click Add on the Custom Authenticator tile.
4. Configure the following settings:
   • Authenticator name: Name for the authenticator. This name is displayed to end users when they sign in.
   • Add to existing application: Select the app that receives the push MFA prompt.
   • User Verification: Choose whether the user must provide a PIN or biometric verification during authentication.
     • Preferred: User verification is optional.
     • Required: User verification is required during setup.
   • Authenticator logo: Select the logo for the authenticator. The end user sees this logo on the authentication pages.
     • Browse files: Upload your logo. It must be an SVG file less than 1 MB. For better quality, use a square logo with a transparent background.
     • Use default logo: Use the default logo.
5. Configure the connection to the push notification service:
   • FCM configuration: Select the connection to the FCM service that you want the custom authenticator to use.
6. Select the checkbox to agree to the Okta terms and conditions mentioned in the Admin Console.

   Note: By adding this feature, you agree to provide any required notices and disclosures to end users. This is your sole responsibility on behalf of the entity that you represent. Include any necessary information from https://www.okta.com/privacy-policy (opens new window).

7. Click Add. The authenticator appears in the list on the Setup tab.

Alternatively, you can create an authenticator using the Authenticator API (opens new window).

Set up a global session policy and authentication policy

Set up a global session policy and an authentication policy to integrate with the Devices SDK. See configure a global session policy and authentication policy.

Install and configure the Okta Devices SDK

Use the Devices SDK to add custom push verification functionality to your Android app.

Note: The following sample code assumes that suspend functions are called from a coroutine. See Kotlin coroutines (opens new window).

The following image shows how data flows through the Devices SDK:

Install the dependency

Add the Okta Devices SDK dependency to your build.gradle file:

implementation("com.okta.devices:devices-push:$okta.sdk.version")

The latest release version is $okta.sdk.version. See Release status (opens new window) for the latest Okta Devices SDK version.

Initialize the client

Create the SDK object to work with your Okta authenticator configuration. Use the PushAuthenticatorBuilder to create an authenticator with your application configuration:

If the end user doesn't provide a passphrase, the Devices SDK data isn't encrypted. Secure the passphrase:

val authenticator: PushAuthenticator = PushAuthenticatorBuilder.create(
    ApplicationConfig(context, appName = "MyApp", appVersion = BuildConfig.VERSION_NAME)
) {
    passphrase = "SecretPassphrase".toByteArray() // Secret must be stored securely
}.getOrThrow()

Enroll the device

Before enrolling the device, ensure that you have the following:

• An OIDC Web Authentication client. See Create an OAuth 2.0 app integration.
• A custom authenticator. See Add a custom authenticator.
• A registration token from Firebase. See Set up notification services.

To start enrolling the user:

val authConfig = DeviceAuthenticatorConfig(URL(orgUrl), "oidcClientId")
val result = authenticator.enroll(AuthToken.Bearer("accessToken"), authConfig, EnrollmentParameters.Push(FcmToken("registrationToken"), enableUserVerification = false))
if (result.isSuccess) {
    val pushEnrollment: PushEnrollment = result.getOrThrow()
}

Alternatively, you can enroll the device by using the MyAccount App Authenticators API (opens new window).

Retrieve enrollments

To retrieve information about existing enrollments, use allEnrollments(). You can use this to display attributes for a list of accounts or find a specific account to update or delete it. Retrieve all previously enrolled PushEnrollment:

val enrollments: List<PushEnrollment> = authenticator.allEnrollments().getOrThrow()

Update the registration token

Whenever the FCM SDK sends your application a new token with FirebaseMessagingService.onNewToken, you can update existing enrollments with the new token by doing the following:

val enrollments: List<PushEnrollment> = authenticator.allEnrollments().getOrThrow()

// Find the enrollment associated with the current user
enrollments.find { it.user().name == "myUser" }?.let { pushEnrollment ->
    pushEnrollment.updateRegistrationToken(AuthToken.Bearer("accessToken"), FcmToken("newToken"))
        .onSuccess { println("success") }
        .onFailure { println("failure") }
}

Alternatively, you can update the registration token by using the MyAccount App Authenticators API (opens new window).

Update user verification

User verification checks that a user is the one claimed. You can do this by asking the user for biometrics. You can enable or disable user verification by doing the following:

val enrollments: List<PushEnrollment> = authenticator.allEnrollments().getOrThrow()

// Find the enrollment associated with the current user
enrollments.find { it.user().name == "myUser" }?.let { pushEnrollment ->
    pushEnrollment.setUserVerification(AuthToken.Bearer("accessToken"), true)
        .onSuccess { println("success") }
        .onFailure { println("failure") }
}

Alternatively, you can update user verification by using the MyAccount App Authenticators API (opens new window).

Delete enrollment

Use the delete function to delete an enrollment from both the server and the device:

val enrollments: List<PushEnrollment> = authenticator.allEnrollments().getOrThrow()

// Find the enrollment associated with the current user and delete it
enrollments.find { it.user().name == "myUser" }?.let { pushEnrollment ->
    authenticator.delete(AuthToken.Bearer("accessToken"), pushEnrollment)
        .onSuccess { println("success") }
        .onFailure { println("failure") }
}

Alternatively, you can delete an enrollment by using the MyAccount App Authenticators API (opens new window).

Delete enrollment from the device

The deleteFromDevice function doesn't call the server, so it doesn't require authorization. As a result, the function only deletes the enrollment from the device.

Note: Use deleteFromDevice with caution as the user can't meet factor requirements for sign-in attempts after deletion. The server is unaware the authenticator no longer exists.

val enrollments: List<PushEnrollment> = authenticator.allEnrollments().getOrThrow()

// Find the enrollment associated with the current user
enrollments.find { it.user().name == "myUser" }?.let { pushEnrollment ->
    pushEnrollment.deleteFromDevice()
        .onSuccess { println("success") }
        .onFailure { println("failure") }
}

Respond to a challenge

When a user attempts to sign in to the enrolled account through an app or a web browser, Okta creates a push challenge. Your push provider sends the push challenge to enrolled devices.

Resolve delivered challenges

After you receive a challenge, your app should resolve them to proceed with the sign-in flow. The SDK may request remediation steps to resolve the challenge:

• UserConsent: Asks the user to approve or deny the challenge.
• UserVerification: Notifies the app that it requires a biometric verification to proceed.

See the Devices SDK sample app (opens new window) for complete details about resolving a push challenge.

val fcmRemoteMessage = "PushChallengeString" // fcm challenge

authenticator.parseChallenge(fcmRemoteMessage)
    .onSuccess { challenge ->
        challenge.resolve().onSuccess { remediation ->
            remediate(remediation) // call method to handle remediation
        }.onFailure { println("failure") }
    }.onFailure { println("failure") }

private fun remediate(remediation: PushRemediation) = runCatching {
    when (remediation) {
        is Completed -> println("Successfully handled. sign in success")
        is UserConsent -> println("Show a UX to accept or deny")
        is UserVerification -> println("Show a biometric prompt")
        is UserVerificationError -> println("Biometric failure")
    }
}.getOrElse { // handle error
}

Alternatively, you can respond to a challenge by using the MyAccount App Authenticators API (opens new window).

Retrieve undelivered challenges

Sometimes FCM fails to deliver a notification to the user. Add code to check for pending challenges:

val enrollments: List<PushEnrollment> = authenticator.allEnrollments().getOrThrow()

// Find the enrollment associated with the current user
enrollments.find { it.user().name == "myUser" }?.let { pushEnrollment ->
    pushEnrollment.retrievePushChallenges(AuthToken.Bearer("accessToken"))
        .onSuccess { println("success") }
        .onFailure { println("failure") }
}

Alternatively, you can retrieve undelivered challenges by using the MyAccount App Authenticators API (opens new window).

Access token management

The SDK communicates with an Okta server using the HTTPS protocol and requires an access token for user authentication and authorization. For authentication flows and access token requests, use the latest version of the Okta Kotlin Mobile SDK (opens new window). To enroll a push authenticator, the user needs to have an access token that contains the okta.myAccount.appAuthenticator.manage scope. You can also use this scope for the following operations:

• Enroll and unenroll user verification keys

• Update device tokens for push authenticator enrollment

• Request pending push challenges

• Enable and disable CIBA capability for push authenticator enrollment

• Delete push authenticator enrollment

  Note: Applications that use sensitive data shouldn't store or cache access tokens or refresh access tokens that contain the okta.myAccount.appAuthenticator.manage scope. Instead, reauthenticate the user and get a new access token.

  The following is a list of operations that are considered high risk and require reauthentication:

  • Enroll push authenticator
  • Enable or disable user verification for push authenticator enrollment
  • Delete push authenticator enrollment

Maintenance token configuration and usage

Other operations are low risk and may not require interactive authentication. For that reason, the Okta Devices SDK provides the silent user reauthentication method, retrieveMaintenanceToken. This method retrieves a maintenance access token for reauthentication that allows an application to silently perform the following operations:

• Request pending push challenges
• Enable and disable CIBA capability for the push authenticator enrollment
• Update device tokens for push authenticator enrollment

To successfully obtain the maintenance token, you must first configure your Okta OIDC application to support the JWT Bearer grant type:

• You can use the Apps API's update app (opens new window) operation (PUT /apps/${appId}) to modify the settings.oauthClient.grant_types property array to include the JWT Bearer grant type, urn:ietf:params:oauth:grant-type:jwt-bearer.

• Alternatively, when you use the Admin Console to add or update the OIDC application in a custom authenticator, the application automatically updates with the JWT Bearer grant type. See Add a custom authenticator.

Apps API usage sample

Explore the Configure and Use JWT Bearer Grant (opens new window) Postman Collection for API examples of how to do the following:

• Get your OIDC app object properties.
• Update your OIDC app to include the urn:ietf:params:oauth:grant-type:jwt-bearer grant type.
• Obtain a token with your OIDC app client ID.

Fork this collection and add url, apiKey, appId, and yourClientId environment variables to run the example endpoints. The PUT method is a full property-replace operation, so you need to specify all required OIDC app properties, including any previous grant types. See Create an API token to obtain an apiKey from your org for testing purposes.

Kotlin maintenance token usage example

suspend fun retrievePushChallenges() {
    val readScope = listOf("okta.myAccount.appAuthenticator.maintenance.read")
    val enrollments = pushAuthenticator.allEnrollments().getOrThrow()
    enrollments.forEach { enrollment ->
        enrollment.retrieveMaintenanceToken(readScope).onSuccess {authToken ->
            enrollment.retrievePushChallenges(authToken).onSuccess { challenges ->
                println("Challenges retrieve: $challenges")
            }.onFailure {error ->
                println(error.localizedMessage)
            }
        }.onFailure { error ->
            println(error.localizedMessage)
        }
    }
}

Troubleshoot

If your push notifications aren't delivering:

1. Follow the steps to view push notification events (opens new window).
2. To narrow your search parameters, enter the following: eventType eq "device.push.provider.update" and displayMessage eq "Push Provider Configuration verification failed". See Event types.
3. In the Reason section, locate the error message from your push provider. Consult the push provider documentation, if necessary.
4. Verify that your notification services configuration is valid. See Edit a notification service (opens new window).
5. Click Save to allow push providers to attempt to send notifications again.
6. If your push notifications aren't delivered, repeat steps 1 through 5.

See also

See Web authentication using OIDC redirect (opens new window).