Mobile-First Authentication: Installing Server-Side Components

Dec 29, 2023

In this tutorial, we will show you how to install back-end components for mobile-first authentication in banking or fintech apps.

Prerequisites

This tutorial assumes that you have:

Read and understood the Problem Overview chapter
Docker installation (amd64 or arm64 architectures)
PostgreSQL 12 installation

Task Overview

When installing the authentication back-end, you need to perform several tasks:

Pull the Docker image
Configure the environment
Run the Docker image
Setup the first system users
Create application and assign the permissions
Configuring push notifications

Pull the Docker Image

To access our Docker container repository, you need to have an access granted from our administrators. Contact us to obtain the access.

You can obtain the Docker images by simply pulling them from our Artifactory:

docker login wultra.jfrog.io
docker pull wultra.jfrog.io/wultra-docker/powerauth-cloud:${VERSION}

Make sure to replace the ${VERSION} placeholder with the last available version.

Configure the Environment

Our Docker images automatically manage the database schema. As a result, the database user must have permissions to manage the schema in the database. For information about our database schema, please refer to our documentation.

Set The Right Database URL
The datasource URL for our Docker container follows the structure of the JDBC connectivity. Make sure to provide a valid JDBC URL to the configuration (starting with jdbc: prefix). Be especially careful when working on localhost! From the Docker container perspective, localhost is in the internal network. To connect to your host’s localhost, use host.docker.internal host name.

In order to be able to run the Docker image, you need to set it environment variables that define the database scheme connectivity. You can do so, for example, by creating the env.list file with the following content:

POWERAUTH_SERVER_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/powerauth
POWERAUTH_SERVER_DATASOURCE_USERNAME=powerauth
POWERAUTH_SERVER_DATASOURCE_PASSWORD=$PASSWORD$

PUSH_SERVER_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/powerauth
PUSH_SERVER_DATASOURCE_USERNAME=powerauth
PUSH_SERVER_DATASOURCE_PASSWORD=$PASSWORD$

POWERAUTH_CLOUD_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/powerauth
POWERAUTH_CLOUD_DATASOURCE_USERNAME=powerauth
POWERAUTH_CLOUD_DATASOURCE_PASSWORD=$PASSWORD$

ENROLLMENT_SERVER_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/powerauth
ENROLLMENT_SERVER_DATASOURCE_USERNAME=powerauth
ENROLLMENT_SERVER_DATASOURCE_PASSWORD=$PASSWORD$

Run the Docker Image

You can now run the Docker image using any techniques typically used for this task. For example, you can run it in Kubernetes or via Docker compose. As a simple quick start, you can just use docker run command, like so:

docker run --env-file env.list -d -it -p 8080:8000 \
    --name=powerauth-cloud wultra.jfrog.io/wultra-docker/powerauth-cloud:${VERSION}

Setup the First System Users

System users represent systems, such as back-end applications, that are calling the protected API resources in our back-end components. Admin system users can call resources intended for the system administration (available on /admin/** context), while integration system users can only call resources intended for integration.

The first admin system user has to be created directly in the database. You need to create a bcrypt hash of a password to insert the right record using the following SQL commands:

INSERT INTO pa_cloud_user (id, username, password, enabled)
VALUES (nextval('pa_cloud_user_seq'), 'system-admin', '${BCRYPT_PASSWORD_HASH}', 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');

Creating an integration system user is easier, you just need to call the API endpoint using the admin system user credentials:

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

The API automatically generates a strong password for the integration user.

Create an Application and Assign Permissions

Application in the back-end system represents a particular mobile application. You should create a new application for any mobile app, but not a separate one for each platform (iOS/Android). Application can represent, for example, your retail mobile banking, corporate mobile banking, mobile token, investment app, etc.

To create an application, call our API using the admin system user credentials:

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

Pass the response of the call above to your mobile application developers - the values from the response must be embedded in the mobile app configuration.

In order for an integration system user to be able to access resources related to the newly created application, you must assign the integration system user permissions to the application by calling the following API endpoint:

curl -X 'POST' \
  'http://localhost:8080/powerauth-cloud/admin/users/integration-user/applications/my-application' \
  -u system-admin:${PASSWORD} \
  -d ''

Configuring Push Notifications

Our system bundles a basic push server. You can use it to deliver push notifications to Apple or Android devices. We also use it under the hood for various use-cases, such as out-of-band operation approval, or lifecycle management (silent push whenever the device is blocked or removed).

To configure push notification delivery for the application created above, you need to post credentials specific for APNS and FCM services (using your admin system user). You can obtain those credentials at the Apple Developer Portal or in Firebase Console. Then, you can post them to the application using the following commands specific for each platform.

Apple Push Notification Service (APNS)

Note that Apple provides development or production environment. You should use a specific one based on how you sign your applications. Apps published on App Store and Testflight use production environment, those signed during development and published via services such as Microsoft’s App Center typically use development environment.

curl -X 'POST' \
  'http://localhost:8080/powerauth-cloud/admin/applications/my-application/push/apns' \
  -u system-admin:${PASSWORD} \
  -H 'Content-Type: application/json' \
  -d '{
    "topic": "${IOS_TOPIC}",
    "keyId": "${IOS_KEY_ID}",
    "teamId": "${IOS_TEAM_ID}",
    "environment": "development|production",
    "privateKeyBase64": "${IOS_PRIVATE_KEY_BASE64}"
}'

Firebase Cloud Messaging (FCM)

curl -X 'POST' \
  'http://localhost:8080/powerauth-cloud/admin/applications/my-application/push/fcm' \
  -u system-admin:${PASSWORD} \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "${ANDROID_PROCECT_ID}",
    "privateKeyBase64": "ANDROID_PRIVATE_KEY_BASE64"
}'

Continue Reading

You can proceed with one of the following chapters:

Resources

You can find more details our reference documentation:

Last updated on Jan 19, 2024 (09:21) Edit on Github Send Feedback

Petr Dvořák

CEO & Founder