Orchestration SDK (Java Edition) – Trusted Device Activation with Android Studio: Part 2

Hakim Aldaoub, October 28, 2020

In this blog, we will illustrate how to obtain the constants required by the Orchestration SDK, create an Android Virtual Device (AVD), and activate the application by provisioning a user instance. This is a continuation of what we started in Orchestration SDK- Trusted Device Activation with Android Studio: Part1, where we introduced the Orchestration SDK for OneSpan Mobile Security Suite and set up the push notification of the cloud messaging service to the sample app after importing it to Android Studio. We will walk through the steps to activate the sample app on a trusted device, so the end user can be prompt to step-up authentication whenever required. A full deep dive of the code will be saved for a future blog series.

Assigning the Main Constants of the App

After obtaining the Sender ID from Firebase in Part 1 and assigning its value to ANDROID_SENDER_ID in your Java code, it is time to place the required values for the remaining parameters to successfully run the application and activate the trusted device.

To do so, open the Constants class of the Utils package in the sample code, and assign values for the static strings of the class as explained below:

  • Replace the ACCOUNT_IDENTIFIER placeholder with the tenant ID value for the Sandbox user in the community portal, you can find it in your sandbox details page as shown below.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_1

  • Replace CLOUD_SERVER_URL placeholder with the URL part specific to the Sandbox environment, the value is .sdb.tid.onespan.cloud.
  • The domain constant will be automatically populated for you in this sample app, it is the ACCOUNT_IDENTIFIER value enforced to lower case.
  • The ENDPOINT_URL string will be constructed as follows:
    "https://" + ACCOUNT_IDENTIFIER + CLOUD_SERVER_URL + "/v1/orchestration-commands"
  • Assign a 32 byte random hexadecimal string ( 64 characters) to SALT_STORAGE and SALT_DIGIPASS. An online random hex generator could be used to obtain the two strings. These salt strings will be appended by the Orchestration SDK to some of the hashed values exchanged in the different commands. This will significantly increase the complexity of the sensitive data against rainbow tables attacks. In addition, the salt strings must certainly be unique for each end user.
  • Finally, the SERVER_COMMAND_KEY is already assigned for you with the value command. It’s the JSON key for network requests.

You could consult the screenshot below for an example of all the strings placed in the class.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_2

Customizing Messages on the Sample App

You could personalize the sample app by customizing its name, the welcome message, how the user name is displayed, or the title of the pages. You could make such customizations from “strings” xml file located in the resources package. For example, you could alter title_activity_main UI component to the value that you would like to be displayed on the main screen of the sample app.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_3

Creating an Android Virtual Device

There are two options to build and run the application in terms of the mobile device physicality. You could either run the sample app on a real device which has an Android OS, or you could take advantage of the Android Virtual Device manager from Android Studio, which we chose to utilize throughout the tutorial to simulate an Android device.

Steps to Create an AVD

From the tools menu in Android Studio, chose AVD Manager. Alternatively, you could find it under “No Device” dropdown beside the execution button as highlighted below.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]4_1

Click on “Create Virtual Device” shown below:

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_5

Select the hardware as “Phone” from “Category”. Then, select the device model you wish to run the application on and click Next. In this exercise, we will go with Pixel 3a.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_6

Select the Android OS target from the screen below. The version must be 4.1 or later. We will go with the most recent version, Android 10.0. Click “Download” and then “Next” upon completion of the installation. This might take a few minutes to download the system image. After that click “Finish”.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_7

Choose the AVD name and the startup orientation, then click “Finish”.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_8

Running the App

Now it is time to run the application on the virtual device and activate the authenticator instance. This will finalize the user provisioning.

The welcome screen below will show up and give you the option to “Start Activation”

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_9

After you click “Start Activation”, the registration page will show up on the mobile device, prompting you to type in the user ID and Activation Password of the end user. This step requires a registered user. This will be achieved by calling user/register endpoint of the Interactive Sandbox API. The response payload will carry the required activation password for the end user. You could refer to OneSpan Developer: Intelligent Adaptive Authentication - User Registration for a complete explanation of how to register a user.

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_10

After you provide the user ID and activation password strings and click “Register”, you will be prompted by the app to enter your PIN and confirm it.

Once complete, you will have finished the trusted device activation. You will be redirected to the screen shown below which will allow you to perform different types of activities securely, like logging-in and transaction signing. 

OneSpan-BlogImage-[Orchestration SDK -Java-Edition-Trusted-Device-Activation-Part2]_11

The Orchestration SDK will execute the authentication method based on the risk associated with the transaction, as directed by Risk Analytics of OneSpan Intelligent Adaptive Authentication.

Now that user account is provisioned and the trusted device is activated, we have reached the end of this series. Stay tuned for more blogs on using OneSpan's Intelligent Adaptive Authentication API. Meanwhile, if you have any questions regarding the content, feel free to reach us on the OneSpan Community Portal Forums.

OneSpan Developer Community

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today