Push client configuration deprecated

How to configure push transport clients

In order to send push messages to a client you need to configure the necessary push transport client. Previously this was done via different yml files and properties. Now this has been unified and if you still use the old way you need to migrate to this approach. For this please consider the migration guide further down in this article.

The transport clients are now configured via yml files in the '/opt/open-xchange/etc/pushClientConfig' folder. All yml files in this folder are considered, however, the used client identifiers needs to be unique across all files. You can also configure multiple transport clients in one file.

The yml files need to follow the following structure:

The top elements are unique names which define the transport client ids. Then each client contains a '_type' field which contains the type of the transport client. Currently only 'apn' and 'fcm' are supported.

The other fields of a config vary depending on the type.

fcm

This is the configuration for android based clients which use the firebase cloud messaging service. The configuration for this type contains the following fields:

Name Type required description
name String true A Unique App Name for the Installation
keyPath String true The path for the FCM key file

Example config

my-fcm-transport-client:
  _type: fcm
  name: A Unique App Name for the Installation
  keyPath: /full/path/of/key.json

apn

The configuration for ios/macos based clients which use the apple push notification service. This type supports two configuration modes.

Certificate

A configuration based on a certificate. There are actually two ways to provide the keystore which contains the certificate. On one hand you can mount it as a file into the container and configure the path via the 'keystore' field. On the other hand and also the preferred way is to deploy it as a secret in the k8s cluster in the same namespace, label it with 'OX_KEYSTORE=YourKeystoreId' and configure this id via the keystoreId field.

Here is an overview over all fields for this auth type:

Name Type required description
authtype String false The config type. If configured must be set to 'certificate'
keystoreId String false The id of the keystore. Must be mapped to the OX_KEYSTORE label of the secret.
keystore String false The path to the local keystore file.
password String false The password of the keystore.
topic String true The topic of your application. Typically the bundle ID of the app.
production boolean false Indicates which apn service to use.

Example apn certificate config

my-apn-certificate-based-transport-client:
  _type: apn
  authtype: certificate
  topic: com.openxchange.mobile.drive2.pushkit.fileprovider
  production: true
  keystoreId: my-secret-label-value
  password: myKeystorePassword

JWT

A configuration based on a json web token. Again there are two ways to provide the jwt. On one hand you can mount it as a file into the container and configure the path via the 'privatekey' field. On the other hand and also the preferred way is to deploy it as a secret in the k8s cluster in the same namespace, label it with 'OX_KEYSTORE=YourKeystoreId' and configure this id via the privatekeyId field.

Here is an overview over all fields for this auth type:

Name Type required description
authtype String true The config type. Must be set to 'jwt'.
privatekeyId String false The id of the jwt. Must be mapped to the OX_KEYSTORE label of the secret.
privatekey String false The path to the local jwt file.
keyid String true The key identifier of this jwt.
teamid String true The team identifier of this jwt.
topic String true The topic of your application. Typically the bundle ID of the app.
production boolean false Indicates which apn service to use.

Example apn jwt config

my-apn-jwt-based-transport-client:
  _type: apn
  authtype: jwt
  topic: com.openxchange.mobile.drive2.pushkit.fileprovider
  production: true
  privatekeyId: my-secret-label-value
  keyid: MyKeyId
  teamid: MyTeamId

How to map push subscriptions to transport clients

Once you configured all your transport for every client you want to support you need to map the subscriptions to the respective transport. There are actually two different systems in place.

Drive

For push messages to drive clients you need to enabled the push transport and configure the client id for every transport type. The properties can be defined individually per user through the config cascade.

com.openexchange.drive.events.apn2.ios.enabled=true
com.openexchange.drive.events.apn2.ios.clientId=my-apn-certificate-based-transport-client

com.openexchange.drive.events.apn.ios.enabled=true
com.openexchange.drive.events.apn.ios.clientId=my-apn-jwt-based-transport-client

com.openexchange.drive.events.fcm.enabled=true
com.openexchange.drive.events.fcm.clientId=my-fcm-transport-client

Mobile Api Facade

For clients which use the mobile api facade it is a bit different. Here the mobile client id must match the transport client id. So you need to configure the transport client with the mobile client id as a prefix followed by the operating system of the mobile client.

So for an android client with the client id 'my-mobile-client' you need to configure a transport client with the id 'my-mobile-client-android'. And for an ios client with the client id 'my-other-client' you need to configure a transport client with the id 'my-other-client-ios'.

Migration

If you want to migrate from your current configuration to the new one please follow the following steps

Drive

  • Remove all com.openexchange.drive.events.* properties with the exception of the com.openexchange.drive.events.*.enabled properties
  • Optionally create a k8s secret from the used keystore files and label them with the OX_KEYSTORE key and a unique value of your choosing
  • Create the yml configuration
    • Create a yml file and mount it into the /opt/open-xchange/etc/pushClientConfig folder
    • Add a transport configuration to it for each different transport client you want to support
    • Choose a unique name
    • Choose the respective type (apn or fcm)
    • Take over the configuration of the existing
    • Optionally set the keystore id to the value of your secret label
  • For each transport configure the respective com.openexchange.drive.events.*.clientId

Mobile Api Facade

APN

  • Optionally create a k8s secret from the used keystore files and label them with the OX_KEYSTORE as a key and a unique value of your choosing
  • Move your /opt/open-xchange/etc/pns-apns-options.yml into the /opt/open-xchange/etc/pushClientConfig folder
  • Adjust the yml
    • Remove the enabled field of this config
    • Adjust the name to match the id + the operating system of your mobile client (see above)
    • Replace keystore with keystoreId and set it to the respective secret label value

FCM

Basically do the same as for apn for the pns-fcm-options.yml file with the exception that the keystore changes are not necessary.