Post-Install Configuration

After you created the database and installed PowerAuth Cloud in the Docker, you need to perform mandatory post-installation steps.

Database Setup

The Liquibase script bundled in the Docker image can create a correct database scheme.

Creating First Admin User

When calling APIs provided by the PowerAuth Cloud application from various systems, authentication is required. For basic HTTP authentication we need to add users (which, in this case, are basically server applications calling the PowerAuth Cloud APIs) and their passwords in the database. Or see OpenID Connect (OIDC) if you want to use OIDC authentication. We also need to assign access to the particular PowerAuth application created in the previous step.

The first user we need to add is basically the main admin user, let’s call the user system-admin. The first user needs to be inserted in the database.

First, we need to generate the password via openssl:

openssl rand -base64 12

Output will look like this:

0k4Vyn4A87VtOkEG

In order to store the password in the database, we need to encode it using bcrypt first. You can use the htpasswd command to achieve this:

htpasswd -bnBC 12 "" 0k4Vyn4A87VtOkEG | tr -d ':'

Output will look like this:

$2a$12$uZbWUhbRxqHwz5IYqg21LO.LHNhuKFM2SoA56ozAezyGMQdFpDJwe

You can now put this all together and store the user in the database:

INSERT INTO pa_cloud_user (id, username, userpassword, enabled)
VALUES (nextval('pa_cloud_user_seq'), 'system-admin', '$2a$08$uZbWUhbRxqHwz5IYqg21LO.LHNhuKFM2SoA56ozAezyGMQdFpDJwe', true);

INSERT INTO pa_cloud_user_authority (id, user_id, authority)
VALUES (nextval('pa_cloud_user_seq'), (SELECT id FROM pa_cloud_user WHERE username = 'system-admin'), 'ROLE_ADMIN');

• We stored the hashed password for the system-admin user.
• We used authority ROLE_ADMIN for the administrator user who can call services published under /admin context. Regular users who only need to call registration and operation APIs can use a restricted ROLE_USER authority.

You can now check the changes in the database:

• pa_cloud_user - New user record with the bcrypt-hashed password.
• pa_cloud_user_authority - New user authority record.

At this point, you can open http://localhost:8080/powerauth-cloud/ and use system-admin as username and 0k4Vyn4A87VtOkEG, your password value respectively (plaintext) as the password.

OpenID Connect (OIDC)

Instead of basic authentication, you may use OpenID Connect (OIDC). Admin users have to contain claim roles with a value ADMIN in the UserInfo endpoint response. (Mind that role name without ROLE_ prefix is used, unlike basic authentication where the authority is inserted.) The claim name may be changed in the configuration powerauth.cloud.security.auth.oidc.roles-claim=roles.

You still have to create users via API and assign them to applications. Password hash stored in the database is not taken into account.

See the Spring Security documentation and OpenID Connect UserInfo endpoint for details.

Adding More Users and Applications

After you create your first admin user, you can open Swagger UI and create new users and applications, and assign user access to application.

Creating an Integration User

In Swagger UI, you can call POST /admin/users to create a new regular user. The corresponding cURL call would be:

curl -X 'POST' \
  'http://localhost:8080/powerauth-cloud/admin/users' \
  -u system-admin:0k4Vyn4A87VtOkEG \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "integration-user"
}'

The response will return a random generated password for the new user.

Create Your First Application

In Swagger UI, you can call POST /admin/applications to create a new application. The corresponding cURL call would be:

curl -X 'POST' \
  'http://localhost:8080/powerauth-cloud/admin/applications' \
  -u system-admin:0k4Vyn4A87VtOkEG \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "my-application"
}'

Assign Integration Access to New Application

In Swagger UI, call POST /admin/users/{username}/applications/{appId} to assign integration user access to the newly created application. The corresponding cURL call (substituting the placeholders for previous values) would be:

curl -X 'POST' \
  'http://localhost:8080/powerauth-cloud/admin/users/integration-user/applications/my-application' \
  -u system-admin:0k4Vyn4A87VtOkEG \
  -d ''

Configuring Push Server Credentials

In order to configure the Push Server credentials, you need to first obtain the required value from Apple and Google.

To obtain APNS credentials for iOS apps, visit the Apple’s developer portal to find:

• Key ID
  • A key generated for APNs see official guide.
• Team ID
  • Team Id of your Apple Developer account. Can be found on the membership details page.
• Your iOS app bundle (used as a “topic”)
  • Can be found in App Store Connect in General>App Information.
• Private key for push notifications (*.p8 file)
  • The key generated in the same procedure when you are retrieving your Key ID.

To obtain FCM credentials for Android, visit the Firebase Console by Google to find:

• Project ID
  • Can be found directly on Firebase Console dashboard.
• Private key (stored in the full *.json file)
  • In the Firebase console on a project page go to Project Settings > Service Accounts > Generate New Private Key and store resulting json file.

The private key value has to be encoded as Base64, i.e. a *.p8 file for APNs and a *.json file for FCM - entire file encoded as Base64. You can now set the values by calling:

• POST /admin/applications/{id}/push/apns

    {
      "topic": "string",
      "keyId": "string",
      "teamId": "string",
      "environment": "development|production",
      "privateKeyBase64": "stringBase64"
    }
  

• POST /admin/applications/{id}/push/fcm

    {
      "projectId": "string",
      "privateKeyBase64": "stringBase64"
    }
  

• POST /admin/applications/{id}/push/hms

    {
      "projectId": "string",
      "clientId": "string",
      "clientSecret": "string"
    }
  

Configuring Push Server Callback

To make sure Push Server is notified about registration status change whenever it happens, we recommend adding the following callback URL to the database:

INSERT INTO pa_application_callback (id, application_id, name, callback_url, attributes)
VALUES (uuid_generate_v4(), 1, 'push-server', 'http://localhost:8080/powerauth-push-server/push/device/status/update', '["activationId","activationStatus"]');

Configuring Operations Templates

Finally, you need to configure the templates used while working with operations. The operation templates are technically stored in three separate tables.

Operation Template

The pa_operation_template table contains templates used for signing. The template is rather technical. The values are not visible to the end user but they are a critical part of the underlying cryptography. Let’s create two operations for the start: login and payment approval.

INSERT INTO pa_operation_template (id, template_name, operation_type, data_template, signature_type, max_failure_count, expiration)
VALUES (1, 'login', 'login', 'A2', 'possession_knowledge,possession_biometry', 5, 300);

INSERT INTO pa_operation_template (id, template_name, operation_type, data_template, signature_type, max_failure_count, expiration)
VALUES (2, 'payment', 'authorize_payment', 'A1*A${amount}${currency}*I${iban}', 'possession_knowledge,possession_biometry', 5, 300);

Of course, you can insert many other operation types, and even the same operation types with different template name (for example, to create payment type that does not allow biometric authentication used for any riskier payment types).

Operation Summary Localization

You can easily localize operation summary (used for the push messages sent through the system, and for offline approvals) by adding localization records for the particular templates. You need to provide at least English localization (en), any other localizations are optional, non-existing localizations will fallback to English keys.

To create English localization for the two operations we created earlier, run the following script:

INSERT INTO pa_cloud_localization (id, placeholder, language, title, summary)
VALUES (1, 'login', 'en', 'Approve Login', 'Please confirm the login request.');

INSERT INTO pa_cloud_localization (id, placeholder, language, title, summary)
VALUES (2, 'payment', 'en', 'Approve Payment', 'Please approve the payment of ${amount} ${currency} to account ${iban}.');

Mobile Token Operation Localization

When mobile token requests the list of operations that are pending approval, additional attributes can be rendered to the end user. To define precise looks of the particular operation, you need to configure the localized mobile API operation template.

Again, you need to provide at least the English localization. Also, note that the operations are addressed not by a template name at this level, but by the operation type.

We will create the data for the operations we created earlier.

INSERT INTO es_operation_template (id, placeholder, language, title, message, attributes, ui)
VALUES (1, 'login', 'en', 'Login Approval', 'Are you logging in to the internet banking?', null, null);

INSERT INTO es_operation_template (id, placeholder, language, title, message, attributes, ui)
VALUES (2, 'authorize_payment', 'en', 'Payment Approval', 'Please confirm the payment', '[
  {
    "id": "operation.amount",
    "type": "AMOUNT",
    "text": "Amount",
    "params": {
      "amount": "amount",
      "currency": "currency"
    }
  },
  {
    "id": "operation.account",
    "type": "KEY_VALUE",
    "text": "To Account",
    "params": {
      "value": "iban"
    }
  }
]', null);

Most of the columns in the table are straight forward. The only complex column is the last one - the attributes column. It is a JSON serialized array of object that define attributes that are rendered in the mobile app. The object structure is the following:

• id - ID of the attribute.
• type - Type of the attribute.
• text - The text (localized) that will be displayed as the attribute static text in the mobile app.
• params - Attribute parameters, differ according to the type. Note that the parameters only define what names of operation named variables are assigned to particular attribute. For example, if you create payments with named variable iban, the value parameter of the KEY_VALUE attribute is set to iban.

The following attribute types are supported:

• AMOUNT - Represent the amount of money, for example during a money transfer. It has two parameters: amount and currency.
• HEADING - Represent the static text heading, does not have any parameters.
• KEY_VALUE - Represent the key-value attribute displayed on a single line. It has one parameter value.
• NOTE - Represent the key-value attribute displayed on multiple lines. It has one parameter note.

REST API Configuration

The version of REST API which is published is controlled using following configuration property:

powerauth.cloud.rest.api.version=v2

Optional Approval UI Extension

It is possible to configure the extension to operation approval. See Operation Extensions documentation at the Enrollment Server. This configuration is intended for online mode and overrides optional Risk Flags defined by Operation Template at the PowerAuth Server.