Post-Install Configuration

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

Database Setup

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

Creating First Admin User

Authentication is required when calling APIs provided by the PowerAuth Cloud application from various systems.

For basic HTTP authentication, you need to add users (in this case, basically server applications calling the PowerAuth Cloud APIs) and their passwords to the database.

If you want to use OIDC authentication, see the OpenID Connect (OIDC) section. You’ll also need to assign access to the particular PowerAuth application created in the previous step.

The first user you need to add is the primary admin user - let’s call the user system-admin - and it needs to be inserted into the database.

First, you need to generate the password via openssl:

openssl rand -base64 12

The output will look like this:

0k4Vyn4A87VtOkEG

To store the password in the database, you must encode it using bcrypt. You can use the htpasswd command to achieve this:

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

The 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');

The above commands:

• Stored the hashed password for the system-admin user.
• Set the ROLE_ADMIN authority for the administrator user who can call services published under the /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 (in plaintext) as the password.

OAuth 2.x / OpenID Connect (OIDC)

You may use OAuth 2.x or OpenID Connect (OIDC) instead of basic authentication. PowerAuth Cloud accepts only JWT, not opaque tokens. Note that access to the /admin context requires an ADMIN role, so admin users must contain the claim roles with a value ADMIN in the used token. The role name is case-sensitive.

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. The password hashes stored in the database are not used once OIDC / OAuth 2.x is set up.

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, create new users and applications, and assign user access to applications.

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

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 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 is generated in the same flow as when 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 the Firebase Console dashboard.
• Private key (stored in the full *.json file)
  • In the Firebase Console, visit the project page, go to Project Settings > Service Accounts > Generate New Private Key, and store the 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 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 names (for example, to create a payment type that does not allow biometric authentication used for any riskier payment types). See examples of templates

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 the precise look 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 straightforward. The only complex column is the last one - the attributes column. It is a JSON-serialized array of an object that defines attributes 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 a particular attribute. For example, if you create payments with a named variable iban, the value parameter of the KEY_VALUE attribute is set to iban.

The following attribute types are supported:

• AMOUNT - Represents the amount of money, for example during a money transfer. It has two parameters: amount and currency.
• HEADING - Represents the static text heading, does not have any parameters.
• KEY_VALUE - Represents 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.

Optional Approval UI Extension

It is possible to configure the extension for the operation approval flow. 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.

Monitoring

The endpoint /powerauth-cloud/actuator/health displays a composite status of PowerAuth Cloud, PowerAuth Server, Enrollment Server, and Push Server. Also probes for Kubernetes are exposed (/powerauth-cloud/actuator/health/liveness and /powerauth-cloud/actuator/health/readiness). When authenticated with the ADMIN or MONITORING role, you may see details.