Instructions for

On this page

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

Sample code

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
    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

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

Custom Authenticator flow chart

Create a Custom Authenticator

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

Custom Authenticator 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.

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:

Alternatively, you can grant scopes using the Grant consent to scope for application operation of the Apps API.

Set up notification services

Add a Custom Authenticator

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


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