Integration of Provisioning for Multi-Device Licensing Authenticators

OneSpan Cloud Authentication supports offline and online provisioning to activate a multi-device licensing (MDL) authenticator.

Offline MDL authenticator provisioning

For offline MDL authenticator provisioning, the integration method depends on whether Activation Message 1 (generated by OneSpan Cloud Authentication) and the device code (generated on the client side) are generated before the registration session or as part of it.

Prerequisites

Before you integrate offline MDL authenticator provisioning, ensure that the following prerequisites are met:

• The user account is created (via the PUT /users/{userID@domain} endpoint)

• A static user password is set

• An MDL authenticator license is assigned to the user (via the POST /users/{userID@domain}/assign endpoint)

To integrate offline MDL authenticator provisioning when the device code has already been generated

1. (OneSpan Cloud Authentication) Generate Activation Message 1 via the POST /authenticators/{serialNumber}/generate-activation-message endpoint from the response.

2. (Optional) (OneSpan Cloud Authentication) If required, generate a Cronto message from the activation message via the GET /visualcodes/render endpoint.

3. (Client) Based on the received activation message, activate the MDL license and generate the device code.

4. (OneSpan Cloud Authentication) Initiate a registration session via the POST /registrations endpoint. The following input fields and field values are mandatory:

   • activationType: offlineMDL

   • userID

   • staticPassword

   • deviceCode

   Retrieve registrationID and activationMessage2 from the response.

5. (Optional) (OneSpan Cloud Authentication) If required, generate a Cronto message from Activation Message 2 via the GET /visualcodes/render endpoint.

6. (Client) Based on the received Activation Message 2, activate the MDL instance and generate a signature.

7. (OneSpan Cloud Authentication) Activate the authenticator instance via the POST /registrations/{registrationID}/activate endpoint. The following input is mandatory:

   • signature

To integrate offline MDL authenticator provisioning with device code generation during the registration session

1. (OneSpan Cloud Authentication) Initiate a registration session via the POST /registrations endpoint. The following input fields and field values are mandatory:

   • activationType: offlineMDL

   • userID

   • staticPassword

   Retrieve registrationID and activationMessage from the response.

2. (Optional) (OneSpan Cloud Authentication) If required, generate a Cronto message from the activation message via the GET /visualcodes/render endpoint.

3. (Client) Based on the received activation message, activate the MDL license and generate the device code.

4. (OneSpan Cloud Authentication) Confirm the activation of the license via the POST ​/registrations​/{registrationID}​/add-device endpoint. The following input field is mandatory:

   • deviceCode

   Retrieve activationMessage2 from the response.

5. (Optional) (OneSpan Cloud Authentication) If required, generate a Cronto message from the activationMessage2 via the GET /visualcodes/render endpoint.

6. (Client) Based on the received Activation Message 2, activate the MDL instance and generate a signature.

7. (OneSpan Cloud Authentication) Activate the authenticator instance via the POST /registrations/{registrationID}/activate endpoint. The following input is mandatory:

   • signature

Online MDLauthenticator provisioning

With online MDL provisioning, the required DSAPP-SRP operations are available through the OneSpan Trusted Identity platform API. During the activation process, an authenticator instance is created.

Prerequisites

Before you integrate online MDL authenticator provisioning, ensure that the following prerequisites are met:

• An authenticator license is available

• The user account is created (via the PUT /users/{userID@domain} endpoint)

• A static user password is set

• An MDL authenticator license is assigned to the user (via the POST /users/{userID@domain}/assign endpoint)

Sequence of an online MDL authenticator provisioning flow

1. The user initiates the online provisioning process on the client web application and enters a user ID and a static password.

2. The Authentication component creates a provisioning session with the user ID and generates the activation password and the request ID.

3. The client server verifies the registration ID and the activation password and calls the Visual Code service for a Cronto image to be generated.

4. The user scans the Cronto image. This establishes the offline communication channel.

5. To secure the online communication between the mobile application and OneSpan Cloud Authentication, the mobile application generates the client ephemeral key.
   Based on the client ephemeral key, the server ephemeral key is generated via the POST /registrations/{registrationID}/generate-ephemeral-key endpoint. Mandatory input for this operation to succeed:

   • clientEphemeralKey

6. The Provisioning Service receives the client ephemeral key and returns the server ephemeral key and a salt.

7. The mobile application reads this and requests the activation message via the POST /registrations/{registrationID}/generate-activation-message endpoint.

8. The mobile application receives Activation Message 1, uses it to activate the authenticator license, and generates a device code.

9. The device code is used as input for the ​/registrations​/{registrationID}​/add-device endpoint. This endpoint adds and/or assigns the authenticator instance to the user account and generates Activation Message 2.

10. The mobile device uses Activation Message 2 to activate the authenticator instance and generates a signature to finalize the registration process via the POST /registrations/{registrationID}/activate endpoint.

To integrate the online MDL provisioning flow

1. Start the online provisioning process with a DSAPP-SRP registration via the POST /registrations endpoint.

   • Payload:

     • staticPassword

     • activationType

     • (Optional) domain

     • (Optional) serialNumber

   • Response payload:

     • activationPassword

     • registrationID

     • serialNumber

2. To secure the online communication between the mobile application and OneSpan Cloud Authentication, generate an ephemeral key (DSAPP-SRP) via the POST /registrations/{registrationID}/generate-ephemeral-key endpoint.

   • Payload:

     • clientEphemeralPublicKey

   • Response payload:

     • Salt

     • serverEphemeralPublicKey

   • Failure responses:

     • 400: The input is invalid.

     • 404: The registration session was not found.

     • 409: Incorrect activation type.

     • 500: Unexpected server error.

3. Generate the activation message via the POST /registrations/{registrationID}/generate-activation-message endpoint.

   • Payload:

     • clientEvidenceMessage

   • Response payload:

     • activationMessage.encryptedData

     • activationMessage.encryptionCounter

     • activationMessage.MAC

     • serverEvidenceMessage

   • Failure responses:

     • 400: The input is invalid.

     • 404: The registration session was not found.

     • 409: Incorrect activation type or authenticator does not support activation.

     • 500: Unexpected server error.

4. Add an MDL device via the POST /registrations/{registrationID}/add-device endpoint.

   • Payload:

     • deviceCode

   • Response payload:

     • activationMessage2

     • activationType

     • deviceStatus

     • deviceType

     • domain

     • registrationID

     • serialNumber

     • userID

5. Activate MDL via the POST /registrations/{registrationID}/activate endpoint.

   • Payload:

     • signature

   • Response payload:

     • userID

     • domain

     • serialNumber

6. (Optional) Update the device Push Notification Identifier (PNID) via the POST /users/{userID@domain}/authenticators/{serialNumber}/update-pnid endpoint.

   • Payload:

     • encryptedMessage

   • Failure responses:

     • 400: The input is invalid.

     • 404: The user account or authenticator was not found.

     • 409: Failed to update the PNID for the authenticator.

     • 500: Unexpected server error.