Integrate app-to-app Secure Channel communication

The Secure Channel feature can only be integrated in the context of an integration of Mobile Authenticator Studio in multi-device licensing mode.

Overview

The app-to-app Secure Channel communication consists of:

1. Generating an encrypted Secure Channel message from raw data provided to a third-party application.

2. Invoking the Mobile Authenticator Studio app with the Secure Channel message.

3. Signing the Secure Channel message in the Mobile Authenticator Studio app.

4. Invoking the third-party application with the Secure Channel message signature.

5. Validating the message signature to acknowledge the transfer.

The integration of app-to-app Secure Channel communication mandatorily requires the integration of OneSpan Authentication Server Framework 3.13.1.2 or later and Secure Messaging SDK 4.3.5 or later.

App-to-app secure channel communication (Overview)

Secure Channel message

The generation of a Secure Channel message body from raw data relies on the transaction message body version 2 generation functionality of the Secure Messaging SDK (as of version 4.3.5). The content of the message can be formatted in three different formats:

• A list of keys and values to display transaction content.

• A challenge for a Challenge/Response operation.

• Free text.

Each format is associated with a dedicated API function to facilitate integration:

• generateSignatureTransactionMessageBodyV2()

• generateChallengeTransactionMessageBodyV2()

• generateFreeTextMessageBodyV2()

The output of this API call must be used as the input for the OneSpan Authentication Server Framework function AAL2GenMessageRequest().

Callback URLs

Mobile Authenticator Studio must be invoked from a URL that has the following format:

${scheme}://app2app_secure_channel?x-success=thirdpartyapp://...&x-error=thirdpartyapp://...&x-cancel=thirdpartyapp://...&secure_message=0000C3E40F4...

where:

• ${scheme} is a string specified in the course of the Mobile Authenticator Studio app customization according to iOS and Android scheme policies.

• x-success is the callback URL invoked by Mobile Authenticator Studio in case of success. Once the message signature is generated, the x-success URL is called with the signature value: thirdpartyapp://...?OTP=%_OTP_%.

• x-error is the callback URL invoked by Mobile Authenticator Studio in case of error. The error code is concatenated to this URL with the key: “ErrorCode=”.

  Possible error codes
  Error code	Description
  1	Internal error
  2	Integration error. The Mobile Authenticator Studio configuration does not support app-to-app Secure Channel communication.
  3	The device is rooted and the root policy has been set to Block in the configuration.
  4	The Mobile Authenticator Studio app is not activated.
  5	The Secure Channel message is invalid.
  6	The authenticator serial number targeted by the Secure Channel message is not activated in this Mobile Authenticator Studio app.
  7	The Secure Channel message is corrupted.
  8	The Mobile Authenticator Studio app is blocked, the maximum number of wrong PIN entry attempts has been reached and the reset policy has been applied.

• x-cancel is the callback URL invoked by Mobile Authenticator Studio in case of process interruption by the user.

• secure_message is the Secure Channel string provided by OneSpan Authentication Server Framework.

Data sent to third-party applications

Along with the Secure Channel message signature, Mobile Authenticator Studio can send additional data to the third-party application, if the appropriate mask is set in the callback URL (see Data sent to third-party applications by Mobile Authenticator Studio).

Each callback URL must be encoded twice according to the encoding rules as specified by W3Schools - see W3Schools HTML URL Encoding Reference.

1. Original URL:

   dpnopin://app2app_secure_channel?x-success=
   http://10.10.10.10:8080/TestServer/test.jsp?action=success&signature
   =%_OTP_%&x-error=http://10.10.10.10:8080/TestServer/test.jsp?action
   =error&x-cancel=http:// 10.10.10.10:8080/TestServer/test.jsp?action=
   cancel&secure_message=
   00C1C3E40F42B823B3C20F3291C7BB5E3815E25AA4C7A4D8CB266CFA56FDA80477CEE081

2. First Encoding:

   dpnopin://app2app_secure_channel?x-success=
   http%3A%2F%2F10.10.10.10%3A8080%2FTestServer%2Ftest.jsp%3Faction%3Dsuccess%26signature%3D%25_OTP_%25&x-error=
   http%3A%2F%2F10.10.10.10%3A8080%2FTestServer%2Ftest.jsp%3Faction%3Derror&x-cancel=
   http%3A%2F%2F10.10.10.10%3A8080%2FTestServer%2Ftest.jsp%3Faction%3Dcancel&secure_message=
   00C1C3E40F42B823B3C20F3291C7BB5E3815E25AA4C7A4D8CB266CFA56FDA80477CEE081

3. Second Encoding:

   dpnopin://app2app_secure_channel?x-success=
   http%253A%252F%252F10.10.10.10%253A8080%252FTestServer%252Ftest.jsp%253F
   action%253Dsuccess%2526signature%253D%2525_OTP_%2525&x-error=
   http%253A%252F%252F10.10.10.10%253A8080%252FTestServer%252Ftest.jsp%253F
   action%253Derror&x-cancel=
   http%253A%252F%252F10.10.10.10%253A8080%252FTestServer%252Ftest.jsp%253F
   action%253Dcancel&secure_message=
   00C1C3E40F42B823B3C20F3291C7BB5E3815E25AA4C7A4D8CB266CFA56FDA80477CEE081

To prevent any compromising of the callback URL, they are check against a URL white list defined in the Mobile Authenticator Studio configuration file. For more information about defining the authorized URL list, refer to the Mobile Authenticator Studio Customization Guide.

The signature of the transaction message generated by Mobile Authenticator Studio can be validated using the OneSpan Authentication Server Framework API method AAL2VerifyMessageSignature().