Okta Devices SDK Sample App

Powered by the Okta Devices Platform Service, the Okta Devices SDK and the Devices API offer a single integration to unify user identity and device identity, along with all of the tools necessary to build passwordless sign-in flows through branded push notifications and biometric capabilities. All of these powerful functionalities come together to deepen security without sacrificing customer engagement. 

Consistent branding across all of your digital touch points is an important way to create a cohesive customer experience. Using the Okta Devices SDK, developers can embed Okta Verify push capabilities into their mobile application, or even build their own branded Okta Verify mobile application. In either case, developers can send customizable, branded push notifications and use biometrics for a frictionless login experience. 

See the following video which demonstrates the Devices SDK Sample App in action.

Sample App Setup Procedure

The new Devices SDK is now available along with a sample app that demonstrates the custom push functionality. These are the steps to get the Sample App (Android version) working with your Workforce Identity Cloud (WIC) tenant.

Note: This is an Early Access feature. To enable it, use the Early Access Feature Manager as described in Manage Early Access and Beta features. Also note that the Devices SDK and Sample App will only work with the Okta Identity Engine (OIE).

The main documentation can be found here: Custom authenticator integration guide | Okta Developer

The Devices SDK download can be found here: GitHub – okta/okta-devices-kotlin: okta-devices-kotlin

At a high level, this is the setup required in your Okta tenant:

1. Create an OIDC authentication client with required scopes
2. Set up notification services
3. Add custom authenticator
4. Set up global session policy and authentication policy

Step 1 – Create a OIDC Client App

Log onto your Okta administration console and go to applications. Create a new OIDC app of type Native Application. As well as the default Grant Type of Authorization Code, select Refresh Token. Either assign the app to everyone in your tenant or assign it to the respective users permitted to use the custom push authenticator.

On the Okta API Scopes tab, click Grant for the following scopes:

• okta.authenticators.manage.self
• okta.authenticators.read
• okta.users.read.self

Step 2 – Configure Firebase Cloud Messaging

Firebase Cloud Messaging (FCM) provides a reliable and battery-efficient connection between your server and devices that allows you to deliver and receive messages and notifications on iOS, Android, and the web at no cost.

The FCM architecture is depicted in the following diagram:

For additional information, see the following documentation: FCM Architectural Overview  |  Firebase Cloud Messaging

Create Firebase Project

Go to the Firebase console here https://console.firebase.google.com/ and create a new project.

Here are my project settings:

Add an Android App to your Project

Once your project has been created, we need to add an app to the project. In our case it is going to be an Android app.

Step 1 – Click the Add App button and select Android.

Step 2 – Then configure the app with the following package address:

example.okta.android.push_sample_app

Step 3 – Click next and then as part of Step 2, you can download the google-services.json file. Save the file for later use.

Step 4 – Click Next until the app has been created under your project.

Create an API Key

Now go to the google cloud console here: https://console.cloud.google.com/ and select the Firebase project that was created in the previous step. There will be a project select drop down in the top left corner of the console. Then follow these steps:

Step 1 – Select the IAM and Admin menu option. Then on the menu on the left, select Service Accounts.

Step 2 – The process of creating a Firebase Project should have resulted in a service account being created. Ensure the service account matches the following:

Step 3 – Open the service account and click on the KEYS tab at the top. Then click on Add Key > Create New Key. Ensure a Key Type of JSON is selected. Once created, the keys JSON file will automatically be downloaded. Save this file for later use.

Thats the end of the Firebase Cloud Messaging setup. You now should have two JSON files:

1. google-services.json
2. okta-custom-push-dae0a-3c4385d15335.json (Service Account JSON file)

Step 3 – Set Up Notification Service

See the Notification Service documentation here: Notification services | Okta

The enabling of the new Custom Push Authenticator in your Okta tenant will have also enabled Notification Services. Log into the Okta administration console and go to Security > Device Integrations and then follow these steps:

1. Open the Notification Services tab and select Add notification service.
2. Select Firebase Cloud Messaging (FCM)
3. Give the service a meaningful name and select the Service Account JSON file created under Step.

Then click Add to finish the setup.

Notification events can be viewed by selecting Actions > Events

If your sample app does not receive push notifications, then these event log messages will usually indicate where the error is.

Step 4 – Add a Custom Authenticator

The Custom Authenticator documentation can be found here: Configure the Custom Authenticator | Okta

The Custom Authenticator will appear as the following:

In the Okta administration console, go to Security > Authenticators and under the setup tab, and do the following:

1. Click Add Authenticator.
2. Select the Custom Authenticator.
3. Give the authenticator a meaningful name.
4. Under Add to existing application, select the application created under Step 1.
5. Leave User Verification set to Preferred.
6. Optionally add a logo to your authenticator.
7. Under Push Notification Configuration, leave the APNs configuration blank, but select the FCM configuration that you created in the previous step.
8. Then select Add and ensure the new authenticator has a status of Active.
9. Now go to the Authenticators Enrollment tab.
10. Ensure your new Custom Authenticator is set to Optional under the respective enrollment policy.

Step 5 – Configure a Global Session Policy and Authentication Policies

See the documentation here: Configure a global session policy and authentication policies | Okta Developer

Follow the documentation to setup the required global session policy and application authentication policies so your tenant users will be prompted for the custom authenticator during initial tenant login and/or when the users access specific applications.

Here is an example of my configured sign on where the user has the option of signing in with a number of factors including my custom Atko Cars Custom Push factor.

Step 6 – Download and Compile Sample App

It is possible to build the project at the command line, but it’s much easier if you import the project into Android Studio. Additionally, you will need an emulator to run the app. Android Studio comes with a built in emulator. At this point, install Android Studio if not already installed. Open Android Studio and run Check for Updates in before proceeding, as the SDK will not work with older versions.

Create Virtual Device

On the Android Studio welcome screen, click on the three dots in the top right and select Virtual Device Manager.

Once device manager opens, click Create Device and choose the hardware.

Then click Next and select the system image.

The main advice would be to select a recent release of Android. In my test, I went for an API level of 32 with Android version 12L.

Click Next and give the device a meaningful name and click Finish.

Finally start the device and ensure it runs correctly. When starting the device for the first time, I found that this takes a number of minutes. Once running, close the emulator.

Note: To save time, close the emulator without powering down the device. This will save the device state and will be much quicker next time.

Import SDK and Sample App

The Okta Custom Push (Devices SDK) and Sample App can be downloaded from here: GitHub – okta/okta-devices-kotlin: okta-devices-kotlin

Download the whole project. Within Android Studio, select Open from the welcome screen and select the parent directory of the download. (okta-devices-kotlin-master)

Android Studio will prompt you to trust the project.

At this point the project will open and start pulling in all of the dependancies. Once completed, the project structure should match the following:

The directory titled devices-push contains the Custom Push SDK and the directory titled push-sample-app contains the sample application that we will be testing. By default, the push-sample-app uses the SDK and runtime under devices-push. This can be changed so the push-sample-app imports a pre-compiled version of the SDK runtime. You may want to do this if the devices-push portion of the project does not compile correctly.

To do this, open the push-sample-app directory and then open the build.gradle.kts file. Under dependancies, replace:

implementation(project(":devices-push"))

with the following:

implementation("com.okta.devices:devices-push:0.0.2")

Update Local Properties File

In the root director of the project, open the file titled local.properties and update the values to the following:

oidc.scheme={yourOidcScheme} 
org.url="{yourOrgUrl}" 
oidc.client.id="{yourOrgClientId}" 
oidc.redirect.uri="{yourRedirectUri}" 
oidc.scope="openid profile email offline_access okta.authenticators.manage.self okta.authenticators.read okta.users.read.self"

Here is an example of my properties file:

oidc.scheme=com.okta.ms2 
org.url="https://ms2.okta.com" 
oidc.client.id="0oa3ufztjeBfiSEEd101" 
oidc.redirect.uri="com.okta.ms2:/callback" 
oidc.scope="openid profile email offline_access okta.authenticators.manage.self okta.authenticators.read okta.users.read.self"

Update Google Services JSON

Open the push-sample-app directory and replace the google-services.json file with the one generated as part of Step 2.

Thats the end of the setup and configuration. The sample app is now ready to be tested.

Running the Sample App

To run the sample app within Android Studio, select the run configuration of push-sample-app, select the virtual device created as part of Step 6 and click the run button.

Device Registrations

Now that the user has enrolled their custom push authenticator, their device will be registered under Directory > Devices within the administration console. Every registered device in Identity Engine is a unique object within Okta Universal Directory. This gives you visibility into the devices that access Okta and enables you to make decisions about user access. For additional information on Okta Devices, see this page: https://help.okta.com/oie/en-us/Content/Topics/identity-engine/devices/devices-main.htm

Limitations

The custom push authenticator cannot be set to Required within an enrollment policy as it is not yet supported on every platform.