Introduction

In a multi tenant environment custom features have to be enabled for certain tenants that should not be available for others or simply different from the server settings. To enable this behavior without providing a distinct environment for each tenant, the server admin has the ability to provide a configuration file, the as-config.yml.

This file is loaded during server start and provides the following features.

Content

Example content:

# Override certain settings
default:
    host: all
    contact: ''

host*.mycloud.net:
    hostRegex: host.*\.mycloud\.net
    someRegexHostKey: someRegexHostValue

# Override certain settings for certain hosts
host1.mycloud.net:
    host: host1.mycloud.net
    pageTitle: 'Professional Webmail OX '
    productName: 'Professional Webmail OX'
    pageHeaderPrefix: ''
    pageHeader: ''
    signinTheme: 'host1.mycloud.net'
    contact: 'E-Mail: cloudservice@host1-support.de'
    languages:
        de_DE: Deutsch
    locales:
        de_DE: Deutsch (Deutschland)
        de_AT: Deutsch (Österreich)
        de_CH: Deutsch (Schweiz)
    notificationMails:
        button:
            textColor: '#ffffff'
            backgroundColor: '#3c61aa'
            borderColor: '#356697'
        footer:
            text: 'Footer text'

host2.mycloud.net:
    host: host2.mycloud.net
    pageTitle: 'OXaaS'
    productName: 'OX as a Service'
    pageHeaderPrefix: 'OX'
    pageHeader: 'Cloud Service'
    forgotPassword: false
    languages: all
    notificationMails:
        button:
            textColor: '#ffffff'
            backgroundColor: '#3c61aa'
            borderColor: '#356697'

host3.mycloud.net:
    host: host3.mycloud.net
    productName: 'OX Cloud'
    pageTitle: 'OX Cloud'
    pageHeaderPrefix: 'OX Cloud'
    pageHeader: ''
    contact: 'Please contact your service provider'
    signinTheme: 'host3.mycloud.net'
    notificationMails:
        button:
            textColor: '#000000'
            backgroundColor: '#ffffff'
            borderColor: '#000000'
        footer:
            image: 'custom_logo.png'
            text: 'Footer text'

Default features

In the first part of the file the admin can set default values for certain properties. To apply them to all hosts on the system the host: all value has to be set.

Custom host features

The second part holds all custom host configuration and addresses each host by the host property. If this property is missing, the following custom configurations will not be applied. This parameter also accepts wildcards, to apply certain features by default to a group of hosts. For more information see the Wildcards chapter for more information on this topic.

Sharding subdomains

For request distribution purposes, the administrator can configure an array of sharding subdomains. If set up correctly, those subdomains will primarily be used to load image previews in drive. This way, requests needed to keep the UI under full functionality are detached from those requests. Those subdomains have to be registered inside the apache configuration. Example:

<VirtualHost *:80>
    ServerName sharding.appsuite.com
</VirtualHost>

Those subdomains can point to the same server, which handles all other requests or another distinct server. This has to be configured inside the hosts file. Inside the as-congig.yml a host has to provide the following parameter to enable sharding:

shardingSubdomains: 
    - sharding.appsuite.com/appsuite/api

Please note, that the full API path has to be provided. This way the administrator is capable of configuring a custom api location. The same cookies will be used for all requests on the main domain and all subdomains provided. Attention, even a single sharding subdomain has to be provided as an array.

Attention

When using sharding subdomains for custom hosts, cookie domains should be disabled to make sure that cookies are used correctly.

com.openexchange.cookie.domain.enabled=false

External login page

The login mask can reside on an external server i. e., not directly located in the domain of the Open-Xchange machines. If an administrator wants to use an external login page, the following steps have to be applied.

HTML

The Open-Xchange HTTP API (Form login) has a function to create a session from external. The full detailed explanation how the HTML form is used and errors can be handled can be found here: OX Session Formlogin

Redirect to custom login

Users can still access the original product login site. If this is not wanted the following Apache configuration for your VirtualHost can be used to redirect all requests to your custom login page:

before 7.8.0:

RewriteEngine On
RewriteRule ^/appsuite/signin /custom-login.html [R]

Since 7.8.0: It can be configured directly in /opt/open-xchange/etc/as-config.yml

# Override certain settings
default:
    host: all
    loginLocation: 'http://example.com/appsuite/mycustomlogin.html'

Note: you need to have the right syntax (like leading spaces) in the .yml file.

It is possible to have different login pages for different domains, just add another section with a different host: line.

Setting custom login as logout location

If users should be directed to the custom login form after logout from App Suite the following property can be set globally somewhere in /opt/open-xchange/etc/settings/. Either create a new properties file or add the option in any existing one. For more complex setups e.g. with different brands please check out how to set this property in context or user scope which is explained here.

io.ox/core//customLocations/logout=https://login.example.com

For cases where only one custom login page exists for all users it's also recommended to set

logoutLocation: 'https://login.example.com/'

in /opt/open-xchange/etc/as-config.yml. This setting takes effect for example if an autologin session is expired. as-config.yml itself defines settings in dependence of the hostname configured for the Open-Xchange access.

Theming the login page

A customized theme for the default login page for an appsuite installation and also the configuration of different ones for different hostnames is possible by referencing those themes inside the as-config.yml.

style.less

To apply a theme to the login page you just add the relevant snippets to the style.less file like for a normal theme and include the logos and artifacts in the theme directory.

Here are some examples of CSS selectors which can be addressed on the login page:

#io-ox-login-username
#io-ox-login-screen .btn-primary
#io-ox-login-screen .btn-primary:hover
#io-ox-login-header-prefix
#io-ox-login-header-label
#io-ox-login-container
.wallpaper
body.down #io-ox-login-container .alert.alert-info
.language-delimiter
#io-ox-copyright

as-config property

To actually apply the above definition the theme needs to be specified in the file /opt/open-xchange/etc/as-config.yml:

signinTheme: MYTHEME

As as-config.yml can have different configuration based on different hostnames a multi branded configuration can be applied as well.

Other login page properties

This list provides some other properties, that influence the login page itself or its behavior.

Theming the about dialog

This dialog can be accessed from inside the Appsuite and displays some general information about the product along side with some contact informations.

Other properties

Notification mails

It is possible to define the basic style of all notification mails for a host. When you do so, you have to override all mandatory settings. Example

notificationMails:
    #mandatory
    button:
        textColor: '#ffffff'
        backgroundColor: '#3c61aa'
        borderColor: '#356697'
    #Optional    
    footer:
        image: 'ox_logo_claim_blue_small.png'
        text: 'Footer text'

Wildcards

Whenever the administrator needs to define a set of features for a set of hosts with similar domain names, he can use Regex and * wildcards as part of a host parameter and set properties for this set of hosts. host*.mycloud.net: hostRegex: host.*\.mycloud\.net someRegexHostKey: someRegexHostValue

In the example under the Content chapter, the value of someRegexHostKey would apply to all three following hosts.