Integrate two-step activation
- 23 Oct 2024
- 10 Minutes to read
- DarkLight
- PDF
Integrate two-step activation
- Updated on 23 Oct 2024
- 10 Minutes to read
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Mobile Authenticator Studio must be configured to use two-step activation to be able to use Secure Channel, multi-device activation (MDA), or multi-device licensing (MDL).
Integrating two-step activation requires the integration of OneSpan Authentication Server Framework 3.13.1.2 or later.
The two-step activation process consists of providing Mobile Authenticator Studio with the activation data in the following two steps:
Providing Mobile Authenticator Studio with the activation data related to the authenticator license.
The activation data related to the authenticator license is shared by all authenticators of the same user. This license activation data can be provided to Mobile Authenticator Studio through an image – QR code or Cronto image – or retrieved by Mobile Authenticator Studio by contacting an online web service.
Providing Mobile Authenticator Studio with the activation data related to the authenticator instance (i.e., the authenticator account).
The activation data related to the authenticator instance is unique for each authenticator. This activation data can be provided to Mobile Authenticator Studio through an image, QR code, or Cronto image, if the activation data of the Mobile Authenticator Studio license has been provided in the same way or retrieved by Mobile Authenticator Studio by contacting an online web service.
The usage of Cronto images requires the integration of the Image Generator SDK as of version 4.3.5.
Several scenarios are possible for activating Mobile Authenticator Studio licenses and/or instances (see Activation scenarios). For detailed information about the particular scenarios, see Activation scenarios.
License activation data from image | License activation data from web service | |
|---|---|---|
Instance activation data from image | Activation scenario 1 | Not supported |
License activation data from web service | Activation scenario 2 | Activation scenario 3 |
Activation scenarios
Activation scenario 1: License and instance activation data from image
This activation scenario succeeds on the Mobile Authenticator Studio side completely offline, and is fully compatible with the activation of OneSpan hardware authenticators.
Two-step activation – scenario 1 (overview)
Activation scenario 1 (Walkthrough)
The integrator imports the authenticator licenses and master activation applications into the database.
The integrator assigns an authenticator license to a user. If it is a multi-device licensing configuration, it can be used to generate up to 99 operational authenticator instances for a user. If it is a single-device licensing configuration, only one authenticator instance can be generated per license.
The integrator generates Activation Message 1 using the OneSpan Authentication Server Framework API method AAL2GenMessageActivation1().
The integrator generates the Cronto image using the Secure Messaging SDK Server API method generateCrontoSign().
The integrator must securely send the image containing Activation Message 1.
Activation Message 1 is highly sensitive as it contains the authenticator license. Disclosure of the authenticator license will compromise any future authenticator activation!
The user scans the Cronto image with Mobile Authenticator Studio.
The Mobile Authenticator Studio app displays the device code that identifies the platform where the license is loaded.
The user must provide the device code to the back-end server.
The integrator must validate the device code using the OneSpan Authentication Server Framework API method AAL2VerifyDeviceCode(). This API returns the platform used to activate the authenticator license (see Platforms used to activate the authenticator license).
At this step, the integrator must generate the payload key BLOB to use Secure Channel with Mobile Authenticator Studio. For more information about payload key BLOB management, refer to the OneSpan Authentication Server Framework Product Guide.
After the device code is successfully validated, the integration must generate Activation Message 2. It contains the authenticator instance activation data that uses the OneSpan Authentication Server Framework API method AAL2GenMessageActivation2().
The integrator generates the Cronto image using the Secure Messaging SDK API method generateCrontSign().
The integrator must display activation image 2 to the user.
The user must scan activation image 2 with the Mobile Authenticator Studio app.
Activation scenario 2: License activation data from image, instance activation data from web service
Activation scenario 2 succeeds offline for the license activation, and online for the instance activation. In a deployment where hardware authenticators and Mobile Authenticator Studio are combined, the image used to activate the authenticator license will be shared by both types of authenticators. However, the activation of the authenticator instance in Mobile Authenticator Studio will continue online, while for the hardware authenticator a second image will have to be scanned.
Two-step activation – scenario 2 (overview)
Activation scenario 2 (Walkthrough)
The integrator imports the authenticator licenses and master activation applications into the database.
The integrator assigns an authenticator license to a user. If it is a premium license, it can be used to generate up to 99 operational authenticator instances for a user. If it is a classic license, only one authenticator instance can be generated per license.
The integrator generates Activation Message 1 using the OneSpan Authentication Server Framework API AAL2GenMessageActivation1().
The integrator generates the Cronto image with the Secure Messaging SDK Server API method generateCrontSign().
The integrator must securely send the image containing Activation Message 1.
Activation Message 1 is highly sensitive as it contains the authenticator license. Disclosure of the authenticator license will compromise any future authenticator activation!
The user scans the Cronto image with Mobile Authenticator Studio.
The Mobile Authenticator Studio app sends the device code that identifies the platform where the license has been loaded to a web service.
The web service must validate the device code using the OneSpan Authentication Server Framework API method AAL2VerifyDeviceCode(). This API returns the platform used to activate the authenticator license (see Platforms used to activate the authenticator license).
At this step, the integrator must generate the payload key BLOB to use Secure Channel with Mobile Authenticator Studio. For more information about payload key BLOB management, refer to the OneSpan Authentication Server Framework Product Guide.
After the device code is successfully validated, the integration must generate Activation Message 2. It contains the authenticator instance activation data that uses the OneSpan Authentication Server Framework API method AAL2GenMessageActivation2().
Finally, Activation Message 2 is sent to Mobile Authenticator Studio to complete its activation.
Activation scenario 3: License and instance activation data from web service
Activation scenario 3 succeeds completely online.
Two-step activation – scenario 3 (overview)
Activation scenario 3 (Walkthrough)
The integrator imports the authenticator licenses and master activation applications into the database.
The integrator assigns an authenticator license to a user. If it is a premium license, it can be used to generate up to 99 operational authenticator instances for a user. If it is a classic license, only one authenticator instance can be generated per license.
The integrator generates credentials for the user. These credentials will be used to authenticate the Mobile Authenticator Studio request to the web services.
The generated credentials are securely sent to the user.
The user starts the Mobile Authenticator Studio activation process by entering the credentials.
The Mobile Authenticator Studio app contacts the license activation web service with the user’s credentials.
The authentication server validates the user’s credentials.
The authentication server uses the OneSpan Authentication Server Framework API method AAL2GenMessageActivation1() to generate Activation Message 1.
The authentication server sends Activation Message 1 to the Mobile Authenticator Studio app.
After processing Activation Message 1, the Mobile Authenticator Studio app calls the instance activation web service with a device code. This device code identifies the platform where the license has been loaded to a web service.
The web service must validate the device code using the OneSpan Authentication Server Framework API method AAL2VerifyDeviceCode(). This API returns the platform used to activate the Digipass license (see Platforms used to activate the authenticator license).
At this step, the integrator must generate the payload key BLOB to use Secure Channel with Mobile Authenticator Studio. For more information about payload key BLOB management, refer to the OneSpan Authentication Server Framework Product Guide.
After the device code is successfully validated, the integration must generate Activation Message 2. It contains the authenticator instance activation data that uses the OneSpan Authentication Server Framework API method AAL2GenMessageActivation2().
Finally, Activation Message 2 is sent to Mobile Authenticator Studio to complete its activation.
# | Platform | Platform type value |
|---|---|---|
0 | Digipass 760 | 00000 |
1 | Unknown software platform | 00001 |
3 | iOS | 00011 |
5 | Jailbroken iOS | 00101 |
7 | Android | 00111 |
9 | Rooted Android | 01001 |
15 | MDP2 Platform or BB Java | 01111 |
17 | Windows | 10001 |
19 | Linux | 10011 |
21 | Mac | 10101 |
23 | RFU | 10111 |
Web service integration
Authenticator license activation request
The request sent by Mobile Authenticator Studio is configured in the OnlineLicenseActivation section of the configuration file:
<LicenseActivation useActivationPassword="true"checksumOnActivationPassword="true">
<OnlineLicenseActivation inputType="image"imageFormat="all"useRegistrationIdentifier="true"useAuthorizationCode="true"checksumOnAuthorizationCode="false">
<URL method="POST"value=" http://MY_DOMAIN_NAME/MY_WEB_SERVICE">
<PayloadParameter key="action"value="licenseActivation" />
<PayloadParameter key="registrationIdentifier"value="VDS%_RegistrationIdentifier_%" />
<PayloadParameter key="authorizationCode"value="%_AuthorizationCode_%" />
<PayloadParameter key="publicKey"value="%_PublicKey_%" />
<PayloadParameter key="initialVector"value="%_InitialVector_%" />
</URL >
</OnlineLicenseActivation >
...
</LicenseActivation>
The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator Studio Customization Guide.
Parameter name | Description |
|---|---|
RegistrationIdentifier | The identifier provided by the user via the online activation screen of the Mobile Authenticator Studio app. This parameter will be used only if the useRegistrationIdentifier attribute of the OnlineLicenseActivation element is set to true. Format: Alphanumeric string, limited to 40 characters |
AuthorizationCode | The second factor to authorize authentication server for processing the provisioning request if the registration identifier is predictable. This parameter will be used only if the useAuthorizationCode attribute of the OnlineLicenseActivation element is set to true. Format: Alphanumeric string, limited to 40 characters |
PublicKey | The public key of the device key pair, used by the DSAPP library to negotiate the session key to encrypt Activation Message 1. The public key can be encrypted using the activation password. The device nonce is concatenated to the public key value. Both data sets are sent together in a string of 136 hexadecimal characters. Format: Hexadecimal string, 132 characters |
InitialVector | A randomly generated initial vector. It is used to diversify the public key encryption. Format: Hexadecimal string of 32 characters |
Version | The version of the application binary as defined when configuring the app. |
DeviceIdentifier | The device-unique identifier. Format: String of 64 hexadecimal characters |
RootingStatus | The status indicating whether the device is rooted, either true or false according to the device state. |
Authenticator license activation response
The response expected by Mobile Authenticator Studio must be formatted as described in the DTD:
<!ELEMENT DP4Mobile (LicenseActivation?)>
<!ATTLIST DP4Mobile retCode CDATA #REQUIRED>
<!ATTLIST DP4Mobile message CDATA #REQUIRED>
<!ATTLIST DP4Mobile serverTime CDATA #IMPLIED>
<!ELEMENT LicenseActivation>
<!ATTLIST LicenseActivation encryptedLicenseActivationMessage CDATA #REQUIRED>
<!ATTLIST LicenseActivation licenseActivationMessageIV CDATA #REQUIRED>
<!ATTLIST LicenseActivation encryptedServerPublicKey CDATA #REQUIRED>
<!ATTLIST LicenseActivation encryptedNonces CDATA #REQUIRED>
<!ATTLIST LicenseActivation generateSessionKeyIV CDATA #REQUIRED>
Example
<?xml version="1.0"encoding="UTF-8"?>
<DP4Mobile retCode="0"message="Operation Successful"serverTime="1271862050" >
<LicenseActivationencryptedLicenseActivationMessage ="3806564453974A59302DD7..."licenseActivationMessageIV ="5464646..."encryptedServerPublicKey ="123456..."encryptedNonces ="98752..."generateSessionKeyIV ="24421..." />
</DP4Mobile >
Attribute name | Description |
|---|---|
//DP4Mobile/@retCode | Required. The return code associated with the authenticator license activation request. 0 means success, any other value will cause the message attribute value to be displayed and the list transaction to stop. |
//DP4Mobile/@message | Required. The return message associated with the authenticator license activation request. This value will be displayed by the app if not 0. |
//DP4Mobile/@serverTime | Optional. This is the current server GMT time. This value will be used by the app to silently set the drift between device and server time to keep the app synchronized. |
//LicenseActivation /@encryptedLicenseActivationMessage | Required. The encrypted license activation message. This message will be decrypted and used to activate the license. |
//LicenseActivation /@licenseActivationMessageIV | Required. The initial vector involved in the encryption of the license activation. This message will be used to decrypt the license activation message. |
//LicenseActivation /@encryptedServerPublicKey | Required. The encrypted server public key. This key will be used during the decryption of the license activation message. |
//LicenseActivation /@encryptedNonces | Required. The encrypted nonces. This attribute will be used during the decryption of the license activation message. |
//LicenseActivation /@generateSessionKeyIV | Required. The session key IV. This attribute will be used during the decryption of the license activation message. |
Authenticator instance activation request
The request sent by Mobile Authenticator Studio is configured in the OnlineInstanceActivation section of the configuration file:
<InstanceActivation>
<OnlineInstanceActivation>
<URL method="POST"value="http:// http://MY_DOMAIN_NAME/MY_WEB_SERVICE">
<PayloadParameter key="serialNumber"value="%_SerialNumber_%" />
<PayloadParameter key="deviceCode"value="%_DeviceCode_%" />
</URL >
</OnlineInstanceActivation>
...
</InstanceActivation>
The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator Studio Customization Guide.
Authenticator instance activation response
The response expected by Mobile Authenticator Studio must be formatted as described in the DTD:
<!ELEMENT DP4Mobile (InstanceActivation?)>
<!ATTLIST DP4Mobile retCode CDATA #REQUIRED>
<!ATTLIST DP4Mobile message CDATA #REQUIRED>
<!ATTLIST DP4Mobile serverTime CDATA #IMPLIED>
<!ELEMENT InstanceActivation>
<!ATTLIST InstanceActivation instanceActivationMessage CDATA #REQUIRED>
<!ATTLIST InstanceActivation challenge CDATA #IMPLIED>
Example
<?xml version="1.0"encoding="UTF-8"?>
<DP4Mobile retCode="0"message="Operation Successful"serverTime="1271862050" >
<InstanceActivationinstanceActivationMessage="65464646..." />
</DP4Mobile >
Attribute name | Description |
|---|---|
//DP4Mobile/@retCode | Required. The return code associated with the authenticator license activation request. 0 means success, any other value will cause the message attribute value to be displayed and the list transaction to stop. |
//DP4Mobile/@message | Required. The return message associated with the authenticator license activation request. This value will be displayed by the app if not 0. |
//DP4Mobile/@serverTime | Optional. This is the current server GMT time. This value will be used by the app to silently set the drift between device and server time to keep the app synchronized. |
//InstanceActivation /@instanceActivationMessage | Optional. The instance activation message. This will be used to activate the instance. |
Was this article helpful?