Integration of user registration and authenticator activation using orchestration

Before the user can use Intelligent Adaptive Authentication, they must complete the registration process and activate their authenticator. Once the device is activated, it can be used for login, event, and transaction data signing operations.

User registration and authenticator activation

Prerequisites for the registration operation

  • The mobile application must be integrated with the Orchestration SDK.
  • (Optional) Define a static password for users.
Registration and Activation Flow

Registration and activation flow

Sequence of a registration and activation flow

  1. The user starts the registration process via the User Registration serviceClosed The User Registration service handles the JSON posts to register the users of your web and mobile applications, and starts the activation process. on the client web application. The user enters a user ID and, optionally, a static password to start the registration operation. The web server then forwards the request to the OneSpan Trusted Identity platform API with a call to the POST /users/register endpoint.

    The use of a static password is optional during the registration process. If no static password is entered, the OneSpan Trusted Identity platform (TID) generates a temporary random password only used for this operation.

  2. The Risk Management component verifies the CDDC data retrieved from the web form.
  3. The TID user account is created after the Risk Management component has accepted the user registration.
  4. An unassigned authenticator license is assigned to the newly created account.
  5. With this, the user is registered and an activation password is sent to the web application.

    The status of the registration can be checked anytime with a call to the POST /registrations/check-status endpoint.

    The serial number returned by userregister may not necessarily match the serial number of the authenticator sent in the request to the TID web service.

  6. The client application forwards this activation password to the user. The user either scans the QR code from the web application or manually enters the activation password on the mobile application.

    The returned activation password is time-limited (10 minutes). When the user tries to enter the activation password after this time, the authenticator activation fails.

  7. The Orchestration SDK starts the activation of the device. For this, the Orchestration SDK must establish a secure communication tunnel with the Provisioning service.
  8. The Orchestration SDK exchanges multiple activation calls to the Provisioning service to gather the necessary activation data. The Orchestration SDK sends requests to the Provisioning service, and the Provisioning service returns orchestration responses to the Orchestration SDK.
    For more detailed information about the activation and the orchestration calls, refer to Features of the Orchestration SDK: Activation.

To integrate the registration flow

  • Issue a registration request with the POST /users/register endpoint:

    • Payload:

      • objectType: "AdaptiveRegisterUserInput"

      • cddc:

        • browserCDDC

          • fingerprintRaw
          • fingerprintHash
      • clientIP
      • relationshipRef
      • (Optional) staticPassword
      • sessionID
      • userID

Activation status check

Two methods are available to poll the activation status following the register request—synchronous or asynchronous activation.

Synchronous activation—check status

Register and synchronous activation

The client application sends the check-status request that is processed after register only once.

The user application server invokes the POST /registrations/check-status endpoint with the following data:

  • { "login": " SomeUserID ", "timeoutSeconds": 60 }

    This statement waits for the activation to start. If the user activates the authenticator in 30 seconds, the customer web application will receive the activated response after 30 seconds. If the user does not activate the authenticator within the timeout parameter (60 seconds in this example), the Check Status service will return the following status:

  • { "activationStatus": "timeout" }

    The customer web application can then decide to retry with a timeout. In this scenario you should retry later without a timeout and restart the activation process. If the user does not activate the authenticator within the session expiration time (10 minutes), the Check Status service will return the following status:

  • { "activationStatus": "unknown" }

Asynchronous activation—check status

Register and asynchronous activation

The client application pools at a certain interval to get the last status information via the POST /registrations/check-status endpoint, with the following data:

  • { "login": "SomeUserID" }

    When the activation is still pending, the Check Status service will return the following status:

  • { "activationStatus": "pending" }

    When the activation is successful, the Check Status service will return the following status:

  • { "activationStatus": "activated" }

    As soon as this is the case, the pending activation status is reset and the Check Status service will return the following status:

  • { "activationStatus": "unknown" }

User deregistration and removal of the authenticator assignment

Sequence of a user deregistration and removal of the authenticator assignment

  1. The user starts the deregistration process. The web server forwards the request to the OneSpan Trusted Identity platform API with a call to the POST /users/{userID@domain}/unregister endpoint.
  2. The OneSpan Trusted Identity platform API communicates with the Provisioning service to unassign the authenticator license.
  3. The TID user is deleted from the OneSpan Trusted Identity platform.
  4. The OneSpan Trusted Identity platform API verifies the deregister event data with the Risk Management component.

To deregister the OneSpan Trusted Identity platform user account

  • Issue a deregistration request with the POST /users/{userID@domain}/unregister endpoint:

    • Payload:

      • objectType: "AdaptiveUnregisterUserInput"

      • cddc:

        • browserCDDC

          • fingerprintRaw
          • fingerprintHash
      • clientIP
      • relationshipRef
      • sessionID

Next Steps

The next step for a full integration of Intelligent Adaptive Authentication is the Integration of User Login and Event Validation via Notification.