Mobile-First Authentication

Mobile Token SDK and PowerAuth Cloud Onboarding

Introduction

In the following tutorial, you will see the basics of how to use Mobile Token SDK in your mobile app with the PowerAuth Cloud solution. For the onboarding purposes, we have provisioned a dedicated Sandbox Environment which can be used for this tutorial and subsequent implementation tests.

For more details please see the following sections of the documentation:

• System Integration
• Activation states and flow
• Computing and Validating Signatures
• Operations Configurations
• PowerAuth Cloud API - General Principles
• Administrative Services
• Auditing Services
• Authentication Services
• Communication Services
• Operations Services
• Registrations Services

Environment Setup

The environment is provisioned with pre-created account credentials and basic PowerAuth configuration. All credentials for the environment will be shared with your appointed persons.

The shared credentials contain the following:

• admin user and password,
• integration user and password,
• URL to the endpoint,
• application configuration data.

Please note that, generally, credentials can be reset but not revealed – e.g., in case of forgotten passwords.

Creating Integration Users

You can create additional users via API. Those users are called Integration users, and the purpose is to segregate a user needed for admin API from the user for standard operations.

The API example:

POST /powerauth-cloud/admin/users

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/System Users/createUser

Payload:

{
  "username": "<client-name>-integration-user"
}

• username - new integration user username

Creating Application

We have already prepared application <client-name>-mobile-banking in the environment. You can create additional applications via API at your convenience. The integration user has to be assigned to the created application.

The API for application creation:

POST /powerauth-cloud/admin/applications

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Applications/createApplication`

Payload:

{
  "id": "<client-name>-mobile-banking"
}

• id – ID of the created application.

The call returns the credentials needed for Mobile Token setup. In the case of SDK development, the credentials have to be compiled into your mobile app.

The API for assigning an integration user to the application:

POST /powerauth-cloud/admin/users/<client-name>-integration-user/applications/<client-name>-mobile-banking

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/System%20Users/addAppAccessToUser

Payload

{
  "username": "<client-name>-integration-user",
  "appId": "<client-name>-mobile-banking"
}

• username – integration user username.
• appId – created application ID.

Integration in the Mobile Application

The Mobile Token SDK and prerequisite PowerAuth SDK have to be integrated into the mobile application.

Mobile Application Activation

First, you need to configure your application to share keys with the servers.

Creating Activation Code

Generate the code (one of the activation options) needed for the device to be activated. The QR code is typically shown in your web application.

Generate code via an API endpoint:

POST /powerauth-cloud/v2/registrations

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/createRegistration

Payload:

{
  "userId": "{userId}",
  "appId": "<client-name>-mobile-banking"
}

• userId – use your end user identifier.
• appId – use <client-name>-mobile-banking.

In the response, you will get two attributes: activationQrCodeData and registrationId.

• activationCode - activation code. The activation code has to be used in the SDK to activate the SDK.
• activationQrCodeData – data for QR code generation. To generate the QR code, you can copy and paste the string to any QR Code Generator. The QR code contains the activation code and additional signature to verify the QR code’s authenticity and integrity.
• registrationId – this value represents the registered device for the user, and you will need to use it in subsequent operations, so please note it for later use.

Using QR Activation Code

Open the application, invoke the QR code scanning feature and scan the QR code. Please keep in mind that the activation has limited validity. By default, it is set to 2 minutes.

Checking Activation Status (Optional)

To check the activation status, use the API endpoint:

GET /powerauth-cloud/v2/registrations/

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/getRegistrationList

Query Parameters:

{
  "userId": "{userId}"
}

• The userId parameter in the query has to match the userId used in the previously created registration.

Removing Activation

The registration can be removed at this stage – e.g., when a user cancels the registration process. So registration in CREATED and PENDING_COMMIT can be removed by an API endpoint:

DELETE /powerauth-cloud/v2/registrations/${registrationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/deleteRegistration

Payload:

{
  "registrationId": "{userId}",
  "externalUserId": "{any id of your employee}"
}

• registrationId – ID created previously during the Creating QR Activation Code step.
• externalUserId – you can insert any ID you want to associate with the registration, e.g., an ID of an external user who created this change, for example the admin or call center operator.

Committing Activation

Now, commit the activation. This part is designed for your onboarding process and KYC to kick in, and the Power Auth server is waiting for an external call to “commit” the registration to an active state.

To commit the activation, i.e. finalize the activation, use the API endpoint:

POST /powerauth-cloud/v2/registrations/${registrationId}/commit

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/commitActivation

Payload:

{
  "registrationId": "{userId}",
  "externalUserId": "{any id of your employee}"
}

• registrationId – ID created previously during the Creating QR Activation Code step.
• externalUserId – you can insert any ID you want to associate with the registration, e.g., an ID of an external user who created this change, for example the admin or call center operator.

Now the mobile application informs you that it is ready to serve authenticated requests.

Blocking and Unblocking Activation

Once the registration has been committed, it cannot be simply removed by the verb DELETE, but you can still change the registration status. Typically, when you wish to block (or unblock) the device or internally remove the registration entirely.

API endpoint:

PUT /powerauth-cloud/v2/registrations/${registrationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Registrations/updateRegistrationState

Payload:

{
  "change": "BLOCK",
  "blockReason": "The reason for blocking",
  "externalUserId": "{any id of your employee}"
}

• change - the state to which the registration should change.
• blockReason - reason for blocking the registration.
• externalUserId – you can insert any ID you want to associate with the registration, e.g., an ID of an external user who created this change, for example the admin or call center operator.

Operation Management

Invoking Operation

There are two operation templates prepared in the demo environment: login and payment.

Login

The operation login can be invoked via an API endpoint:

POST powerauth-cloud/v2/operations

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/createOperation

Payload:

{
  "userId": "{userId}",
  "template": "login",
  "language": "en"
}

• userId – userId created in the registration step.
• template – you can use pre-defined operation templates login or payment.
• language – for localization purposes, only English is available in the demo environment, this is the language of first push notification, otherwise the localization is driven by the setting of the mobile app.

Payment

The call for payment has a slightly different payload as there are more parameters defined in the template:

POST powerauth-cloud/v2/operations

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/createOperation

Payload:

{
  "userId": "{userId}",
  "template": "login",
  "language": "en",
  "parameters": {
    "amount": "1000000000.00",
    "currency": "EUR",
    "iban": "CZ5508000000001234567899"
  }
}

• parameters – this section is defined per template, i.e. new template has to be configured for different parameters. In the response, you will receive operationId attribute. The attribute is needed for subsequent operation processing.

Retrieving a Pending Operation in a Mobile Application

Approving an Operation in a Mobile Application

Checking Operation Status (Optional)

To check the operation status you can poll the result via an API endpoint:

GET /powerauth-cloud/v2/operations/${operationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/getOperation

Query parameters:

{
  "operationId": "{operationId}"
}

• operationId – operationId received during the creation of the operation.

The Wultra PowerAuth system can perform callbacks, so in a real-life scenario you typically combine callback with polling to get an immediate response via callback for the best user experience and polling as a fallback.

Removing Operation (Optional)

You can remove any pending operation if required by your business logic.

Removal is invoked via an API endpoint:

DELETE /powerauth-cloud/v2/operations/${operationId}

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Operations/cancelOperation

Payload:

{
  "operationId": "{operationId}"
}

• operationId – ID of the operation to be removed.

Message Signing

In a mobile-only approach, it might be more straightforward to sign the payload of business calls in the mobile app and validate it on your own backend. For this, we can use the signing of the data provided by PowerAuth SDK.

The flow is that your mobile app lets a user enter necessary data for some operation, e.g., payment. This data can be in any format of your choosing, and then the mobile app uses PowerAuth SDK to create an authorization header. This header is sent to your backend alongside the standard API call for operation (e.g., payment) creation. During the validation of the call, your backend can call API in the PowerAuth Cloud to verify that operation data are properly signed by the user.

The verification of the signature is done on the PowerAuth Cloud via an API call:

POST /powerauth-cloud/v2/signature/verify

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Signature%20Verification/verifyOnlineSignature

Payload:

{
  "method": "POST",
  "uriId": "/mobile/login",
  "authHeader": "PowerAuth pa_activation_id=\"a4452997-45c0-4667-bb24-c7d39337b9c0\", pa_application_key=\"GlxZ1Qe70pGAG/ek0BvNXw==\", pa_nonce=\"2I9gzcP5uJtX3RUr9Qp5Bg==\", pa_signature_type=\"possession_knowledge\", pa_signature=\"LLUZvtWpXwXWZlPzwRFG7PBFQdQkp5h/K/dxWiUi2A8=\", pa_version=\"3.1\"",
  "requestBody": "bG9n"
}

• method – same as the method used for signature computation.
• uriId – same as resourceId used for signature computation.
• authHeader – use the value returned by the previous call. All information needed to compute signature and signature itself are present here.
• requestBody – base64 encoded parameter used for the creation of the signature in the mobile application.

The call returns the status of signature verification as a signatureValid attribute. And several other metadata, most notably remainingAttempts. Please note that the signature verification is resistant to replay attacks, so only the first call to the verification API can return signatureValid true. Any subsequent call will fail (and decrease the remaining attempts).

Communication with the Token

Configuring Push Notification

For a good user experience, PowerAuth actively sends push notifications when a user should confirm an operation. The PowerAuth API also allows sending custom push notifications.

A push notification can be sent via an API endpoint:

POST /powerauth-cloud/v2/messages/send

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Push%20Notifications/applicationDetail

Payload:

{
  "userId": "{userId}",
  "registrationId": "{registrationId}",
  "silent": false,
  "title": "Balance Update",
  "message": "We just updated your balance. You can review it in mobile banking.",
  "sound": "default"
}

• userId – userId created in the registration step.
• registrationId – registrationId created in the registration step. The registrationId is optional if the push notification should be sent only to a specific device.
• silent – switch if the message delivery should be announced by a push message.
• title - title of the notification
• message- content of the message

Inbox

For communication purposes – like sending news, info about new features etc., PowerAuth Cloud offers simple Inbox.

An example of an API call sending a simple message to the Inbox:

POST /powerauth-cloud/v2/inbox/messages

Console URL:

https://<client-url>/powerauth-cloud/swagger-ui/index.html#/Inbox/sendMessage

Payload:

{
  "userId": "{userId}",
  "type": "html",
  "subject": "Message subject",
  "summary": "Message summary",
  "body": "Message content",
  "silent": false
}

• userId – userId created in the registration step.
• type – user html of text.
• subject – message subject – used for push notification and as a headline in app.
• summary – message summary used for the push notification.
• body – main message body displayed in app.
• silent – switch if the message delivery should be announced by a push message.