Deploying Push Server

Push Server is a Java EE application (packaged as an executable WAR file) that can be used to send push notifications to iOS or Android devices. This chapter explains what steps need to be taken in order to deploy PowerAuth 2.0 Push Server.

Downloading Push Server

You can download the latest powerauth-push-server.war at the releases page:

• https://github.com/lime-company/lime-security-powerauth/releases

Configuring Push Server

The default implementation of a PowerAuth 2.0 Push Server has only one compulsory configuration parameter powerauth.service.url that configures the SOAP endpoint location of a PowerAuth 2.0 Server. The default value for this property points to localhost:

powerauth.service.url=http://localhost:8080/powerauth-java-server/soap

Setting Up Credentials

(optional) In case PowerAuth 2.0 Server uses a restricted access flag in the server configuration, you need to configure credentials for the PowerAuth 2.0 Push Server so that it can connect to the SOAP service:

powerauth.service.security.clientToken=
powerauth.service.security.clientSecret=

The credentials are stored in the pa_integration table.

Note: For SOAP interface, PowerAuth 2.0 Server uses WS-Security, UsernameToken validation (plain text password). The RESTful interface is secured using Basic HTTP Authentication (pre-emptive).

Connecting to Database

The default database connectivity parameters in powerauth-push-server.war are following (MySQL defaults):

spring.datasource.url=jdbc:mysql://localhost:3306/powerauth
spring.datasource.username=powerauth
spring.datasource.password=
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.jpa.hibernate.ddl-auto=none

These parameters are of course only for the testing purposes, they are not suitable for production environment. They should be overridden for your production environment using a standard Spring database connectivity related properties.

As you can see, these credentials are the same as for the PowerAuth 2.0 Server. You may use the same database for both applications but it is not required - Push Server can have own database.

Setting Up Database Tables

The PowerAuth 2.0 Push Server requires following new tables to be set up in the database you use for your PowerAuth 2.0 deployment.

Registered Devices Table

Table name: push_device_registration

Purpose: Stores push tokens specific for a given device.

Columns:

Name	Type	Info	Note
id	BIGINT(20)	primary key, index, autoincrement	Unique device registration ID.
activation_id	VARCHAR(37)	index	Application name, for example "Mobile Banking".
user_id	BIGINT(20)	index	Associated user ID
app_id	BIGINT(20)	index	Associated application ID
platform	VARCHAR(30)	-	Mobile OS Platform ("ios", "android")
push_token	VARCHAR(255)	-	Push token associated with a given device. Type of the token is determined by the platform column.
last_registered	DATETIME	-	Timestamp of the last device registration.
is_active	INT(11)	-	PowerAuth 2.0 activation status (boolean), used as an activation status cache so that communication with PowerAuth 2.0 Server can be minimal.
encryption_key	TEXT	-	Base64 encoded key that is used for deriving per-message end-to-end encryption keys in case the message is encrypted.
encryption_key_index	TEXT	-	Base64 encoded session index (byte[]) used to derive encryption_key from KEY_TRANSPORT key.

Push Service Credentials

Table name: push_app_credentials

Purpose: Stores per-app credentials used for communication with APNs / FCM.

Columns:

Name	Type	Info	Note
id	BIGINT(20)	primary key, index, autoincrement	Unique credential record ID.
app_id	BIGINT(20)	index	Associated application ID
ios	BLOB	-	Binary representation of P12 file with certificate used for Apple's APNs service.
ios_password	VARCHAR(255)	-	Password used to protect the P12 key.
android	TEXT	-	Base64 encoded token (API_KEY) used for Google's FCM service.

Push Messages Database

Table name: push_message

Purpose: Stores individual messages that were sent by the push server and their sent status.

Columns:

Name	Type	Info	Note
id	BIGINT(20)	primary key, index, autoincrement	Unique message record ID.
device_registration_id	INT	index	Associated device registration (device that is used to receive the message), for the purpose of resend on fail operation.
user_id	BIGINT(20)	index	Associated user ID.
activation_id	VARCHAR(37)	index	PowerAuth 2.0 activation ID.
silent	INT	-	Flag indicating if the message was "silent" (0 = NO, 1 = YES)
personal	INT	-	Flag indicating if the message was "personal" - sent only on active devices (0 = NO, 1 = YES)
encrypted	INT	-	Flag indicating if the message was "encrypted" (0 = NO, 1 = YES)
message_body	TEXT	-	Payload of the message in a unified server format. This format is later translated in a platform specific payload.
timestamp_created	DATETIME	-	Date and time when the record was created.
status	INT	-	Value indicating message send status. (-1 = FAILED, 0 = PENDING, 1 = SENT)

Setting up APNL

PowerAuth 2.0 Push Server uses Pushy to send notifications. Since Pushy uses the new HTTP/2 interface for sending APNs messages, underlying server must support this protocol. As a result, Java runtime / application container must support HTTP/2 as well.

APNL and Tomcat 8.0

Put apnl-boot library in ${CATALINA_HOME}/lib folder and make sure to start Tomcat with -Xbootclasspath/p:${CATALINA_HOME}/lib/alpn-boot.jar parameters, so that the library is on classpath.

Deploying Push Server

You can deploy PowerAuth 2.0 Push Server into any Java EE container.

The default configuration works best with Apache Tomcat server running on default port 8080. In this case, the deployed server is accessible on http://localhost:8080/powerauth-push-server/.

To deploy PowerAuth 2.0 Push Server to Apache Tomcat, simply copy the WAR file in your webapps folder or deploy it using the "Tomcat Web Application Manager" application (usually deployed on default Tomcat address http://localhost:8080/manager).

Important note: Since PowerAuth 2.0 Push Server is a very simple application with direct access to the PowerAuth 2.0 Server SOAP services, it must not be under any circumstances published publicly and must be constrained to the in-house closed infrastructure. The only exception to this rule is the requirement to open up ports for the purpose of communication with APNs and FCM services - the push notifications apparently would not work without access to the primary push service providers.

Deploying Push Server Outside the Container

You can also execute WAR file directly using the following command:

java -jar powerauth-push-server.war

Note: You can overwrite the port using -Dserver.port=8090 parameter to avoid port conflicts.

Important note: Since PowerAuth 2.0 Push Server is a very simple application with direct access to the PowerAuth 2.0 Server SOAP services, it must not be under any circumstances published publicly and must be constrained to the in-house closed infrastructure. The only exception to this rule is the requirement to open up ports for the purpose of communication with APNs and FCM services - the push notifications apparently would not work without access to the primary push service providers.