Integrate app-to-app Secure Channel communication
  • 18 Apr 2025
  • 3 Minutes to read
  • Dark
    Light
  • PDF

Integrate app-to-app Secure Channel communication

  • Dark
    Light
  • PDF

Article summary

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.

Integrating app-to-app- secure channel communication (Overview)

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

Data sent to third-party applications by Mobile Authenticator Studio

Parameter name

Description

PlatformName

The name of the platform, where the authenticator app is running.

SerialNumber

The authenticator serial number.

Format: Alphanumeric string of 10 characters

SequenceNumber

The sequence number of the authenticator instance/account.

Format: Alphanumeric string of 2 characters

UserIdentifier

The extra user identifier that has been set during activation.

Format: Alphanumeric string, limited to 40 characters

This parameter is only supported for activation and app-to-app signing operations with DIGIPASS Gateway but not for a regular multi-device licensing app-to-app signing operation.

Version

The version of the application binary as defined when configuring the app. Only supported for app-to-app signing.

DeviceIdentifier

The device-unique identifier. Only supported for app-to-app signing, and only on Android.

Format: String of 64 hexadecimal characters

RootingStatus

Indicates the rooting status of the device and always returns false. Only supported for app-to-app signing.

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().


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.
ESC

Ozzy, our interactive help assistant