AppSuite:OX Mail

OX Mail

OX Mail is a native mobile phone app built specifically for smartphone users who already have a valid OX App Suite account. The app is designed to let users access their OX App Suite email environment directly from a smartphone native client.

OX Mail enables users to synchronize mails between a variety of smartphone devices and OX App Suite. OX Mail consists of two elements: The OX Mail component that is built into OX App Suite and the native OX Mail app.

The OX Mail app has been designed specifically for ease-of-use and is available for both iOS and Android.

Please Note: The OX Mail app will be available in September. With this app Open-Xchange has also created a new branding concept for the customers and partners. More information can be found in the chapter Branding/Customization Concept for Partners and Customers

Requirements

Server-side Installation and Configuration

With OX Mail, OX App Suite supports server based PUSH functionality.

Dovecot customers can use the special PUSH plugin without any additional costs. The plugin will be provided via the Dovecot software repository for Dovecot Pro and community edition. Please Note, the installation of the latest Dovecot v2.2.19 release is required

Please Note: The Open-Xchange package 'open-xchange-push-imapidle' which provides mail push functionality by using the IMAP IDLE command to generate push events when new mail arrives, is not officially supported with OX Mail (app).

If you are not using the Dovecot Push Plugin your mail backend has to actively notify the Open-Xchange middleware servers of new emails. This might require the creation of an additional OX middleware plugin to receive those notifications. For further details please contact your assigned pre-sales / prof. services contact.

Please Note, the installation of the latest OX App Suite version is required.

You will finde the client requirements under OX Mail requirements

Key Benefits

• Supports email PUSH notification for personal Inbox – emails show up immediately on the device
• Quick and easy to set up with the start-up wizard
• Intuitive, simple to use, design
• Familiar smartphone experience
• Available for both iOS and Android – download app from App Store for free

A more detailed overview of OX Mail, can be found at: http://software.open-xchange.com/products/mail/doc/OX_Mail_Product_Guide.pdf

Pricing & Availability

OX Mail will be available in September 2015.

This email app is available for both iOS and Android and can be downloaded for free from the corresponding App Stores. Availability will be confirmed by Open-Xchange via the usual communication channels.

Please note: The exact date when the clients become available depends on the approval process of the respective app stores.

The Open-Xchange Middleware components can be downloaded from the respective download repositories as normal.

Please contact your Open-Xchange account manager for further information and pricing details.

Enabling OX Mail for Users

OX Mail is enabled for all users that have the capability com.openexchange.capability.mobile_mail_app

More details about capabilities can be found at AppSuite:Capabilities. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at ConfigCascade.

IMPORTANT: By default, the capability for the OX Mail app is set to false for all users. It can be changed by editing the corresponding capability in the "permissions.properties" config file, or if you need a more fine grained selection of enabled users, you can use the well known provisioning tools / config cascade.

Installation of the Clients

The OX Mail will be available via the different App Stores for iOS and Android by September 2015

OX Mail Server-side Installation and Configuration

This chapter describes how the backend components of OX Mail are installed and configured on the server.

Available packages

OX Mail is available with the following backend packages:

• open-xchange-mobile-push-certificates - Certificates for cloud-based push notifications
• open-xchange-mailapp-backend - The main server components for OX Mail
• open-xchange-mobile-push-plugin - Provides Push functionality

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

Redhat Enterprise Linux 6 or CentOS 6

Add the following repositories to your Open-Xchange yum configuration:

 [open-xchange-backend-updates]
name=Open-Xchange-backend-updates
baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m


 [open-xchange-mail]
name=Open-Xchange-mail
baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/mail/stable/mail/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

 [open-xchange-mailapp]
name=Open-Xchange-mailapp
baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/mail/stable/mailapp/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin

Debian GNU/Linux 6.0 (Squeeze)

Add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/appsuite/stable/backend/updates/DebianSqueeze /

deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/mail/stable/mail/DebianSqueeze /
deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/mail/stable/mailapp/DebianSqueeze /

and run

$ apt-get update
$ apt-get install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin

Debian GNU/Linux 7.0 (Wheezy)

Add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/appsuite/stable/backend/updates/DebianWheezy /

deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/mail/stable/mail/DebianWheezy /
deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/mail/stable/mailapp/DebianWheezy /

and run

$ apt-get update
$ apt-get install open-xchange-mobile-push-certificates open-xchange-mailapp-backend open-xchange-mobile-push-plugin

Setup Description for Mobile Push

Setup of the Open-Xchange Node

The existing push framework of the Open-Xchange Middleware has been extended by the capability to spawn "permanent" listeners for incoming new message deliveries. Up to that point the life cycle for a listener was bound to at least one active session, which is associated with a client that is allowed to receive push notifications.

With introduction of the previously mentioned capability, listeners can be started without the need for an existent session right on the start of an Open-Xchange Middleware node. In addition those permanent listeners are spread approximately even over capable cluster members as - dependent on the underlying implementation - a listener representation may open/hold resources (socket connections) in order to receive notifications about new message deliveries.

To prepare a certain Open-Xchange Middleware node to spawn permanent push listeners the following properties need to be configured in file '/opt/open-xchange/etc/mail-push.properties':

• com.openexchange.push.allowPermanentPush
  This is the general switch to enable/disable support for permanent listeners on a node. Thus needs to be set to "true"
• com.openexchange.push.allowedClient
  Specify the comma-separated list of clients which are allowed to receive notifications about new mails, “open-xchange-mailapp” should be added here if you plan to use it in combination with the new mobile-push feature.
• com.openexchange.push.credstorage.enabled
  As permanent listeners are required to run without an active session, the credential storage can be used to store user credentials in installations that do not support a master authentication to the mail storage Hence, if the property "com.openexchange.mail.passwordSource" (mail.properties) is not set to "global" this property is required to be set to "true"
• com.openexchange.push.credstorage.passcrypt
  This property is required if "com.openexchange.push.credstorage.enabled" is set to "true". It does specify the passphrase to use to symmetrically encrypt the stored credentials. The passphrase is required to be equal on each cluster member.
• com.openexchange.push.credstorage.rdb
  Once the credential storage is enabled, Open-Xchange offers two ways of storing the user-associated login/password combination. In cluster memory (default) or persisted to database. While the first way ensures that no user credentials are persisted nowhere in the Open-Xchange installation, it has the big disadvantage the stored credentials are gone once the last cluster members gets shut-down. Therefore there is also the possibility to store the credentials inside the database. Of course, no matter where the credentials are stored, they are encrypted using the value from com.openexchange.push.credstorage.passcrypt" property

With setting the properties above the configuration on the Open-Xchange Middleware node is prepared to spawn permanent listeners.

Now an appropriate push bundle/package needs to be installed that supports spawning permanent listeners. Currently Open-Xchange ships with three implementations:

• open-xchange-push-dovecot
• open-xchange-push-imapidle (Not recommended, therefore disabled for IMAP-IDLE by default. com.openexchange.push.imapidle.supportsPermanentListeners=false)
• open-xchange-push-mailnotify

Putting all together the following execution flow is taken to decide whether permanent listeners are spawned or not:

To check at any time what listeners are currently running, there is a new command-line tool "/opt/open-xchange/sbin/listpushusers" that outputs the user-id/context-id pair along-side with the information if the listener is of permanent nature or bound to an active session:

An exemplary out put might look like:

~# /opt/open-xchange/sbin/listpushusers
user=249, context=1, permanent=true
user=402, context=1, permanent=true

Setup of the Mobile Push

An appropriate registration for a capable client is required to create a permanent listener for a certain user. As of now, only the Open-Xchange Mail App performs such a registration request to mark the user to have a permanent listener using the newly introduced Mobile Push interfaces of the Open-Xchange Middleware. The Mobile Push feature is installed by the following packages:

• open-xchange-mobile-push
• open-xchange-mobile-push-restricted (Only certificates and licenses)

Simply said the main purpose of the Mobile Push functionality is to register an OSGi event handler converting an incoming OSGi event with topic "com/openexchange/push" to an appropriate native push reaching the mobile device using either

• APN or
• GCM

Client subscription

To be able to do so, the client has to perform a subscribe request against the Mobile Push interface. Such a subscribe call mainly performs two things

1. Storing the data into the database that is needed to initiate a APN/GCM push request
2. Registering & starting a permanent listener in the push framework

Handling of OSGi events

Moreover, the OSGi events with topic "com/openexchange/push" are spread remotely throughout the Open-Xchange cluster. To avoid that each node yields a native push event for the mobile device, the OSGi event handler of the Mobile Push does only consider local events. This fact implies that each node that broadcasts OSGi events with topic "com/openexchange/push" is required to have the open-xchange-mobile-push packages installed; otherwise the OSGi event is not handled.

Mobile Push configuration

The setup of the Mobile Push functionality includes proper configuration of the communication with the APN/GCM services, which is performed in file 'mobilepushevent.properties':

• com.openxchange.mobilepush.events.gcm.enabled
  General switch to enable/disable communication with GCM service
• com.openxchange.mobilepush.events.gcm.key
  Specifies the GCM key in order to authenticate against the GCM service and to forward push messages to that service. Required if "com.openxchange.mobilenotifier.events.gcm.enabled" is "true" and you want to use a different key than provided by open-xchange-mobile-push-restricted. Otherwise the key from open-xchange-mobile-push-restricted is used.
• com.openxchange.mobilepush.events.apn.ios.enabled
  General switch to enable/disable communication with APN service
• com.openxchange.mobilepush.events.apn.ios.keystore
  Specifies the path to the local keystore file (PKCS #12) containing the APNS certificate and keys for the iOS application. Required if "com.openxchange.mobilepush.events.apn.ios.enabled" is "true" and you want to use a different certificate than provided by open-xchange-mobile-push-restricted. Otherwise the certificate from open-xchange-mobile-push-restricted is used.
• com.openxchange.mobilepush.events.apn.ios.password
  Specifies the password used when creating the referenced keystore containing the certificate of the iOS application. Note that blank or null passwords are in violation of the PKCS #12 specifications. Required if "com.openxchange.mobilepush.events.apn.ios.enabled" is "true" and you want to use a different certificate than provided by open-xchange-mobile-push-restricted.

Setup of the Dovecot Push

Dovecot Push plug-in requires METADATA support on Dovecot side, but it should only be enabled for OX IMAP sessions and not for any other IMAP clients directly. Enabling can be done with e.g. the remote directive "remote 1.2.3.0/24 { imap_metadata = yes }" and specifying the IP ranges of OX. Metadata configuration is also described in the article http://wiki2.dovecot.org/ImapMetadata. Please note, the mail_attribute_dict setting also needs to be defined.

The following picture should demonstrate how the overall communication flow between Mail App, Open-Xchange Middleware, and the Dovecot Push plug-in takes place. That communication flow requires the "open-xchange-push-dovecot" package to be installed on the Open-Xchange Middleware nodes and the Dovecot "http-notify" plug-in.

Once the Open-Xchange Mail App is installed on the user’s mobile device and it is allowed to show notifications about a new message delivery, the Mail App performs a subscription call to the Open-Xchange Middleware Servers using a fully authenticated session.

When the "open-xchange-push-dovecot" package is installed, the previous subscribe call requests it to spawn a permanent listener. Such a listener simply tells the Dovecot server to notify about new message delivery events for the associated user by executing a special SETMETADATA command. Hence, it does not open or use any resources other than firing a single IMAP command to the Dovecot IMAP Server.

Whenever a "new message delivery" event occurs, the Dovecot Server performs a HTTP callback against a configurable HTTP end-point of the Open-Xchange Middleware providing crucial information about the newly delivered message with a simple JSON body. That incoming HTTP callback is then turned into an appropriate OSGi event with topic "com/openexchange/push".

That event is in turn handled by the Mobile Push event handler, which uses the event’s information to request an APN/GCM push to the mobile device.

Configuration of Dovecot "http-notify" plug-in

To use push notifications, both the "notify" and the "push_notification" plugins need to be activated. For LMTP delivery, this is required:

protocol lmtp {
  mail_plugins = $mail_plugins notify push_notification
}

If you also want push notifications to work for LDA-based delivery, you would need additional configuration:

protocol lda {
  mail_plugins = $mail_plugins notify push_notification
}

The HTTP end-point (URL + authentication information) to use is configured in the Dovecot configuration file. The appropriate configuration options will contain the HTTP URL denoting the end-point to connect to as well as the authentication information for Basic Authentication as configured by properties "com.openexchange.rest.services.basic-auth.login" and "com.openexchange.rest.services.basic-auth.password". The URL to configure in Dovecot configuration follows this pattern.

<http|https> + "://" + <login> + ":" + <password> + "@" + <host> + ":" + <port> + "/preliminary/http-notify/v1/notify"

E.g.

plugin {
 push_notification_driver = ox:url=http://login:pass@node1.domain.tld:8009/preliminary/http-notify/v1/notify
}

Furthermore, it is also possible to specify more than one HTTP end-point to connect to if a new message delivery occurs. Thus the configuration section mentioned above may be extended by additional "push_notification_driver" entries; e.g. push_notification_driver2, push_notification_driver3, etc.

Please note that the path "/preliminary/http-notify/v1/notify" denotes the internal REST API of the Open-Xchange Middleware, which is not publicly accessible. The administrator can decide whether to add that path to the Apache configuration (see also AppSuite:Apache_Configuration and AppSuite:Grizzly) through a Location/ProxyPass directive:

<Location /preliminary>
    Order Deny,Allow
    Deny from all
    # Only allow access from servers within the network. Do not expose this
    # location outside of your network. In case you use a load balancing service in front
    # of your Apache infrastructure you should make sure that access to /preliminary will
    # be blocked from the internet / outside clients. Examples:
    # Allow from 192.168.0.1
    # Allow from 192.168.1.1 192.168.1.2
    # Allow from 192.168.0.
    ProxyPass /preliminary balancer://oxcluster/preliminary
</Location>

In case the "user=" sent by OX in the push_notification_driver url data does not match the IMAP login of a user, Dovecot ignores it. This can be overridden by defining "user_from_metadata" in the push_notification_driver url, e.g.

 push_notification_driver = ox:url=http://example.com/ user_from_metadata

Integrated Branding/Customization Concept for Partners and Customers

With OX Mail it is also possible for customers and partners to add branding elements to the app. During the installation of the app a user is presented with a list of preconfigured providers. When a provider is selected the app is automatically setup and branded for that provider.

For both design reasons, as well as app store restrictions, branding in this context means:

• The app design is “Super Flat”. This means there are not many elements that can be, or need to be, styled in order to match a particular brand.
• The app does not contain or use any logos of any sort.
• At install time the app uses a startup wizard in combination with a hosted configuration service. The wizard gives the end user the option to select a provider from a list. When this is done the app will retrieve the branding information from the configuration service and changes its theme accordingly.

Branding / Customization Process

In order to participate you will need to provide specific information such as:

• Confirmation that you are running OX App Suite 7.6.2 including the latest patch.
• A full URL where your OX App Suite service can be reached by a web client.
• Two test accounts on your OX App Suite service, where we can verify that the OX App Suite system works as expected.
• A “logo” and “name” of your service. This information will be used in the app itself.
• Optional: A preferred color (CI color) that Open-Xchange will use for the app if a user chooses their service from the provider list.

Steps

1. Please download the Questionnaire from Open-Xchange Download Server
2. Please fill out the Questionnaire and send it to your Open-Xchange account manager.
3. Open-Xchange will check the data. If all information are available, Open-Xchange will add your personal brand to the live OX Mail app. Please Note: The exact date when your brand becomes available depends on the approval process and could take 5 to 10 days. Open-Xchange won't communicate an exact date. Please check by your self.