AppSuite:OX Guard: Difference between revisions
(InterOX / mailmapping) |
|||
Line 322: | Line 322: | ||
The required DNS entry to allow external senders to get the public key has to look like: | The required DNS entry to allow external senders to get the public key has to look like: | ||
_oxguard.example.com TXT "https://ox. | _oxguard.example.com TXT "https://ox.hoster.com/appsuite/api/oxguard" | ||
Such an entry needs to exist for all mail domains (not only the OX host domain obviously). | |||
== Clustering == | == Clustering == |
Revision as of 08:36, 20 November 2014
OX Guard
OX Guard is a security solution that provides protection for email communications and files. Fully integrated with both OX as a Service and standard OX App Suite installations, it allows users to send and read encrypted messages and store and share encrypted files – and requires no additional setup or knowledge. OX Guard offers a simple way to increase security by limiting the opportunity for unauthorized access while data is en-route or in-storage, creating extra peace of mind.
This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:
- To setup a single server installation
- To setup a single Guard instance on an existing Open-Xchange installation, no cluster
- To use the database service on the existing Open-Xchange installation for Guard, no replication
- To provide a basic configuration setup, no mailserver configuration
Key features
- Simple security at the touch of a button
- Provides user based security - Separate from provider
- Supplementary security to Provider based security - Layered
- Powerful features yet simple to use and understand
- Security - Inside and outside of the OX environment
- Email and Drive integration
- Uses proven PGP security
Availability
If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.
Requirements
Please review following URL for remaining requirements
Please review OX Guard Requirements for a full list of requirements.
Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment without having any of the other Open-Xchange App Suite core services installed. OX App Suite v7.6.0 or later is required to operate this extension both in a single or multi server environments.
Prerequisites:
- Open-Xchange REST API
- Grizzly HTTP connector (open-xchange-grizzly)
- A supported Java Virtual Machine (Java 7)
- An Open-Xchange App Suite installation v7.6.0 or later
- Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article Updating OX-Packages explains how that can be done.
Please Note
OX Guard version 1.0 supports branding / theming using the configuration cascade, defining a templateID for a user or context. Additional details will be provided in customization documentation
Download and Installation
General
The installation of the open-xchange-rest package which is required for Guard will eventually execute database update tasks if installed and activated. Please take this into account.
Redhat Enterprise Linux 6 or CentOS 6
If not already done, add the following repositories to your Open-Xchange yum configuration:
[open-xchange-appsuite-stable-guard-backend] name=Open-Xchange-appsuite-stable-guard-backend baseurl=https://software.open-xchange.com/products/appsuite/stable/guard-backend/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-appsuite-stable-guard-ui] name=Open-Xchange-appsuite-stable-guard-ui baseurl=https://software.open-xchange.com/products/appsuite/stable/guard-ui/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
and run
$ yum update $ yum install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static
Debian GNU/Linux 7.0
If not already done, add the following repositories to your Open-Xchange apt configuration:
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/guard-backend/DebianWheezy /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/guard-ui/DebianWheezy /
and run
$ apt-get update $ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static
SUSE Linux Enterprise Server 11
Add the package repository using zypper if not already present:
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/guard-backend/SLES11 appsuite-stable-guard-backend
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/guard-ui/SLES11 appsuite-stable-guard-ui
and run
$ zypper ref $ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static
Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:
$ update-alternatives --config java
Now select the Java 1.7 JRE, example:
There are 2 alternatives which provide `java'.
Selection Alternative ----------------------------------------------- * 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java + 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java Press enter to keep the default[*], or type selection number: 2 Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.
Update OX Guard
Redhat Enterprise Linux 6 or CentOS 6
If not already done, add the following repositories to your Open-Xchange yum configuration:
[open-xchange-appsuite-7.6.0-guard-backend-updates] name=Open-Xchange-appsuite-7.6.0-guard-backend-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.6.0/guard-backend/updates/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-appsuite-7.6.0-guard-ui-updates] name=Open-Xchange-appsuite-7.6.0-guard-ui-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.6.0/guard-ui/updates/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
and run
$ yum update $ yum upgrade
After the new packages are installed, the guard process needs a restart:
$ /etc/init.d/open-xchange-guard restart
Debian GNU/Linux 7.0
If not already done, add the following repositories to your Open-Xchange apt configuration:
deb https://software.open-xchange.com/products/appsuite/7.6.0/guard-backend/updates/DebianWheezy /
deb https://software.open-xchange.com/products/appsuite/7.6.0/guard-ui/updates/DebianWheezy /
Then run
$ apt-get update $ apt-get dist-upgrade
If you want to see, what apt-get is going to do without actually doing it, you can run:
$ apt-get dist-upgrade -s
After the new packages are installed, the guard process needs a restart:
$ /etc/init.d/open-xchange-guard restart
SUSE Linux Enterprise Server 11
Add the package repository using zypper if not already present:
$ zypper ar https://software.open-xchange.com/products/appsuite/7.6.0/guard-backend/updates/SLES11 appsuite-7.6.0-guard-backend-updates
$ zypper ar https://software.open-xchange.com/products/appsuite/7.6.0/guard-ui/updates/SLES11 appsuite-7.6.0-guard-ui-updates
and run
$ zypper dup -r appsuite-7.6.0-guard-backend-updates $ zypper dup -r appsuite-7.6.0-guard-ui-updates
You might need to run
$ zypper ref
to update the repository metadata before running zypper up.
After the new packages are installed, the guard process needs a restart:
$ open-xchange-guard restart
Configuration
The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file guard.properties located in /opt/open-xchange/guard/etc. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options.
$ vim /opt/open-xchange/guard/etc/guard.properties
Open-Xchange config_db host - Guard will establish a connection to the config_db
com.openexchange.guard.configdbHostname=localhost
Guard database for storing user keys
com.openexchange.guard.oxguardDatabaseHostname=localhost
Username and Password for the two databases above
com.openexchange.guard.databaseUsername=openexchange com.openexchange.guard.databasePassword=db_password
Open-Xchange REST API host
com.openexchange.guard.restApiHostname=localhost
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below)
com.openexchange.guard.restApiUsername=apiusername com.openexchange.guard.restApiPassword=apipassword
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients
com.openexchange.guard.externalEmailURL=URL_TO_OX
Configure services
Apache
Configure the mod_proxy_http module by adding the Guard API.
Redhat Enterprise Linux 6 or CentOS 6
$ vim /etc/httpd/conf.d/proxy_http.conf
Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11
$ vim /etc/apache2/conf.d/proxy_http.conf
<Proxy balancer://oxguard> Order deny,allow Allow from all
BalancerMember http://localhost:8080/oxguard timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1 ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON SetEnv proxy-initial-not-pooled SetEnv proxy-sendchunked </Proxy>
ProxyPass /appsuite/api/oxguard balancer://oxguard
Please Note: The Guard API settings must be inserted before the existing “<Proxy /appsuite/api>” parameter.
After the configuration is done, restart the Apache webserver
$ apachectl restart
Open-Xchange
Please remove comments in front of the following settings to the configuration file guard.properties on the Open-Xchange backend servers:
$ vim /opt/open-xchange/etc/guard.properties
# OX GUard general permission, required to activate Guard in the AppSuite UI. com.openexchange.capability.guard=true # Default theme template id for all users that have no custom template id configured. com.openexchange.guard.templateID=0
Configure the API username and password that you assigned to Guard in the server.properties file
$ vim /opt/open-xchange/etc/server.properties
# Specify the user name used for HTTP basic auth by internal REST servlet com.openexchange.rest.services.basic-auth.login=apiusername # Specify the password used for HTTP basic auth by internal REST servlet com.openexchange.rest.services.basic-auth.password=apipassword
Restart the OX backend
$ /etc/init.d/open-xchange restart
SELinux
Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8080, which is where the Guard backend service listens to. In order to allow localhost connections to 8080 execute the following:
$ setsebool -P httpd_can_network_connect 1
Initiating the Guard database and key store
Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the Guard databases. The administration script also takes care of the creation of the master keys and the master password file in /opt/open-xchange/guard. The initiation only needs to be done once for a multi server setup, for details please see “Optional / Clustering”.
/opt/open-xchange/guard/sbin/guard init
Please Note: It is important to understand that the master password file located at /opt/open-xchange/guard/oxguardpass is required to reset user passwords, without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table.
Start Guard
The services have been configured and the database has been initiated, it's time to start Guard
$ /etc/init.d/open-xchange-guard start
Enabling Guard for Users
Guard provides two capabilities for users in the environment:
- Guard Mail: com.openexchange.capability.guard-mail
- Guard Drive: com.openexchange.capability.guard-drive
Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:
Guard Mail:
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true
Guard Drive:
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true
Please Note: Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the guard.properties file on the OX bakend
Optional
SSL Configuration
Per default the connection between the Guard backend and the configured Open-Xchange REST API host is unencrypted. Even though that Guard will never transmit unencrypted emails to or from the REST API you can optionally encrypt the whole communication between those two components by using SSL. To enforce Guard to use SSL in the communication between those two components enable the follwing configuration in Guard configuration file.
$ vim /opt/open-xchange/guard/etc/guard.properties
com.openexchange.guard.backend_ssl=true
The Guard backend is most commonly placed behind a load balancer (APACHE or other) and defaults to HTTP for incoming and outgoing traffic, using the load balancer to do SSL with the users. If you want Guard to use SSL for all communications, you need to set up the SSL key to use.
Please note that you have to provide access to the certificates.
com.openexchange.guard.useSSL: true com.openexchange.guard.SSLPort: 8443 com.openexchange.guard.SSLKeyStore: //keystore location// com.openexchange.guard.SSLKeyName: //alias name here// com.openexchange.guard.SSLKeyPass: //ssl password//
Please Note: Enabling SSL might decrease performance and/or create more system load due to additional encoding of the HTTP streams.
Recipient key detection
Local
By default Guard works transparently for context internal users but in case the recipient is not in the same OX context, Guard will create a guest account and create a local keypair for the recipient. This happens unless Guard can find the user on the local (or remote - see "External") OX Guard system where the existing public key would be used making it possible to work transparently within OX without the guest interface.
To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the com.openexchange.mailmapping.MailResolver class.
External
OX Guard can also detect if the external recipient's account is also supported by its own Guard system in case the feature is publically announced via DNS.
The required DNS entry to allow external senders to get the public key has to look like:
_oxguard.example.com TXT "https://ox.hoster.com/appsuite/api/oxguard"
Such an entry needs to exist for all mail domains (not only the OX host domain obviously).
Clustering
You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.
MySQL
The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL my.cnf:
bind = 0.0.0.0
This allows the Guard backend to bind to the MySQL host which is configured in the guard.properties file with com.openexchange.guard.configdbHostname. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the mysql client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:
GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;
Apache
OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via mod_proxy we need to add a servlet called "preliminary" to proxy_http.conf, example based on a clustered mod_proxy configuration:
<Location /preliminary> Order Deny,Allow Deny from all # Only allow access from Guard 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>
Make sure that the balancer is properly configured in the mod_proxy configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose /preliminary to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to /preliminary from WAN to restrict access to the servlet to internal network services only.
Now add the OX Guard BalancerMembers to the oxguard balancer configuration (also in proxy_http.conf) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.
If the Apache server is a dedicated server / instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):
$ apt-get install open-xchange-guard-ui-static
Open-Xchange
Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:
$ vim /opt/open-xchange/etc/server.properties
and set:
com.openexchange.IPCheck=false
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):
$ apt-get install open-xchange-guard-ui
Restart the Open-Xchange service afterwards.
OX Guard
After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in /opt/open-xchange/guard/etc/guard.properties:
com.openexchange.guard.restApiHostname=apache.example.com
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the serblet /preliminary on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into /opt/open-xchange/guard/etc/guard.properties:
com.openexchange.guard.oxBackendPort=80
Please also change all settings in regards to MySQL like com.openexchange.guard.configdbHostname, com.openexchange.guard.oxguardDatabaseHostname, com.openexchange.guard.databaseUsername or com.openexchange.guard.databasePassword. Afterwards restart the OX Guard service and check the logfile if the OX Guard backend is able to connect to the configured REST API.