Additional activation OTP

The purpose of additional activation OTP is to help with the user authentication, or with the activation confirmation. The additional OTP can be used either in the early stages of the activation or later when the activation is created and waits for the confirmation in the PENDING_COMMIT state.

We will describe each situation in detail in the separate chapters:

1. Additional user authentication
   • Regular activation with OTP
   • Custom activation with OTP
2. Activation confirmation
   • Confirm regular activation with OTP
   • Confirm custom activation with OTP
   • Confirm activation recovery with OTP

Notes:

1. This part of the documentation describes in detail how usage of additional activation OTP changes the activation process. So, before you start, you should be familiar with actors and processes defined for the regular activation.

Additional user authentication

In this common scenario, it’s expected that the PowerAuth activation is not yet created so that the additional activation OTP can be used in the time of the activation creation as additional user authentication.

Regular activation with OTP

1. User is authenticated in Master Front-End Application and initiates the activation creation process:

   1. Master Front-End Application generates random activation OTP.
   2. Master Front-End Application then asks PowerAuth server to create an activation, with using this OTP (initActivation method, OTP validation set to ON_KEY_EXCHANGE).
   3. Master Front-End Application then displays QR code, containing an activation code.
   4. At the same time, Master Front-End Application initiates the delivery of activation OTP. It’s recommended to deliver such code via a dedicated out-of-band channel, for example, via SMS.

2. In the mobile application:

   1. The user scans QR code or retypes the activation code manually.
   2. The user waits for OTP delivery via the out-of-band channel.
   3. The user retypes OTP to the mobile application.
   4. Mobile application then initializes the activation, using activation code and OTP.

3. Intermediate Server Application receives activation with activation code and OTP:

   1. The activation code and OTP are verified by the PowerAuth server in the prepareActivation method.
   2. If the method call succeeds, the activation is set to the ACTIVE state. There’s no need to wait for the confirmation.
   3. In case that received OTP is wrong, the user has a limited number of retry attempts. The activation will be removed after too many failures.

4. The mobile application receives the response from the server and completes the activation on the mobile side.

Custom activation with OTP

There are multiple ways how to implement custom activation with an additional authentication OTP so that we will discuss only one particular case. What they have all common and what you need to know is that OTP is, in this case, not verified by PowerAuth Server. It’s more practical to validate it before the actual activation creation.

1. Let’s say that the user is authenticated in Master Front-End Application (with username and password) and initiates the activation creation process:

   1. Master Front-End Application generates random activation OTP and keeps it temporarily in the database.
   2. At the same time, Master Front-End Application initiates the delivery of activation OTP. It’s recommended to deliver such code via a dedicated out-of-band channel, for example, via SMS.
   3. Master Front-End Application instructs the user to start the mobile application and type the username, password, and OTP to the mobile app.

2. In the mobile application:

   1. The user enters username and password.
   2. The user waits for OTP delivery via the out-of-band channel.
   3. The user retypes OTP.
   4. Mobile application then initializes the custom activation with provided username, password, and OTP.

3. Intermediate Server Application receives a custom activation request, with username, password, and OTP:

   1. The username, password, and OTP is verified by the Intermediate Server Application.
   2. If everything’s right, then Intermediate Server Application creates activation by calling createActivation. The activation state can be set to ACTIVE.

4. The mobile application receives the response from the server and completes the activation on the mobile side.

Activation confirmation

In this common scenario, an additional activation OTP helps with the final activation confirmation, so the OTP is required in the later stages of the activation process (during the commit). In this case, it doesn’t matter how the activation process was initiated. You can confirm regular, custom and also recovery activations with the OTP.

Confirm regular activation with OTP

1. User is authenticated in Master Front-End Application and initiates the activation creation process:

   1. Master Front-End Application generates random activation OTP and keeps it temporarily in the database.
   2. Master Front-End Application then asks PowerAuth server to create an activation, with using this OTP (initActivation method, OTP validation set to ON_COMMIT).
   3. Master Front-End Application then displays QR code, containing an activation code.

2. In the mobile application:

   1. The user scans QR code or retypes the activation code manually.
   2. Mobile application then initializes the activation, using activation code.

3. Intermediate Server Application receives a regular activation request, with activation code:

   1. The activation code is verified by the PowerAuth server in the prepareActivation method.
   2. If the method call succeeds, the activation is set to the PENDING_COMMIT state.
   3. At the same time, Intermediate Server Application initiates the delivery of activation OTP. It’s recommended to deliver such code via a dedicated out-of-band channel, for example, via SMS.

4. The mobile application receives the response from the server and completes the keys-exchange on the mobile side.

Now it depends whether the user has to retype OTP back to the Master Front-End Application, or the mobile application.

1. For the first case, the implementation is straightforward. Once the user retypes OTP back to Master Front-End Application, the activation can be completed on PowerAuth Server by calling commitActivation method. In case the commit fails, the number of commit attempts is limited to the MAX_FAILED_ATTEMPTS.

2. In case the OTP is retyped in the mobile application, the additional RESTful endpoint has to be implemented on the Intermediate Server Application. We recommend to use our ECIES encryption to protect such endpoint. In case the commit fails, the number of commit attempts is limited to the MAX_FAILED_ATTEMPTS.

For both cases, it’s recommended to generate a new OTP in case that delivery failed (e.g. user did not receive SMS). You can use updateActivationOtp method to set a new OTP to the PowerAuth Server.

You can also slightly alter this whole sequence, and generate the first OTP later, in the step 3. In this case, you have to use updateActivationOtp in the same step, to set the OTP.

Confirm custom activation with OTP

There are multiple ways how to implement custom activation and confirm it with an additional authentication OTP so that we will discuss only one particular case. In this scenario, we don’t involve the Master Front-End Application in the process, but we expect that the user has already issued some valid credentials to the system.

1. In the mobile application:

   1. The user enters username and password.
   2. Mobile application then initializes the custom activation with provided username and password.

2. Intermediate Server Application receives a custom activation request, with username and password:

   1. The username and password is verified by the Intermediate Server Application.
   2. If everything’s right, then Intermediate Server Application creates activation by calling createActivation. The activation must be set to the PENDING_COMMIT state.
   3. Intermediate Server Application generates random activation OTP and update the activation record, by calling updateActivationOtp method.
   4. At the same time, Intermediate Server Application initiates the delivery of activation OTP.

3. Back in the mobile application:

   1. The mobile application receives the response from the server and completes the key exchange on the mobile side.
   2. The user waits for OTP delivery via the out-of-band channel.
   3. The user retypes OTP.
   4. Mobile application then commits the activation with OTP, by calling a custom RESTful endpoint, protected with our ECIES encryption scheme.

4. Intermediate Server Application then receives the commit request:

   1. Decrypts OTP from the request
   2. Commits the activation by calling PowerAuth Server’s commitActivation method.

After the response from the commit is received on the mobile side, the application can check whether the activation’s state is ACTIVE.

Confirm activation recovery with OTP

The confirmation of activation recovery is very similar to custom activation confirmation.

1. In the mobile application:

   1. The user enters recovery code and PUK.
   2. Mobile application then initializes the recovery activation with provided code and PUK.

2. Intermediate Server Application receives a recovery activation request:

   1. The recovery code and PUK is verified by the PowerAuth Server, by calling recoveryCodeActivation.
   2. Intermediate Server Application generates random activation OTP and update the activation record, by calling updateActivationOtp method.
   3. At the same time, Intermediate Server Application initiates the delivery of activation OTP.

3. Back in the mobile application:

   1. The mobile application receives the response from the server and completes the keys-exchange on the mobile side.
   2. The user waits for OTP delivery via the out-of-band channel.
   3. The user retypes OTP.
   4. Mobile application then commits the activation with OTP, by calling a custom RESTful endpoint, protected with our ECIES encryption scheme.

4. Intermediate Server Application then receives the commit request:

   1. Decrypts OTP from the request.
   2. Commits the activation by calling PowerAuth Server’s commitActivation method.

After the response from the commit is received on the mobile side, the application can check whether the activation’s state is ACTIVE.