Features of the Orchestration SDK

With the activation feature of the Orchestration SDK you can provision authenticator instances to the Customer Mobile Application by securely exchanging activation data with OneSpan Trusted Identity platform. The activation process is initiated on the Customer Website, and then continued and completed using the Customer Mobile Application. Four network requests are required between the Customer Mobile Application and the Customer Application Server to complete the activation process.

The activation process will provision two authenticator instances in the Customer Mobile Application. For security reasons, each authenticator instance will be linked to a given authentication method: one instance for the password authentication method and another for the other authentication methods (No password and biometric recognition).

For more details concerning the authentication methods, see Authentication methods.

Activation workflow

Activation workflow of OneSpan Orchestration SDK

1. The user initializes an activation session via the Customer Website, by providing their user identifier and static password.
2. The Customer Website transmits the user identifier and the static password to the Customer Application Server.
3. The Customer Application Server calls the https://{tenant}.{environment}.tid.onespan.cloud/v1/users/register endpoint from the OneSpan Trusted Identity platform API by providing their user identifier and the static password. In case of success, the web service returns the activation password.
4. The Customer Application Server notifies the Customer Website that registration has been completed.
5. The Customer Application Server transmits the activation password to the user via a channel other than the network (e.g. by sending an SMS message or an e-mail). The activation password remains valid for 10 minutes.
6. The user enters their user identifier and the activation password in the Customer Mobile Application to start the activation process.
7. The Customer Mobile Application calls the startActivation method of the Orchestration SDK to start the activation process.
8. The Orchestration SDK displays a virtual keypad or calls the password user authentication flow, where the user can define their password, and confirm it.
9. The Orchestration SDK builds the first orchestration command required for the activation process and transmits it to the Customer Mobile Application using the onActivationStepComplete method.
10. The Customer Mobile Application transmits the orchestration command to the Customer Application Server.
11. The Customer Application Server calls the orchestration-commands Web service of the OneSpan Trusted Identity platform by providing the orchestration command. A new orchestration command is returned as a result.
12. The Customer Application Server transmits the orchestration command to the Customer Mobile Application as a response to the previous request.
13. The Customer Mobile Application calls the execute method of the Orchestration SDK to continue the activation process.
14. A second activation step repeats steps 9 to 13.
15. A third activation step repeats steps 9 to 13.
16. A fourth activation step repeats steps 9 to 13.
17. The Orchestration SDK finalises the activation process and transmits the status to the Customer Mobile Application using the onActivationSuccess method.
18. The Customer Mobile Application notifies the user that the activation has been successfully completed.

Notification registration is required to finalize activation.

After a successful activation process, the Customer Mobile Application can use the other features of the Orchestration SDK (e.g. authentication, notification registration etc.).

See Activation for more information how to integrate this feature.

To be able to use push notification messages for remote authentication and remote transactions, the Customer Mobile Application must complete a notification registration process.

Notification registration consists in obtaining a notification identifier from the Push Notification Service, and in transmitting it to the OneSpan Trusted Identity platform via a dedicated orchestration command. The notification identifier is unique per device and per app.

For more information, refer to the Notification SDK Integration Guide at Mobile Security Suite Integration Guides.

The notification registration process can only be completed if the Customer Mobile Application has been activated (see Activation); this process must take place after a successful activation (mandatory for finalizing the activation flow on the server-side) and at application startup (only if the notification identifier has changed).

Notification registration is mandatory for finalizing the activation process on the server-side.

Notification registration workflow illustrates the notification registration workflow.

1. The Customer Mobile Application calls the registerNotificationService method of the Notification SDK to obtain a notification identifier.
2. The Notification SDK contacts the Push Notification Service to obtain a notification identifier.
3. The Notification SDK returns to the Customer Mobile Application a OneSpan Notification Identifier, which is an abstraction of the previously retrieved notification identifier.
4. The Customer Mobile Application calls the startNotificationRegistration method of the Orchestration SDK to start the notification registration process.
5. The Orchestration SDK builds an orchestration command which includes the OneSpan Notification Identifier and transmits it to the Mobile Application Server using the onNotificationRegistrationComplete method.
6. The Customer Mobile Application transmits the orchestration command to the Customer Application Server.
7. The Customer Application Server calls the orchestration-commands Web service of the OneSpan Trusted Identity platform by providing the orchestration command. A new orchestration command is returned as a result.
8. The Customer Application Server transmits the orchestration command to the Customer Mobile Application as a response to the previous request.
9. The Customer Mobile Application calls the execute method of the Orchestration SDK to finalize the notification registration process.
10. The Orchestration SDK calls the onNotificationRegistrationSuccess method to notify the Customer Mobile Application.

After a successful notification registration process, the OneSpan Trusted Identity platform is able to send push notification messages to the Customer Mobile Application.

The Customer Mobile Application must integrate the other methods of the Notification SDK to properly receive and process the push notification messages sent by the OneSpan Trusted Identity platform.

For more information about integrating this feature, see Notification registration.

With the remote authentication feature of the Orchestration SDK, the user can authenticate to the Customer Website using the Customer Mobile Application, via an authentication request initiated on the OneSpan Trusted Identity platform, and based on the corresponding risk evaluation.

The remote authentication process is initiated using the Customer Website and evaluated for risk by OneSpan Trusted Identity platform before continuing with the Customer Mobile Application.

The authentication request is embedded in an orchestration command and can be transmitted via a push notification message initiated by OneSpan Trusted Identity platform or by another communication channel handled by the Customer Website (e.g. image scanning).

The authentication request contains the following parameters:

• A session identifier created by the Customer Application Server, which uniquely identifies the authentication session.
• A request identifier created by the Customer Application Server, which uniquely identifies the authentication request.
• An authentication method, which defines how the user must authenticate to sign the authentication request (see Authentication methods).

• (OPTIONAL) Data to display on the Customer Mobile Application to provide authentication request information to the user; the user can choose to approve or reject it.

  The data to display is a string defined by the Customer Application Server, which must be interpreted by the Customer Mobile Application.

Remote authentication workflow illustrates the remote authentication workflow with the transmission of the authentication request via a push notification message.

Remote authentication workflow

1. The user initializes an authentication request via the Customer Website (e.g. for login purposes), providing their user identifier.
2. The Customer Website transmits the user identifier and the Client Device Data Collector (CDDC) browser data to the Customer Application Server.
3. The Customer Application Server calls the https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/login endpoint from the OneSpan Trusted Identity platform API by providing their user identifier, a session identifier (dynamically generated and uniquely identifying the authentication request), the received CDDC browser data, and, optionally, the data to display on the Customer Mobile Application.

4. The OneSpan Trusted Identity platform evaluates the risk related to the Web browser used for the authentication request (based on multiple parameters provided in the previous step and on existing parameters related to the user, e.g. unknown country) and, in case of risk detection, initiates a step-up authentication request on the Customer Mobile Application with a given authentication method (see Authentication methods).

   Depending on the configuration defined in the OneSpan Trusted Identity platform, multiple scenarios are possible:

   • The authentication request can be transmitted via a push notification message initiated by the OneSpan Trusted Identity platform and sent by the Push Notification Service to the Customer Mobile Application. In this case, a push notification message is sent to all mobile devices of the user where the Customer Mobile Application is installed and activated.
   • The authentication request can be transmitted by the Customer Application Server via a different channel (e.g. display a Cronto image containing the orchestration command related to the authentication request and scan it with the Customer Mobile Application).
   • The authentication request can be blocking or non-blocking.

   The following steps describe a blocking scenario with the authentication request transmitted via push notification.

5. The Push Notification Service sends a push notification message containing the orchestration command related to the authentication request to the Customer Mobile Application.
6. The Customer Mobile Application obtains the orchestration command contained in the push notification message and calls the execute method of the Orchestration SDK to perform the remote authentication.
7. The Orchestration SDK builds an orchestration command and transmits it to the Customer Mobile Application using the onRemoteAuthenticationStepComplete method.
8. The Customer Mobile Application transmits the orchestration command to the Customer Application Server.
9. The Customer Application Server calls the orchestration-commands Web service of the OneSpan Trusted Identity platform by providing the orchestration command. A new orchestration command is returned as a result.
10. The Customer Application Server transmits the orchestration command to the Customer Mobile Application as a response to the previous request.
11. The Customer Mobile Application calls the execute method of the Orchestration SDK to continue the remote authentication process (only if the authentication request is still pending).
12. The Orchestration SDK calls the onRemoteAuthenticationDisplayData method to transmit the data to display to the Customer Mobile Application (if data has been defined in step 3).
13. The Customer Mobile Application displays a screen to the user containing the data to display and two buttons to approve or reject the authentication request.
14. The user must approve or reject the authentication request, according to the displayed data.
15. Based on the user’s decision in the previous step, the Customer Mobile Application calls the onDataApproved or onDataRejected method of the Orchestration SDK.
16. In both cases, the Orchestration SDK prompts the user to authenticate by using an authentication method defined by the OneSpan Trusted Identity platform, based on the evaluated risk (see step 4).
17. The Orchestration SDK signs the authentication request, builds an orchestration command, and transmits it to the Customer Mobile Application using the onRemoteAuthenticationStepComplete method.
18. Repeat steps 8 to 11.
19. In case of validation by the OneSpan Trusted Identity platform, the Orchestration SDK calls the onRemoteAuthenticationSuccess method to notify the Customer Mobile Application.
20. The Customer Mobile Application notifies the user that the authentication request has been successful and that they are about to be logged in to the Customer Website.
21. The OneSpan Trusted Identity platform provides a response to the call to the login Web service from step 3, indicating the success of the authentication request.
22. The Customer Application Server transmits the success status to the Customer Website. The user is now logged in to the Customer Website.

For more information about integrating this feature, see Remote authentication.

With the remote transaction feature of the Orchestration SDK, the user can perform a transaction to the Customer Website using the Customer Mobile Application, via a transaction request initiated on OneSpan Trusted Identity platform, and based on the corresponding risk evaluation.

The remote transaction process is initiated using the Customer Website and evaluated for risk by the OneSpan Trusted Identity platform before continuing with the Customer Mobile Application.

The transaction request is embedded in an orchestration command and can be transmitted via a push notification message initiated by the OneSpan Trusted Identity platform or by another communication channel handled by the Customer Website (e.g. image scanning).

The authentication request contains the following parameters:

• A session identifier created by the Customer Application Server, which uniquely identifies the transaction session.
• A request identifier created by the Customer Application Server, which uniquely identifies the transaction request.
• An authentication method, which defines how the user must authenticate to be able to sign the transaction request (see Authentication methods).

• Data to display on the Customer Mobile Application to provide transaction request information to the user; the user can choose to approve or reject it.

  The data to display is a string defined by the Customer Application Server, which must be interpreted by the Customer Mobile Application.

Remote transaction workflow illustrates the remote transaction workflow with the transmission of the transaction request via a push notification message.

Remote transaction workflow

Remote transaction workflow

1. The user initializes a transaction request via the Customer Website (e.g. for money transfer purposes), providing their user identifier and the transaction data.
2. The Customer Website transmits the user identifier and the Client Device Data Collector (CDDC) browser data to the Customer Application Server.
3. The Customer Application Server calls the https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userID@domain}/transactions/validate endpoint from the OneSpan Trusted Identity platform API by providing their user identifier, a session identifier (dynamically generated and uniquely identifying the authentication request), the received CDDC browser data, and the data to display on the Customer Mobile Application.

4. The OneSpan Trusted Identity platform evaluates the risk related to the Web browser used for the transaction request (based on multiple parameters provided in the previous step and on existing parameters related to the user, e.g. amount too high) and, in case of risk detection, initiates a step-up transaction request on the Customer Mobile Application with a given authentication method (see Authentication methods).

   Depending on the configuration defined in the OneSpan Trusted Identity platform, multiple scenarios are possible:

   • The transaction request can be transmitted via a push notification message initiated by the OneSpan Trusted Identity platform and sent by the Push Notification Service to the Customer Mobile Application. In this case, a push notification message is sent to all mobile devices of the user where the Customer Mobile Application is installed and activated.
   • The transaction request can be transmitted by the Customer Application Server via a different channel (e.g. display a Cronto image containing the orchestration command related to the transaction request and scan it with the Customer Mobile Application).
   • The transaction request can be blocking or non-blocking.

   The following steps describe a blocking scenario with the transaction request transmitted via push notification.

5. The Push Notification Service sends a push notification message containing the orchestration command related to the transaction request to the Customer Mobile Application.
6. The Customer Mobile Application obtains the orchestration command contained in the push notification message and calls the execute method of the Orchestration SDK to perform the remote authentication.
7. The Orchestration SDK builds an orchestration command and transmits it to the Customer Mobile Application using the onRemoteTransactionStepComplete method.
8. The Customer Mobile Application transmits the orchestration command to the Customer Application Server.
9. The Customer Application Server calls the orchestration-commands Web service of the OneSpan Trusted Identity platform by providing the orchestration command. A new orchestration command is returned as a result.
10. The Customer Application Server transmits the orchestration command to the Customer Mobile Application as a response to the previous request.
11. The Customer Mobile Application calls the execute method of the Orchestration SDK to continue the remote transaction process (only if the transaction request is still pending).
12. The Orchestration SDK calls the onRemoteTransactionDisplayData method to transmit the data to display to the Customer Mobile Application.
13. The Customer Mobile Application displays a screen to the user containing the data to display and two buttons to approve or reject the transaction request.
14. The user must approve or reject the transaction request, according to the displayed data.
15. Based on the user’s decision in the previous step, the Customer Mobile Application calls the onDataApproved or onDataRejected method of the Orchestration SDK.
16. In both cases, the Orchestration SDK prompts the user to authenticate by using an authentication method defined by the OneSpan Trusted Identity platform, based on the evaluated risk (see step 4).
17. The Orchestration SDK signs the transaction request, builds an orchestration command, and transmits it to the Customer Mobile Application using the onRemoteTransactionStepComplete method.
18. Repeat steps 8 to 11.
19. In case of validation by the OneSpan Trusted Identity platform, the Orchestration SDK calls the onRemoteTransactionSuccess method to notify the Customer Mobile Application.
20. The Customer Mobile Application notifies the user that the transaction request has been validated.
21. The OneSpan Trusted Identity platform provides a response to the call to the transactions/validate Web service from step 3, indicating the success of the transaction request.
22. The Customer Application Server transmits the success status to the Customer Website. The user is informed that the transaction has been validated on the Customer Website.

For more information about integrating this feature, see Remote transaction.

With the local authentication feature of the OneSpan Orchestration SDK, the user can authenticate to the Customer Website using a one-time password (OTP) generated via the Customer Mobile Application. The OTP can be transmitted manually by the user, or remotely by the Customer Mobile Application. An authentication method must be defined to authenticate the user before the OTP is generated. See Authentication methods for more information.

Local authentication workflow illustrates the local authentication workflow with a manual transmission of the OTP.

1. The user initializes an authentication request via the Customer Mobile Application (e.g. for login purposes), providing their user identifier.

2. The Customer Mobile Application calls the startLocalAuthentication method of the Orchestration SDK to perform the local authentication with a given authentication method (see Authentication methods for more information).

3. The Orchestration SDK prompts the user to authenticate by using an authentication method defined by the Customer Mobile Application.

4. In case of successful user authentication, the Orchestration SDK generates a one-time password (OTP), and transmits it to the Customer Mobile Application using the onLocalAuthenticationSuccess method.

5. The Customer Mobile Application displays the OTP to the user.
6. The user initializes an authentication request via the Customer Website (e.g. for login purposes), by providing their user identifier and the generated OTP. This request is transmitted to the Customer Application Server.
7. The Customer Application Server calls the login method of the OneSpan Trusted Identity platform to verify the OTP.
8. The Customer Application Server provides a response to the Customer Website by indicating the success of the authentication request.
9. The user is logged in to the Customer Website.

For more information about integrating this feature, see Local authentication.

With the local transaction feature of the OneSpan Orchestration SDK, the user can do a transaction to the Customer Website using a signature generated via the Customer Mobile Application. The signature can be transmitted manually by the user or remotely by the Customer Mobile Application. An authentication method must be defined to authenticate the user before the signature is generated. See Authentication methods for more information.

Local transaction workflow illustrates the local transaction workflow with a manual transmission of the signature.

Local transaction workflow

Local transaction workflow

New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on LocalTransactionDelegate for this workflow.

1. The user initializes a transaction request via the Customer Mobile Application (e.g. for login purposes), providing their user identifier and the transaction data.
2. The Customer Mobile Application calls the startLocalTransaction method of the Orchestration SDK to perform the local authentication with a given authentication method (see Authentication methods for more information).
3. The Orchestration SDK prompts the user to authenticate, using an authentication method defined by the Customer Mobile Application.
4. In case of successful user authentication, the Orchestration SDK generates a signature and transmits it to the Customer Mobile Application using the onLocalTransactionSuccess method.
5. The Customer Mobile Application displays the signature to the user.
6. The user initializes a transaction request via the Customer Website (e.g. for money transfer purposes) by providing their user identifier, the transaction data, and the generated signature. This request is transmitted to the Customer Application Server.
7. The Customer Application Server calls the transactions/validate method of the OneSpan Trusted Identity platform to verify the signature of the transaction request.
8. The Customer Application Server provides a response to the Customer Website, indicating the success of the transaction request.
9. The user is informed that the transaction has been validated on the Customer Website.

For more information about integrating this feature, see Local transaction.

User authentication requested by the Orchestration SDK can take place using one of the following methods:

• No password
• Password
• Biometric recognition

In case of remote authentication or remote transaction the authentication method is dynamically defined by the OneSpan Trusted Identity platform after risk evaluation. In case of local authentication or transaction, the Customer Mobile Application must define the authentication method.

If the requested authentication method is not supported by the mobile device (e.g. biometric recognition requested but no biometric sensor on the device), the Orchestration SDK will fall back to authentication with password.

No password

If the authentication method is No password, no user action is required for the completion of the process.

Password

If the authentication method is password, the Orchestration SDK displays a virtual keypad or call the password user authentication flow, and the user needs to enter their password.

The texts displayed in the dialog and other graphical elements (i.e. text, colors, icons) are customizable. For more information, see Integrating the Orchestration SDK.

Biometric

If the authentication method is biometric recognition, the Orchestration SDK displays a dialog prompting the biometric scanner of the device. The Fallback button provided by the Biometric Sensor SDK is not available in the biometric dialog.

The texts displayed in the dialog are customizable. All other graphical elements (i.e. text, colors, icons) cannot be customized. For more information, see Integrating the Orchestration SDK.

The Orchestration SDK provides facilities for the user to change their password. The password was defined during the activation process.

The Orchestration SDK displays a virtual keypad or calls the password user authentication flow, where the user can enter the old password, and then define and confirm the new password. If an external user authentication by password has been configured the “User Authentication Flow” will be called.

A network request is required to check whether the entered old password is valid: an OTP is generated with the old password and validated on the Customer Application Server.

Change password workflow illustrates the change password workflow.

Change password workflow

New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on ChangePasswordDelegate for this workflow.

1. The user initiates the change password process using the Customer Mobile Application.
2. The Customer Mobile Application calls the startChangePassword method of the Orchestration SDK to change the user’s password.
3. The Orchestration SDK displays the virtual keypad or calls the password user authentication flow, where the user can enter their old password.
4. The Orchestration SDK generates a one-time password (OTP) with the old password, builds an orchestration command, and transmits it to the Customer Mobile Application using the onChangePasswordStepComplete method.
5. The Customer Mobile Application transmits the orchestration command to the Customer Application Server.
6. The Customer Application Server calls the orchestration-commands Web service of the OneSpan Trusted Identity platform by providing the orchestration command. A new orchestration command is returned as a result.
7. The Customer Application Server transmits the orchestration command to the Customer Mobile Application as a response to the previous request.
8. The Customer Mobile Application calls the execute method of the Orchestration SDK to continue the change password process (only if the OTP validation succeeded).
9. In case of successful user authentication, the Orchestration SDK displays the virtual keypad or calls the password user authentication flow, where the user can enter their new password.
10. If the password is not weak, the Orchestration SDK displays the virtual keypad or calls the password user authentication flow, where the user can confirm their new password.
11. The Orchestration SDK calls the onChangePasswordSuccess method to notify the Customer Mobile Application of the changed password.
12. The Customer Mobile Application notifies the user that the password has been successfully changed.

For more information about integrating this feature, see Change password.

The orchestration commands sent by the Orchestration SDK contain device data collected periodically.

This data is used for risk evaluation in the OneSpan Trusted Identity platform and protected via the Secure Channel feature to ensure confidentiality, integrity, and non-repudiation.

Collection of device data is started automatically when the Orchestration SDK is initialized, with the following default collection parameters:

• Refresh interval: 60 seconds
• Collection enabled for geolocation, Bluetooth, and Wi-Fi

Special permissions may be required (see Integrating the Orchestration SDK).

Data that cannot be collected automatically must be populated during the integration. For more information about integrating this feature, see Device data collection.

The Orchestration SDK provides facilities to activate multiple users in the Customer Mobile Application. To achieve this, each activation process must use its own user identifier.

Each user has their own password; the password is not shared by all users.

Notification registration must be performed for each activated user.

The Orchestration SDK provides methods to check whether a user is activated, to obtain user information, and to delete a user.

For more information about integrating this feature, see Multi-user management.