Difference between revisions of "AppSuite:OX Mail"

(Configuration of Dovecot "http-notify" plug-in)
(Configuration of Dovecot "http-notify" plug-in)
Line 204: Line 204:
 
  }
 
  }
  
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:Grizzly]]) through a Location/ProxyPass directive:
+
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 [[AppSuite:Apache_Configuration]] (see also [[AppSuite:Grizzly]]) through a Location/ProxyPass directive:
  
 
  <Location /preliminary>
 
  <Location /preliminary>

Revision as of 08:36, 26 August 2015

Pre-Information - 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 Integrated Branding/Customization Concept for Partners and Customers

Requirements

Server-side Installation and Configuration

With OX Mail, OX App Suite supports server based PUSH functionality. One of the main requirements for push functionality is the use of the Dovecot mail backend. In addition the following conditions should be met:

  • Dovecot Customers with less than 100,000 users: Customers can use the special PUSH plugin without any additional costs. The plugin will be provided via the Open-Xchange software repository for customers with a valid Open-Xchange App Suite license.
  • Dovecot Pro Customers with more than a 100,000 users: PUSH plugin use is covered under this license without incurring additional costs.
  • 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.

Requirement System / Platform / User Interface / Server Capability
   
OX App Suite OX App Suite v7.6.2 (latest patch version 2569 W27) and push certificates from restricted mail repository.
OX Mail (App) for iOS Apple iOS 7, Apple iOS 8 (tablet support in a later version)
OX Mail (App) for Android Smartphone on Android 4.2 or later (tablet support in a later version)
Server Capability Ensure that all user who should get access to the Mail App have the capability com.openexchange.capability.mobile_mail_app

Key Benefits

  • Supports email PUSH notification – 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
  • Low support requirements

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

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.

If you would like to try out the OX Mail app or participate in our launch partner program please contact your Open-Xchange Sales rep.

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.

Pricing & Availability

OX Mail will be available in August 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 Open-Xchange Sales 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 August 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-mail - The main server components for OX Mail
  • open-xchange-mobile-push-restricted - Restricted components, including prerequisites for cloud-based push notifications

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

Install on OX AppSuite

Debian GNU/Linux 8.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/updates/DebianJessie/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/updates/DebianJessie/ /

and run

$ apt-get update
$ apt-get install open-xchange-mail open-xchange-mobile-push-restricted

Debian GNU/Linux 9.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/updates/DebianStretch/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/updates/DebianStretch/ /

and run

$ apt-get update
$ apt-get install open-xchange-mail open-xchange-mobile-push-restricted

SUSE Linux Enterprise Server 12

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox

If you have a valid maintenance subscription, please run the following command and add the ldb account data to the url so that the most recent packages get installed:

$ zypper ar https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/updates/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-mail open-xchange-mobile-push-restricted

RedHat Enterprise Linux 6

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://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
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-mail open-xchange-mobile-push-restricted

RedHat Enterprise Linux 7

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-mail open-xchange-mobile-push-restricted

CentOS 6

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://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
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/updates/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-mail open-xchange-mobile-push-restricted

CentOS 7

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/ox.repo

[ox]
name=Open-Xchange
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# [ox-updates]
# name=Open-Xchange Updates
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/updates/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-mail open-xchange-mobile-push-restricted


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:

Ox mail push configuration 2.png

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:

Ox mail push configuration 3.png

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. Please read this article for Dovecot METADATA configuration: http://wiki2.dovecot.org/ImapMetadata

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.

Ox mail push configuration 4.png

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

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_backend = ox:url=http://login:pass@node1.domain.tld:8009/preliminary/http- notify/v1/notify
}

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 AppSuite:Apache_Configuration (see also 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>