Introduction

UnifiedPush is a protocol that allows applications to receive push messages, while letting the user choose which push provider they wish to use.

In this ecosystem, we can identify 2 different sides:

• The push provider, who provides an application responsible to keep a connection with its server, and to forward notifications to other apps. This is the push service, also named distributor, which works with its push server. The push server receives messages from application servers.
• The end user applications that consume the push service. Their server sends messages to the mobile application through the push server and the distributor.

Any application can be used with any distributor. Depending on whether the user has a default distributor, applications can automatically use it or can ask the user to choose the distributor they want to use. For more details, see the User Experience guide.

Important

When adding UnifiedPush support to your app, you should test the feature with at least 2 different distributors!

Push notification is a misleading name, it gives some confusion with notifications shown on the user interface. Push message would be more accurate: they don’t necessarily lead to a notification. They can be used to wake your client to synchronize with the server, or to process the content in the background.

UnifiedPush uses two main standards/specifications:

• Web Push is used for the connection between the application server and the push server.
• The UnifiedPush specification is used for the communication between the distributor app and the end user application. There are separate specifications for Android and Linux.

Note that the following are not standardised:

• The connection between the push server and the distributor app.
• The connection between the application server and the end user application.

Push providers and application developers build their own APIs for these and are free to make their own implementation choices.

Push notifications are encrypted following RFC8291. The application generates a public key and an authentication secret it shares with its server with the endpoint. So the server can use these information to encrypt the notifications.

Important

Some libraries are outdated and support a draft of the RFC8291 (the 4th draft) and won’t work. To check if the library supports the RFC correctly, check the content-encoding header: it must be aes128gcm.

Push notifications may be authenticated with VAPID (RFC8292). VAPID is a mechanism to authenticate requests to a push server, using asymmetric keys. These keys are generated by the application server. The mobile application fetch the public key and use it to register to the distributor, which will be able to add restrictions for your subscription. VAPID adds an additional security layer on push notifications, endpoints are already Capability URLs that should not be guessable.

Important

Some push providers require a VAPID key to get registrations, if they don’t have it, they will respond to registration with a failure.

Some other push providers may ignore VAPID authorizations.

A blog post gives more details about security of push notifications.

The content of the cleartext of the notification is then totally dependent on the application. It may be a JSON containing the information that can be used to create a UI notification directly, a simple ping to tell the app to synchronize, a message the app needs to parse, and so on.

When adding Web Push support to an application server, you should take the following points into account.

After receiving a new push registration, it is recommended for the application server to validate the new push channel before sending actual notifications. It prevents Web Push from being used for Denial Of Service (DOS) amplification. This is especially relevant in a federated context where a single event could trigger push messages to many different servers.

During the registration, the server should send a unique token to the application through a push message, and the app should send the token back to the app server. If this succeeds, the application server can use the new registration.

Additionally, the application server should reject push endpoints that resolve to non-global IP addresses, in order to limit server-side request forgery (SSRF).

The server should check this for every push message it sends, after the domain resolution, and before sending the request.

At a minimum, private IP addresses such as RFC 1918 and RFC 4193 are denied. Excluding other non-global IP ranges is recommended, but not as critical (e.g., link-local or broadcast addresses). Many programming languages have library functions for this, for example, Rust.

If the application server is self-hostable, it should provide an option to allow-list domains and IP ranges (to allow for self-hosted private push servers).

The specifications can be overwhelming. Luckily, libraries are available, so that you don’t have to implement these protocols yourself.

On the end user application side, the UnifiedPush connector libraries handle things for you: they generate encryption keys during a new registration, and automatically decrypt incoming messages. Libraries are available for both Android and Linux.

On the application server side, you should use a Web Push library. Most programming languages and frameworks should have such a library available. Make sure that the library complies with the latest version of the Web Push RFCs (see above).

The high-level flow of adding UnifiedPush support to your app looks as follows:

1. Include one of the UnifiedPush connector libraries in your end user application. Build the user flows for handling the different situations, for example, selecting from multiple installed distributors.
2. Include a Web Push library in your application server.
3. Build your own API for communicating between your end user application and your application server. It needs to have the following features:
   • The end user application may query the application server for the VAPID public key (optional, but recommended).
   • The end user application sends the push registration to the application server. This registration includes a push URL, a public key and an auth secret (RFC8291).
   • Note: These values are generally provided by and consumed by the UnifiedPush connector library and the Web Push library. You don’t need to generate them, you only need to send them between your app and server.

If you wish to write a new distributor, to provide push notifications to other applications, you need to look at UnifiedPush specifications, starting with the Definitions.