- 18 Apr 2025
- 3 Minutes to read
- Print
- DarkLight
- PDF
Integrate app-to-app Secure Channel communication
- Updated on 18 Apr 2025
- 3 Minutes to read
- Print
- DarkLight
- PDF
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:
Generating an encrypted Secure Channel message from raw data provided to a third-party application.
Invoking the Mobile Authenticator Studio app with the Secure Channel message.
Signing the Secure Channel message in the Mobile Authenticator Studio app.
Invoking the third-party application with the Secure Channel message signature.
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=”.
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.
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=
00C1C3E40F42B823B3C20F3291C7BB5E3815E25AA4C7A4D8CB266CFA56FDA80477CEE081First 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=
00C1C3E40F42B823B3C20F3291C7BB5E3815E25AA4C7A4D8CB266CFA56FDA80477CEE081Second 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().