Advanced Activation Flows

Edit on Github Send Feedback v1.9.0

This part of the documentation describes in detail advanced customizations of the activation process: how the commit phase can be changed as well as usage of additional activation OTP. So, before you start, you should be familiar with actors and processes defined for the regular activation.

Following advanced activation flows are supported:

Changing the commit phase of the activation
Verification of an additional activation OTP

By default, the activation is committed during the PENDING_COMMIT status. It is possible to change the activation flow, so that the activation is committed during the key exchange and so it skips the PENDING_COMMIT status transition completely and goes directly into ACTIVE state.

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:

Changing the commit phase
Additional user authentication using Activation OTP
- Regular activation with OTP
- Custom activation with OTP
Activation confirmation using OTP

Changing the Commit Phase

As mentioned before, by default the activation is committed in the PENDING_COMMIT state.

It is possible to change the activation flow, so that the PENDING_COMMIT state is skipped and activation becomes ACTIVE during key exchange.

To do so, you can set the commitPhase parameter to ON_KEY_EXCHANGE when initializing the activation using the init activation method (initActivation.

In case the commitPhase parameter is not specified, or the value is set to ON_COMMIT, the activation flow remains standard and waits for an additional commit step after the key exchange.

The commitPhase can be chosen independently on the activation OTP verification. However, the OTP verification can be added as another extra option in either of the commit phases, as described below.

Additional User Authentication using Activation OTP

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

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 using the init activation method (initActivation, commitPhase parameter is set to ON_KEY_EXCHANGE and the activationOtp value is set to previously generated OTP).
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.
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.
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.
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.

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.
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.
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.
The mobile application receives the response from the server and completes the activation on the mobile side.

Activation Confirmation using OTP

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

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 using the init activation method (initActivation method, commit phase is not specified or set to ON_COMMIT and the activationOtp value is set to previously generated OTP).
3. Master Front-End Application then displays QR code, containing an activation code.
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.
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.
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.

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.
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.

In the mobile application:
1. The user enters username and password.
2. Mobile application then initializes the custom activation with provided username and password.
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.
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.
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.

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.
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.
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.
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.

Last updated on Oct 07, 2024 (06:31) Edit on Github Send Feedback