Open-Xchange - User contributions [en]

Caldav carddav Bundles

2019-12-03T08:50:09Z

Daniel.becker: Deprecated with 7.10.3

This article is valid until the version 7.10.2 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/latest/middleware/miscellaneous/caldav_carddav.html

= Installation and Configuration of the CalDAV- and CardDAV-bundles =

The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS Calendar and Address Book clients.

CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way.

== User Guide and Client Configuration ==
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].

== Webserver Configuration ==
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDAV configuration in Mac OS X Mavericks and enter the path by hand. If you just want to enter the hostname, SSL is required. The same applies to iOS7 where SSL is always required.

=== Alternative 1: Apache vhost (recommended) ===
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDAV configuration are placed inside their own virtual hosts sections.'''.

Please add the following entries before your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:

# NameVirtualHost directive no longer has any effect since Apache >=2.4
# uncomment only for Apache Versions <2.4
#NameVirtualHost *:80
<VirtualHost *:80>
ServerName dav.<MYSERVER.TLD>
ErrorLog /tmp/dav.err.log
TransferLog /tmp/dav.access.log

<Proxy balancer://oxserver-sync>
Order deny,allow
Allow from all

# for grizzly http service
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1
# uncomment this entry if you have a clustered setup and want to use the other nodes too
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass / balancer://oxserver-sync/servlet/dav/

</VirtualHost>

If you use this method, you have to make sure that <code>dav.<MYSERVER.TLD></code> is reachable, your DNS configuration needs an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to <code>/tmp</code>.

Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.

=== Alternative 2: Apache useragent detection ===
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.

$ vi <your-ox-site-configuration-file>

RewriteEngine On
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]
RewriteCond %{HTTP_USER_AGENT} Reminders [OR]
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]
RewriteCond %{HTTP_USER_AGENT} DAVx5 [OR]
RewriteCond %{HTTP_USER_AGENT} "DAVdroid" [OR]
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]
RewriteCond %{HTTP_USER_AGENT} Address\ Book [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]
RewriteCond %{HTTP_USER_AGENT} CalDAV%20Sync%20Adapter [OR]
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]
RewriteCond %{HTTP_USER_AGENT} "eM Client" [OR]
RewriteCond %{HTTP_USER_AGENT} "OX Sync" [OR]
RewriteCond %{HTTP_USER_AGENT} CalDav [OR]
RewriteCond %{HTTP_USER_AGENT} CoreDAV
RewriteCond %{HTTP_USER_AGENT} "!Open-Xchange Calendar Feed Client"
RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service

'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.

'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule.

== Autodiscovery ==

By providing some DNS service name registrations for your domain and adding an additional rewrite-rule to the webserver's configuration, it's possible for some clients to automatically discover the account settings by just providing the user's e-mail address and password. The procedure is specified in [http://tools.ietf.org/html/rfc6764 RFC 6764].

The following example illustrates the DNS entries where MYSERVER.TLD would be the domain name of the ox-server, both for CalDAV and CardDAV via HTTP and HTTPS on the virtual host dav.MYSERVER.TLD:

_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.

Additionally, a rewrite-rule similar to the following example should be added to the webserver configuration of the virtual host to enable the bootstrapping process. The rewrite target must be the root of your DAV server.
The well-known aliases should be added for your DAV vhost and on the vhost serving the host matching the mail domain:

RewriteEngine On
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav
RewriteRule (.*) / [L,R]

In the case of not serving the DAV service on the vhost root additionally some DNS TXT records are recommended:

_caldavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_caldav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav
_carddav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav

== Installation on OX App Suite ==

=== Debian GNU/Linux 7.0 (valid until v7.8.2)===

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/7.8.2/backend/DebianWheezy/ /

# 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/7.8.2/backend/updates/DebianWheezy/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== 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/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/DebianJessie/ /

and run

$ apt-get update
$ apt-get install open-xchange-dav

=== SUSE Linux Enterprise Server 11 (valid until v7.8.2)===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 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/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-dav

=== 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/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/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-dav

=== 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/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/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===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/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/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===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/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/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

===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/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/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-dav

== CalDAV Configuration ==

The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:

===com.openexchange.caldav.enabled===
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:

/opt/open-xchange/etc/caldav.properties:
com.openexchange.caldav.enabled=false

/opt/open-xchange/etc/contextSets/caldav.yml
premium:
com.openexchange.caldav.enabled: true
withTags: ucInfostore

This means: In general CalDAV is turned off, but using the <code>contextSets</code> feature of the config cascade it is turned on for everyone that has infostore access.

===com.openexchange.caldav.tree===
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.

===com.openexchange.caldav.interval.start===
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months".

===com.openexchange.caldav.interval.end===
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years".

===com.openexchange.caldav.url===
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].

== CardDAV Configuration ==

The following configuration options are available in the configuration files carddav.properties and carddav.yml:

===com.openexchange.carddav.enabled===
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:

/opt/open-xchange/etc/groupware/carddav.properties:
com.openexchange.carddav.enabled=false

/opt/open-xchange/etc/groupware/contextSets/carddav.yml
premium:
com.openexchange.carddav.enabled: true
withTags: ucInfostore

===com.openexchange.carddav.ignoreFolders===
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.

===com.openexchange.carddav.tree===
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.

===com.openexchange.carddav.exposedCollections===
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'.

===com.openexchange.carddav.userAgentForAggregatedCollection===
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive.

===com.openexchange.carddav.reducedAggregatedCollection===
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.

[[Category: Clients]]
[[Category: Administrator]]
[[Category: AppSuite]]

AppSuite:Sharing and Guest Mode

2018-12-07T13:37:49Z

Daniel.becker:

{{VersionFrom|7.8.0}}

This article is valid from 7.8.0 to 7.10 and is not updated for newer versions anymore.
For 7.10.1 and onwards you can find the corresponding documentation at https://documentation.open-xchange.com/7.10.1/middleware/components/sharing_guest_mode.html

With the version 7.10.2 the publication mechanism along subscription done to those publications are removed.

__TOC__

== Introduction ==

Starting with v7.8.0, the Open-Xchange server comes with a whole new concept to share contents with external people, allowing guest users to interact with the shared data in the same way as regular groupware users do. This article describes the underlying technical implications and outlines the different use cases.

The main idea behind the new sharing concept is that guest users, i.e. external users without a regular account on the server, should be able to access the shared contents using the existing interfaces, especially the App Suite web interface. On the one hand, this includes consuming the shared data using the App Suite's advanced media viewing capabilities. On the other hand, this enables guests to edit existing as well as to create or upload new content in the groupware. Even real-time collaboration between internal users and guests in OX Documents is possible.

The following chapters cover different topics regarding sharing and guest users and try to describe some technical background and impact where hosters, administrators or integrators might be interested in.

== Creating Shares ==

Basically, creating a share means adding an additional permission entity to the shared folder or item. Previously, this was only possible for "internal" entities, i.e. regular users or user groups. Now, the underlying permission system has been extended to support external entities, which can be either invited guest users, or special "anonymous" guest users who access a shared folder or item via a secret link. Anonymous and invited guest users are explained in more detail below.

Sharing is available for the groupware modules Calendar, Contacts, Tasks and Drive (a.k.a. Infostore/Files). While the latter one also allows "writable" access for invited guest users, folders from the Calendar, Contacts and Tasks module may only be published in "read-only" mode to external guests.

=== Invite Guests ===

To share something to a guest user, it's possible to just add the e-mail address of the invitee as new permission entity for files and folders. The middleware then takes care to provision a new or reuse an existing account for the guest user, and equips him with the required permissions for accessing the contents. So, from a client's point of view, sharing something to a guest user is mostly the same process as sharing something to an internal user or group.

=== Share Links ===

Besides explicitly inviting a guest user to a share, it's also possible to just get a secret link for a folder or item. This will result in an additional "anonymous" guest entity in the permissions of the shared object, and will grant any user with the corresponding share link access the shared contents. To simplify the creation of share links, the clients will offer an additional "wizard" to quickly get a share link for a folder or item. Unlike invited guests which behave much like internal users, anonymous guest entities are strictly bound to the underlying folder or item, i.e. there is at most one anonymous permission entity per file or folder, as well as an anonymous permission entity can only be used for only once.

=== Required Permissions and Capabilities ===

Whether a user is allowed to create share links, invite external guests, or internal groups or users, depends on the following module access permissions and capabilities. Please note that share links no longer require <code>read_create_shared_folders</code> since Open-Xchange v7.8.1; this restriction was removed in order to allow simple publications also for non-groupware accounts, e.g. as defined by the <code>pim</code> or <code>pim_infostore</code> module access combinations.

==== v7.8.0 ====
* Create, update & remove share links: <code>read_create_shared_folders</code>, <code>share_links</code>
* Add, update or remove internal users and group permissions: <code>read_create_shared_folders</code>
* Add, update or remove external guest permissions: <code>read_create_shared_folders</code>, <code>invite_guests</code>

==== v7.8.1 ====
* Create, update & remove share links: <code>share_links</code>
* Add, update or remove internal users and group permissions in modules Calendar, Contacts, Tasks: <code>read_create_shared_folders</code> for personal / <code>edit_public_folders</code> for public folders
* Add, update or remove internal users and group permissions in module Drive: none
* Add, update or remove external guest permissions in modules Calendar, Contacts, Tasks: <code>invite_guests</code>, and <code>read_create_shared_folders</code>, <code>read_create_shared_folders</code> for personal / <code>edit_public_folders</code> for public folders
* Add, update or remove external guest permissions in module Drive: <code>invite_guests</code>

'''''Administrator Notes:'''''

* Existing shares for a guest user or context may be listed using the commandline utility <code>listshares</code>
* The ability to create share links may be controlled via <code>com.openexchange.capability.share_links</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]
* The ability to invite guest users may be controlled via <code>com.openexchange.capability.invite_guests</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]
* The number of allowed share links per user may be specified via <code>com.openexchange.quota.share_links</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]
* The number of allowed guest invitations per user may be specified via <code>com.openexchange.quota.invite_guests</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]
* Both quotas can also be set on a per-context basis via a 'changecontext' call and the <code>quota-module</code> and <code>quota-value</code> options, see [http://oxpedia.org/wiki/index.php?title=AppSuite:Context_management#changecontext]. The module IDs are accordingly <code>share_links</code> and <code>invite_guests</code>.
* Quotas are always checked per-user, per default both are set to 100. You'll probably want to increase the quota for links when enabling the link mail feature available with OX App Suite 7.8.2.

== Removing Shares ==

The lifetime of shares is implicitly bound to the lifetime of the associated permission of the guest user entity. So, once a permission entity pointing to a (named or anonymous) guest user account is removed from the parent folder or item, this also leads to the removal of the associated share itself. Afterwards, the contents are no longer accessible for the guest user. For shares that were created with a specific expiry date, it is ensured that they can no longer be accessed via their share link after expiring. Additionally, expired shares are cleaned up periodically within a background task.

'''''Administrator Notes:'''''

* Shares may be revoked manually using the commandline utility <code>removeshares</code>
* The interval of the periodic cleanup task can be controlled via <code>com.openexchange.share.cleanup.periodicCleanerInterval</code> in <code>share.properties</code>

== Share Links & Tokens ==

Shares are accessed with a hyperlink that contains the so-called share "token". This 24-byte token uniquely identifies the associated guest account on the system, and carries enough randomness that it can't be guessed. Explicitly invited guest users receive this hyperlink in the invitation mail to a share, while in case of an "anonymous" share where just the link itself was generated, it's up to the sharing user to distribute the link on his own. Besides the token, a share link may contain an additional path that points to the concrete folder and item, which just aids to jump to the shared item in the web interface directly. The following shows an example of a share link:

<code>https://share.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/1/2/ODAxMDY</code>

If a guest user has been invited to more than one share in a context (based on his e-mail address), his individual share token remains equal, so that he will have access to all shared contents in the web interface after following any of the share links he received. However, the additional "path" still points to the concrete item. When inviting more than one guest user to the same share, each recipient will get his own individual share link.

Once the share URL is requested from the server, the associated guest account is looked up and, depending of the guest type, the request is redirected to a specific login screen or directly into the App Suite web interface. More details regarding the different login modes are described at [[#Guest_Login_&_Session_Handling|Guest Login & Session Handling]].

After a share has been revoked (either explicitly, by removing the permission, or if the share is expired), share links can't be accessed any longer, and, after the last share for the guest user was removed, the guest account is removed from the system automatically.

'''''Administrator Notes:'''''

* The share token is stored as user attribute <code>com.openexchange.shareBaseToken</code> in the corresponding guest user account
* The target database schema for a share and the associated guest account is extracted from the context identifier encoded in the share token

== Guest Users ==

As outlined above, guest users are created on demand once something is being shared. We basically distinguish between two types of guest users: Those that were invited explicitly by the sharing user, or "anonymous" guest users that are able to access by visiting the share link. Access for the latter one may optionally be secured with a fixed PIN code.

For both kinds of guest users, a corresponding user account is provisioned dynamically on the system once a new share is created. Such a guest account is handled much similar as an account for a regular user, with the following main exceptions:

* No access to the "Mail" module
* No personal folders
* No access to the "Portal"
* No access to the global address book
* Module access is restricted to only include modules from the actual shares

All those restrictions are configured and enforced using the built-in mechanisms of the Open-Xchange Server, i.e. by a reduced set of capabilities (i.e. module permissions), or by selectively set permission bits in the folder tree for the virtual guest group. This ensures that guest users are only able to access things they explicitly have been invited to, as well as a transparent handling of guest accounts within all subsystems.

'''''Administrator Notes:'''''

* Guest users are stored much similar as regular users in the database (tables <code>user</code>, <code>prg_contacts</code>, <code>user_attribute</code>, <code>user_configuration</code>)
* Additionally, the identifier of the user who (initially) created the guest account is stored in <code>user.guestCreatedBy</code>, i.e. if this column is not <code>0</code>, this entry refers to a guest user
* All service calls and APIs that list or search users have been adjusted to be "guest-aware", i.e. by default, guests users are not included in the output, yet may be included explicitly with additional parameters (namely <code>includeGuests</code> and <code>excludeUsers</code>)
* Service calls and APIs that request data explicitly based on an entity's identifier are also working with guest users, i.e. if a specific idnetifier points to a guest, then the referenced guest data is returned

=== Capabilities ===

Guest users always have the <code>guest</code> capability set. Besides they are generally configured with a limited permission set, that allows them just to work with their shared items. This permission set includes:

{|
!Permission
!Capability
!Details
|-
|<code>deniedportal</code>
|
|No <code>portal</code> capability
|-
|<code>editpublicfolders</code>
|<code>edit_public_folders</code>
|
|-
|<code>readcreatesharedfolders</code>
|<code>read_create_shared_folders</code>
|
|-
|<code>editpassword</code>
|<code>edit_password</code>
|Only for invited guests, not links
|}

Additionally, for every module the guest is having shared items in, the according module permission is granted, e.g. a shared drive folder results in permission <code>infostore</code> and the according capability. Guest users are never allowed to share folders or items on their own, i.e. the capabilities <code>share_links</code> and <code>invite_guests</code> can never be set.

'''''Administrator Notes:'''''

This limited capability set can be extended by configuration. Currently three modes are supported:

{|
!Mode
!Description
|-
|deny_all
|No further capabilities are applied to guest users, except ones that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code>.
|-
|static
|A static list of capabilities is applied to guest users via the <code>com.openexchange.share.staticGuestCapabilities</code> property. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.
|-
|inherit
|All capabilities of the user who "created" the guest, i.e. created the link or initially invited somebody, are applied to the guest user. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.
|}

The mode can be configured via the <code>com.openexchange.share.guestCapabilityMode</code> property in <code>share.properties</code>. This property is config-cascade capable, so it can for example be overridden for certain sets of contexts. The same applies to the <code>com.openexchange.share.staticGuestCapabilities</code> property.

Due to this configuration mechanism it is possible to increase the user experience for guests and even allow some real collaboration. As an '''example''' one could apply the following configuration to allow guests to see preview images of files and edit shared documents with OX Documents:

<pre>com.openexchange.share.guestCapabilityMode = static
com.openexchange.share.staticGuestCapabilities = document_preview, text, spreadsheet, presentation</pre>

=== Anonymous Guest Users ===

If a "share link" is created, this results in an implicit creation of an anonymous guest user account on the server. The "secret" to access the shared contents is the share token itself that is encoded in the generated share link, so that everybody that knows the share link is able to access the shared contents. Optionally, such an anonymous share link may be secured with an additional PIN code. Guest users will be prompted to enter this PIN code when attempting to access the share.

To have a strict separation between different shared contents, each time a folder or item is shared using the "Get a link" method, a designated anonymous guest account for this share is used. Consequently, each time such an anonymous share is revoked, this guest account is terminated again with no further delay. Additionally, such an anonymous guest entity can only be applied to the permission set of the folder or item the original link was created for, i.e. it's not possible to add more shared contents to an anonymous guest - in contrast to an invited, named guest user.

Besides the common restrictions for guest accounts outlined above, the following applies for anonymous guest user accounts:

* No e-mail address or display name
* No password, if no PIN was assigned by the sharing user
* A password that may only be changed by editing the link, if a PIN code was set
* Anonymous guest users may only receive "read-only" access permissions to the shared item
* Optionally, an expiry date can be applied for an anonymous guest user after which the share link is no longer accessible

'''''Administrator Notes:'''''

* The PIN code for anonymous guest users is stored using symmetrical encryption in the database, therefore, an encryption key needs to be specified via the property <code>com.openexchange.share.cryptKey</code> in <code>share.properties</code>

=== Named Guest Users ===

Internal users are able to invite a guest user to a folder or item explicitly by specifying the e-mail address of the recipient. Such "named" guest users are internally stored as individual guest users, identified by their e-mail address.

If data is shared for the first time to the recipient in the context, a new guest user account is provisioned and an initial set of user permissions and capabilities is assigned. In case there are already shares in different contexts to the same recipient (based on his e-mail address), some existing user data like a display name or an assigned password is copied over if a cross-context database is available on the system.

If the recipient has already been invited from the same or another internal user in the context to another share before, the new share is added to the guest user in a way that the underlying folder- and object permissions are taken over, and the user capabilities getting expanded as needed to cover all modules the shares are located in. Similarly, if a share to a named guest user is revoked and the underlying folder- and object-permissions are removed, the guest user capabilities are updated implicitly to reflect the modules of the remaining shares.

After the last share to a named guest user has been revoked, the user has no longer access to any data. The account itself gets removed from the context automatically after a configurable expiry time. Additionally, any data that is stored for the guest user in the cross-context database is removed once the guest user has been deleted from all contexts in the system.

In contrast to an "anonymous" guest user, a named guest user has access to all shared items from a context after logging in, since the permissions get added to an existing guest user account automatically. For entering the web interface, he may use any of the share links that were sent to him in the different notification messages. Those links usually point to an individual share target like a folder or file, but the guest user may navigate to the other shared contents using the folder tree of the web interface in the same way as regular groupware users do. Similarly, if the guest user has access to shares from different modules, the modules can be switched in the web interface as usual.

'''''Administrator Notes:'''''

* The timespan after which an unused named guest user should be removed from the system can be configured via <code>com.openexchange.share.cleanup.guestExpiry</code> in <code>share.properties</code> - this value may also be set to <code>0</code> to force an immediate removal
* For the removal of no longer needed guest user accounts, a periodical cleanup task is scheduled based on the interval of <code>com.openexchange.share.cleanup.periodicCleanerInterval</code>
* Whether a cross-context database is considered for guest users may be configured via <code>com.openexchange.share.crossContextGuests</code>

== Guest Login & Session Handling ==

Based on the underlying guest user account, different login operations with different authentication workflows are possible.

=== Authentication ===

We have basically three different authentication options for guest users accessing a share, each of them having their own characteristics.

==== Anonymous ====

* Access is granted without providing additional authentication information, the knowledge of the link is sufficient
* When accessing the share link, a guest session is spawned implicitly
* Initially supplied cookies are considered to recycle an existing session
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)

==== Anonymous with PIN ====

* Access is granted for anonymous guest users providing a password / PIN code
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=anonymous</code>
* User can then enter his PIN code, client executes the <code>anonymous_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)
* Password can't be changed by an anonymous user
* Password can be re-constructed / changed by sharing user

==== Guest without Password ====

* Access is granted without providing additional authentication information, the knowledge of the guest's individual link is sufficient
* When accessing the share link, a guest session is spawned implicitly
* Exiting cookies are considered to recycle an existing session
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)
* Guest user may choose an individual password at a later stage

==== Guest with Password ====

* Access is granted for guest users providing a user name and password.
* Much similar to a regular groupware user
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=guest</code> and <code>login_name=<NAME></code>
* The login name is used to pre-fill the username input
* User can then enter his password, client executes the <code>guest_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)
* Password can be changed by guest user
* Guest user may reset his password if he can't remember

=== Guest Hostname ===

For serving shares, a separate guest hostname needs to be configured. This is mainly required to prevent guest- and regular user sessions using the same cookie container when logged in in the same client (otherwise, the cookie holding the alternative session identifier as well as other cookies would get overwritten concurrently). Additionally, this allows to have separate entry points to the web client for guest- and regular users.

The hostname for guests is used when generating external share links, as well as at other locations where hyperlinks are constructed in the context of guest users. Usually, the guest hostname refers to a separate subdomain of the installation like <code>share.example.com</code>, and is defined as an additional named virtual host pointing to the web client's document root in the webserver's configuration.

Once the webserver configuration is done and the web client is accessible using the guest hostname, this hostname needs to be specified in the backend configuration, too. In simple scenarios, where a fixed guest hostname should be used for the installation, this can be done statically in a configuration file. This setting may also be overridden per context via the Config Cascade. In case a dedicated hostname service is installed (for example <code>open-xchange-hostname-ldap</code>), this hostname service is also supposed to supply the guest hostname.

'''''Administrator Notes:'''''

* The guest hostname may be specified via <code>com.openexchange.share.guestHostname</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]
* The guest hostname may also be supplied via dedicated hostname services like <code>open-xchange-hostname-config-cascade</code> or <code>open-xchange-hostname-ldap</code>
* For test purposes, guests may also access the web interface using the same host as regular users do, however, this might lead to unexpected results (missing images, sessions timing out, auto-login malfunction...)

=== Cookies ===

Guest sessions basically make use of the same cookies as regular user sessions do. This includes the JSESSONID cookie for the JVM route, as well as the <code>open-xchange-secret-<hash></code> and <code>open-xchange-public-session-<hash></code> cookies. Additionally, if configured, the client may also issue a <code>store</code> request to persist the open-xchange-session-<hash> cookie. This cookie may then be used to auto-login the guest client into the previously used session if it is still valid.

Besides the common cookies, another special cookie is set: <code>open-xchange-share-<hash></code>. The value contains the unique share token bound to the guest user accessing the share. here, the cookie hash is calculated as it's done for ordinary sessions, so that there can only be one <code>open-xchange-share-<hash></code> cookie in a client at the same time. Whenever an auto-login request is issued by the client, the server checks for the existence of this "share" cookie, and, once recognized and checked for validity, it will try to perform the auto-login for an existing guest session first, i.e. using the session cookie based on the special guest hash calculation outlined above. Otherwise, the common auto-login process takes place. The "share" cookie is removed once the guest session terminates, i.e. the guest user logs out.

Since guest users access the web interface on a separate (sub)domain (see [[#Guest_Hostname|Guest Hostname]] above for details), guest session cookies won't interfere with cookies of a regular session on the same client. This allows to use the regular user session as well as one or more guest sessions in parallel - e.g. if the sharing user quickly wants to check how the contents appear for the guest user after generating a share link.

'''''Administrator Notes:'''''

* Whether guest sessions are enabled for auto-login is configurable via the property <code>com.openexchange.share.autoLogin</code> in <code>share.properties</code>
* By default, the cookie TTL for guest sessions is inherited from the TTL for cookies of regular sessions as defined by <code>com.openexchange.cookie.ttl</code> - this default may be overridden by defining a timespan at <code>com.openexchange.share.cookieTTL</code>

=== Login Modes ===

When accessing a share link, one of the following login modes is triggered to acquire a session and forward the client to the share target. The executed login operation and redirect depends on the authentication mode of underlying guest account, the share target iteself, and the client accessing the share.

==== Redirect to Target ====

In case a share is accessible without providing credentials, the client is redirected to the share target directly, i.e. without prompting for a username or password. By default, the client is redirected to the target in the App Suite web interface by responding the <code>GET</code> request to the share link with <code>HTTP 302</code>, and a location header like the following:

<code>Location: /appsuite/ui#!&session=80c711019d6f48b5bec9cd82758e3308&store=true&user=&user_id=642&context_id=1&m=files&f=41042</code>

The session for the guest user is created implicitly in the backend after checking the share link's validity, and the client is instructed to store appropriate cookies in the redirect response, including the "share" cookie:

<code>Set-Cookie: open-xchange-secret-aNobP2G9wLHJ6sMr7vtTA=38ee770d6e4f42ab8366d91db3279931; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=cae6a3e712ac429e9da9194abd389cb3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br />
<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ad50ac00418fbcdad50ac1418f94fb181d51b8fa7b2bde3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code>

==== Redirect to Login Screen ====

If additional credentials, i.e. an additional PIN code or username/password combination, are required to access a share target, and no "special client" like an iCal consumer is detected by the backend, the client is redirected to the login screen of the app suite webinterface. The GET request to the share link is answered with statuscode HTTP 302, and a location header depending on the required credentials to access the share.

If the share ought to be accessed anonymously, but protected by a PIN code, a location like the following is added to the response header:

<code>Location: /appsuite/ui#!&share=08b4b6110151f1bd7d4b610151f0405d9fc8bb89a887f04e&login_type=anonymous&message_type=INFO&message=Tony%20Parker%20has%20shared%20the%20folder%20%22Pictures%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&target=151ebb38</code>

For shares to dedicated guest users identified by their e-mail address, the redirect location looks like follows:

<code>Location: /appsuite/ui#!&share=4ac9eb590f9ca4d2ac9eb58f9ca611ec9b4f4638d288c8c0&login_type=guest&message_type=INFO&message=Tony%20Parker%20has%20shared%20the%20file%20%22Agenda.pdf%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&login_name=ray%40example.com&target=4444cbc7</code>

The redirect response already contains the <code>Set-Cookie</code> header for the JVM route. On the redirect target, the client should request the PIN code or password from the user, and then issue a special login request, supplying the share token and optional target from the URL parameters, and the password as URL encoded form data in the request body, similar to the usual login request via POST. After successful authentication, the login response includes, along with the common login response properties like the session identifier, information about the share target being accessed:

<code>{"session":"b89af2c2ce494ce4b4573c0632b48e89","user":"ray@example.com","user_id":660,"context_id":1,"locale":"en_US","module":"files","folder":"10","item":"10/456398", ... }</code>

Additionally, the client is instructed to store the secret cookies:

<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ac9eb590f9ca4d5ac9eb58f9ca641ec9b4f4638d288c8a0; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br />
<code>Set-Cookie: open-xchange-secret-MBIRg9bJBLduCcosqQBCw=70187de16f844be6880c18be373b953d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=4e797a59758a4dd7b763912472ccf26d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code>

Afterwards, the client is able to use the session to access the share target as usual.

=== Session Lifecycle ===

Generally, guest sessions on the server are treated just like the sessions of ordinary users. Especially, guest sessions are also held in the local session containers of the backend host they're associated with. However, by default guest sessions are marked as <code>transient</code>, i.e. they are not moved to the long-term session containers, nor they are put into the distributed session storage.

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to <code>false</code> in order to also have guest sessions available in the distributed storage.

'''''Administrator Notes:'''''

* Guest sessions are also accounted in the monitoring outputs (e.g. in the sessions per container graphs)
* The <code>transient</code> handling of guest sessions may be changed via the property <code>com.openexchange.share.transientSessions</code> in <code>share.properties</code>

=== Logout ===

Guest sessions are terminated once a logout request is issued by the client, i.e. the user clicks the "Logout" button in the web interface, just like it is done for regular sessions. Additionally, guest sessions expire in the backend when not being used for a while, the actual timeout depends on the configured default session lifetime and whether they are treated as "transient" or not, as explained above.

Since guest users are not able to use the default login page for regular users, a custom logout location for guest users should be specified where guest users are taken to after clicking logout explicitly, or if their session expired.

If a share is consumed "directly", e.g. by downloading the binary contents of a file share directly (see [[#Consuming_Shares|Consuming Shares]] for details), the guest sessions is terminated instantly after serving the request.

'''''Administrator Notes:'''''

* The logout location for guest accounts can be customized via <code>guestLogoutLocation</code> in the file <code>as-config.yml</code> (see file <code>as-config-default.yml</code> for an example)

== Share Notifications ==

With the new sharing concept, notification mails can be sent out to the permission entities (i.e. internal or guest users) of folders or items. Mechanisms exist to send out such mails implicitly or explicitly. Notifications are sent out implicitly, if externals are invited as guests and can also be sent out for internal invitations, if configured so. The client (e.g. App Suite UI) decides on its own whether implicit notifications shall be sent when updating a folders or items permissions. Besides there are separate API calls for sending out notification messages explicitly. Its on the client to provide this functionality to its users. This makes it possible to re-send a link to a folder or item to an existing permission entity.

Sending out links to shared folders and items is not the only case for notification messages, it can also be necessary to send out system notifications to guest users. Currently this is the case when a guest user secured his account with a password and needs to reset that password, because he cannot remember.

'''''Administrator Notes:'''''

* A special transport must be configured for system notifications and cases where the sharing user has no configured webmail account. This transport is configured in <code>noreply.properties</code>. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.
* It is possible to disable the implicit notification of internal users about shared folders or items at all by setting <code>com.openexchange.share.notifyInternal</code> in <code>share.properties</code> to <code>false</code>.
* The layout of notifications mails can be changed via <code>as-config.yml</code>. All available properties are defined and explained in <code>as-config-defaults.yml</code>.

== API Access ==

From a client's point of view, guest users basically don't differ from regular users, although they usually have limited capabilities, for example no mail access or no personal folders. However, all those differences are reflected within the regular permission- and capability-concepts, so that existing clients, once the guest user is authenticated and has a valid session, continue to work transparently, and use the same API calls as with a regular groupware user.

To create or manage shares and guest users, the HTTP API has been extended at various locations. The following list gives an overview about the changes, derived from the corresponding software change requests.

=== Format change for object identifiers of the default "infostore" account ===

As preparation for individual object permissions where a file can be accessed from different folder "views", the object IDs for documents in the default "infostore" file storage account will get enhanced with the prefixing folder ID.

The identifiers will now be of format <code><some numbers>/<more numbers></code>. Object identifiers are already of type <code>String</code>, so this change should usually be transparent to clients. However, there may be some clever clients out there that for example tried to interpret the string of numerical characters as number, so client developers should double-check their implementation for compatibility. They most likely would run into trouble when coping with non-infostore file storages anyway.

=== Object permissions for files ===

In order to define permissions on object-level, a new property <code>object_permissions</code> for objects of type <code>infoitem</code> is introduced. Each time the underlying folder permissions are not sufficient to access an item, those object permissions are taken into account. Object permissions are stored as an array of Object Permission objects as defined below within the detailed infoitem data, the column ID is <code>108</code>.

Details about the JSON structure are available at:

* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionFlags HTTP API: Object Permission Flags]

=== New field for "user" data: "guest_created_by" ===

A new property has been introduced for users that needs to be exposed in our HTTP API, too. The following property is added to the detailed user data object:

* ID: 616
* Name: guest_created_by
* Type: Number
* Value: Contains the ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users

The property is read-only and can't be removed or set by clients.

See also:

* [http://oxpedia.org/index.php?title=HTTP_API#DetailedUserData HTTP API: Detailed User Data]

=== Extend folder- and object permissions for addressing external guests ===

For sharing files- or folders to external guests, the folder- and object permission objects are extended with additional properties. Those extended properties can be set during creation or update of the parent folder or file. The underlying shares and guest user entities for the referenced recipients are created automatically along with folder/file creation/update. Afterwards, the external recipients appear as regular "user" entities in the permission arrays in subsequent "get" requests.

Details about the extended JSON structure are available at:

* [http://oxpedia.org/index.php?title=HTTP_API#PermissionObject HTTP API: Permission Object]
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]

=== New Ajax module: share/management ===

To work with shares, a new Ajax module is introduced.

The available actions in the module are described at:

* [http://oxpedia.org/index.php?title=HTTP_API#Module_.22share.2Fmanagement.22_.28preliminary.2C_available_with_v7.8.0.29 HTTP API: Module share management]

=== New column "shareable" in detailed infoitem data ===

Clients want to know quickly if an infostore item is shareable or not. A new (read-only) property named <code>shareable</code> of type Boolean with column identifier <code>109</code> is introduced for "detailed infoitem data". If "true", the can be considered as shareable, i.e. the item's object permissions may be adjusted by the user.

Further details are available at:

* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]

=== New action "shares" in module folder ===

To provide an overview of all folders of a certain modules that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>folders</code>. It returns all personal folders of a certain module that are shared to other entities.

Further details are available at:

* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared folders]

=== New action "shares" in module infostore ===

To provide an overview of all files that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>infostore</code>. It returns all personal files that are shared to other entities.

Further details are available at:

* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared infoitems]

=== New fields to retrieve extended permissions of files and folders ===

Clients would like to have more details about permission entities folders directly. A new read-only property named <code>com.openexchange.share.extendedPermissions</code> is introduced for "Detailed folder data", with column identifier <code>3060</code>. It basically contains the same as the regular <code>permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.

Similarly, a new read-only property named <code>com.openexchange.share.extendedObjectPermissions</code> is introduced for "Detailed infoitem data", with column identifier <code>7010</code>. It basically contains the same as the regular <code>object_permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.

Further information about the JSON structure is available at:

* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedPermissionObject HTTP API: Extended Permission Object]
* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedObjectPermissionObject HTTP API: Extended Object Permission Object]

== Consuming Shares ==

Depending on the shared contents and the requesting user agent, shares may be consumed in a couple of different ways. The concrete response to a request to the share URL is evaluated by the share servlet in the backend.

=== App Suite ===

The default handling for all shares is forwarding them to the App Suite web interface, where the shared contents are made available through the existing client. Based on the underlying guest account, the client is either forwarded to the login prompt, or taken directly to the share target if no credentials need to be provided. This process is described in more detail at [[#Guest_Login_&_Session_Handling|Guest Login & Session Handling]].

=== Direct Download ===

Shares to a single file may also be downloaded directly by clients, without opening them in the web interface first. This is indicated by an additional parameter appended to the plain share link, and can be specified in the following ways:

* Append <code>dl</code> parameter:<br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?dl=true</code>
* Specify <code>delivery</code> parameter:<br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?delivery=download</code>

If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an "anonymous" share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like "Guest".

=== Get iCal ===

Shares to a single calendar- or task-folder may also be downloaded directly by clients as iCal files, without opening them in the web interface first. This standard format allows to consume event data directly using various calendaring clients, which often can be configured to subscribe an external calendar source.

Once a share link to a calendar- or task-folder is requested by the client, the <code>Accept</code>- and <code>User-Agent</code> headers of the request are evaluated. If the <code>Accept</code> header is either set to <code>text/calendar</code> or <code>text/iCal</code>, or if the <code>User-Agent</code> header denotes a well-known client like Microsoft Outlook or Mozilla Thunderbird w/ Lightning, the contents of the shared folder are converted to an iCal file that is directly written back in the response.

To force the iCal output, an additional parameter may be appended to the plain share link:

* Append <code>ical</code> parameter:<br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?ical=true</code>

If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an "anonymous" share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like "Guest".

'''''Administrator Notes:'''''

* The interval of task- and appointment data considered for conversion to iCal can be adjusted via <code>com.openexchange.share.handler.iCal.futureInterval</code> and <code>com.openexchange.share.handler.iCal.pastInterval</code> in configuration file <code>share.properties</code>

== Cross-context functionality ==

As already mentioned in previous sections the administrator is able to configure if guests should be handled per context (default) or server wide by using the configuration parameter <code>com.openexchange.share.crossContextGuests</code>.

If set to <code>true</code> the guests email address is used to recognize if there is already a registered user with the given address and aligns the stored password to the already existing guest user. In addition to the password (which is the most important parameter this feature is about) even the users contact data gets synchronized.

'''''Administrator Notes:'''''

* To handle user and contact data across contexts boundaries the feature has to be enabled before a guest receives the first share. Guests that receive shares before the activation cannot be considered within the alignment process. Only latter shares will be considered.
* At the moment this feature does only sync user and contact related data (no shared content). If the user got two shares from different contexts he will only see shares related to the given link.

== Publish/Subscribe vs. Sharing ==

The upcoming sharing features are going to replace the previously used OXMF "publications", allowing guest users to interact with the shared data in the same way as regular groupware users do. However, since the underlying concepts and their technical realization are completely different, a seamless migration between publications and shares is not possible without some drawbacks.

The following list gives an overview of the main discrepancies:

* Custom templates for OXMF publication targets<br />An adminsitrator/admin may have defined some custom publication targets that are using the published data in a special way. While shares would still make all the data available (mainly via the web interface), this would only be a drop-in replacement for the ordinary "view the publication in a browser" use case, but not for anything beyond that scope.
* Subscribe of publications<br />Publications from one user can be added to another user's groupware using the "subscribe" functionality, making use of the embedded microformat data of publications (OXMF). For sharing, we will not have a similar feature in the first iteration, so migrating an existing publication to a share would also stop it from being subscribable.
* Deep links to download files of publications<br />Files behind an infostore publication were accessible behind a static URL, which would theoretically allow them to be requested independently of the parent publication (e.g. images linked from an external website). While the entry URL to a publication would be mappable to a corresponding share URL, converting existing publications to shares would at least break such deep links.

Because of the above points and the whole different concept, we do not migrate existing publications to shares. Instead, the default behavior will be:

* No new OXMF publications or subscriptions can be created by default
* The web client does no longer give the option to publish or subscribe in the OXMF format
* Existing OXMF publications / subscriptions can't be updated
* Existing OXMF publications continue to work as is, including associated subscriptions
* Yet it's still possible to delete existing publications and subscriptions
* Therefore, the menu section "Publications and Subscriptions" will still be available (if there's at least one publication or subscription)

Exceptions to these rules cover special internal subscriptions to 3rd party services like addressbooks from LinkedIn (removed since 7.10.0) or Xing, as well as the auto-publish feature of mail attachments exceeding a specific size.

'''''Administrator Notes:'''''

* The possibility to create/update OXMF publications via HTTP-API may be configured via <code>com.openexchange.publish.createModifyEnabled</code> in file <code>publications.properties</code>
* The possibility to create/update OXMF subscriptions via HTTP-API may be configured via <code>com.openexchange.subscribe.microformats.createModifyEnabled</code> in file <code>microformatSubscription.properties</code>

== Limit file accesses for named/anonymous guests (since 7.8.2) ==

As links to shares might be shared without knowing the audience we introduced a mechanism to prevent abuse.

Therefor the possibility to define size and/or count limits for named/anonymous guests has been introduced. As internal users can be considered as reliable it is not possible to define limits for them.

For named and anonymous guests there are two kinds of limits which apply to a defined time frame. The time frame acts as a sliding time window which means that based on the current request all earlier requests matching the time frame are cumulated and evaluated if one of the two limits is exceeded. If so, the request will be answered with an exception.

The two limits mentioned above are:

* size limits: how many content (in bytes) should the guest be allowed to download (within the defined time frame).
* count limits: how often should the guest be allowed to download a file or folder (within the defined time frame).

Named and anonymos guests can have different limits. Limits are valid for downloads of files and folders. Preview of images is not considered within the limit.

'''''Administrator Notes:'''''

* The anti-abuse mechanism will be available after updating the package open-xchange-core to release 7.8.2
* Additional parameters are located within the configuration file <code>share.properties</code>
* Per default the feature is disabled
* To enable the feature you have to set <code>com.openexchange.share.servlet.limit.enabled</code> to <code>true</code>. If not enabled all additional checks will be skipped. If you would like to set limits via config cascade those will only be checked if the feature itself is enabled.
* To be more flexible the administrator is able to overwrite limits by using the config cascade. As guests do not have fixed user identifiers only the 'context' level scope is supported.

After the feature is enabled you have the ability to configure fine-grained accesses via:
* <code>com.openexchange.share.servlet.limit.timeFrame.guests</code>: sliding time frame (in milliseconds) the limits are valid for named guests. Setting to 0 will disable the check for named guests (if not overwritten via config cascade).
* <code>com.openexchange.share.servlet.limit.timeFrame.links</code>: sliding time frame (in milliseconds) the limits are valid for anonymous guests. Setting to 0 will disable the check for anonymous guests (if not overwritten via config cascade).
* <code>com.openexchange.share.servlet.limit.size.guests</code>: the limit in bytes for named guests (valid for aboves time frame). Setting to 0 will disable the size check for named guests (if not overwritten via config cascade).
* <code>com.openexchange.share.servlet.limit.size.links</code>: the limit in bytes for anonymous guests (valid for aboves time frame). Setting to 0 will disable the size check for anonymous guests (if not overwritten via config cascade).
* <code>com.openexchange.share.servlet.limit.count.guests</code>: the limit for a number of downloads (valid for aboves time frame) for named guests. Setting to 0 will disable the count check for named guests (if not overwritten via config cascade).
* <code>com.openexchange.share.servlet.limit.count.links</code>: the limit for a number of downloads (valid for aboves time frame) for anonymous guests. Setting to 0 will disable the count check for anonymous guests (if not overwritten via config cascade).

=== Example configurations ===

A mixed configuration is possible. Have a look at the following examples assuming that <code>com.openexchange.share.servlet.limit.enabled</code> is set to <code>true</code>.

The following configuration only checks the count limit for anonymous guests. Named guests and the limit for download sizes will not be checked
* <code>com.openexchange.share.servlet.limit.timeFrame.guests:0</code> (# disabled)
* <code>com.openexchange.share.servlet.limit.timeFrame.links:3600000</code> (# 60 minutes)
* <code>com.openexchange.share.servlet.limit.size.guests:0</code> (# not considered as disabled)
* <code>com.openexchange.share.servlet.limit.size.links:0</code> (# size for 60 minutes not checked)
* <code>com.openexchange.share.servlet.limit.count.guests:0</code> (# not considered as disabled)
* <code>com.openexchange.share.servlet.limit.count.links:100</code> (# 100 downloads within 60 minutes)

The following configuration will check the count limit for named guests and the size limit for anonymous guests (both within the last 60 minutes).
* <code>com.openexchange.share.servlet.limit.timeFrame.guests:3600000</code> (# 60 minutes)
* <code>com.openexchange.share.servlet.limit.timeFrame.links:3600000</code> (# 60 minutes)
* <code>com.openexchange.share.servlet.limit.size.guests:0</code> (# disabled)
* <code>com.openexchange.share.servlet.limit.size.links:1073741824</code> (# 1 GB)
* <code>com.openexchange.share.servlet.limit.count.guests:1000</code> (# 1000 downloads within 60 minutes)
* <code>com.openexchange.share.servlet.limit.count.links:0</code> (# disabled)

It is possible to reload an adapted configuration by using reloadconfiguration command line tool.

[[Category: AppSuite]]
[[Category: Administrator]]

AppSuite:Data management

2018-11-26T13:48:07Z

Daniel.becker: Cleanup

This article has been moved to [https://documentation.open-xchange.com/latest/middleware/components/commandlinetools/deleteinvisible.html documentation.open-xchange.com]

AppSuite:Data management

2018-11-26T13:47:40Z

Daniel.becker: Page moved to documentation.open-xchange.com

== deleteinvisible ==

This article has been moved to [https://documentation.open-xchange.com/latest/middleware/components/commandlinetools/deleteinvisible.html documentation.open-xchange.com]

AppSuite:Permission Level

2018-11-26T13:42:22Z

Daniel.becker: Marked deprecated flags

{{VersionFrom|7.4.2}}
= OX Permission Level Matrix=
Note: ''While permissions still apply to versions from 7.4.2 on, a new concept named capabilities has been introduced. This allows for a more granular control of access to features. This article has not yet been updated to reflect this enhancement.''

App Suite allows to provide different permission levels to the users.

The levels start with pure webmail-only functionality and end with the full featured groupware product including all connectors and are described in the first table.

* '''Webmail''' contains pure webmail functionality including a private addressbook
* '''PIM''' (Private Information Management) adds private calendar and private tasks, no group or sharing permissions are available
* '''PIM + Mobility''' adds mobile synchronisation to the PIM level
* '''PIM + InfoStore''' adds private InfoStore functionality to the PIM level
* '''Groupware Standard''' includes all group and sharing permissions as well as the InfoStore
* '''Groupware Premium''' adds all external connectors and mobile synchronisation to Groupware Standard

In addition to this levels, App Suite contains several functions, which can flexible be used with every level. This functions are described in the second table.

== How to read the Matrix ==

{|
|-
! !! Definition
|-
| '''Mandatory''' || This column defines the options, which must not be changed for this level. '''This is a technical requirement and necessary for the correct functioning of OX HE/SE/App Suite'''
|-
| '''Default''' || This column lists the options, which are activated per default for this level
|-
| '''API Parameter''' || Related parameter in the RMI, SOAP and CLT API - described in the [http://software.open-xchange.com/OX6/doc/OX6-Provisioning.pdf Provisioning Documentation]
|-
|  ||  
|-
| '''and/or''' || Minimum one of this options need to be activated in this level
|-
|style="background-color:#C0C0C0" |  || Fields in this color define the most important differentiator to the next lower level
|}

== Matrix - Permission Levels ==

This table describes the mandatory parameters for the different permission levels.

{|
|-
! OX Base Levels !! Functionality !! Mandatory (technical requirement) !! Default !! Requirements / Description !!   !! API Parameter
|-
| rowspan="2" | '''Webmail'''
Webmail only
|style="background-color:#F0F0F0" | Email ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||  || webmail
|-
|style="background-color:#F0F0F0" | Contacts ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || contacts
|-
|   ||   ||   ||   ||   ||   ||  
|-
| rowspan="5" | '''PIM'''<br>Private use only<br>No sharing, no group functions.
|style="background-color:#F0F0F0" | Email ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] || rowspan="3" | The absence of other features defines this level ||   || webmail
|-
|style="background-color:#F0F0F0" | Contacts ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   || contacts
|-
|style="background-color:#F0F0F0" | Calendar ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   || calendar
|-
|Global Addressbook ||   || [[File:Cross_gray.gif]] ||  ||   || globaladdressbookdisabled
|-
|Tasks ||   || [[File:check.gif]] ||  ||   || tasks
|-
|   ||   ||   ||   ||   ||   || 
|-
| rowspan="9" | '''PIM + Mobility'''<br>Private use only<br>No sharing, no group functions<br>Enabled for mobile synchronization
|style="background-color:#F0F0F0" | Email ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || webmail
|-
|style="background-color:#F0F0F0" | Contacts ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || contacts
|-
|style="background-color:#F0F0F0" | Calendar ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || calendar
|-
|style="background-color:#F0F0F0" | USM ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || usm
|-
|style="background-color:#C0C0C0" | Active Sync ||style="background-color:#C0C0C0" | and/or ||style="background-color:#C0C0C0" | [[File:check.gif]] || rowspan="2" | This defines the level<br>At least one of these needs to be set<br>Typically "Active Sync"||   || activesync
|-
|style="background-color:#C0C0C0" | SyncML ||style="background-color:#C0C0C0" | and/or ||style="background-color:#C0C0C0" | [[File:check.gif]] ||   || syncml (deprecated)
|-
|Global Addressbook ||  || [[File:Cross_gray.gif]] ||  ||   || globaladdressbookdisabled
|-
|Tasks ||   || [[File:check.gif]] ||  ||   || tasks
|-
|   ||   ||   ||   ||   ||  
|-
| rowspan="6" | '''PIM + InfoStore''' <br>Private use only<br>No sharing, no group functions<br>Enabled for document storage.
|style="background-color:#F0F0F0" | Email ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || webmail
|-
|style="background-color:#F0F0F0" | Contacts ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || contacts
|-
|style="background-color:#F0F0F0" | Calendar ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || calendar
|-
|style="background-color:#C0C0C0" | InfoStore ||style="background-color:#C0C0C0" | [[File:check.gif]] ||style="background-color:#C0C0C0" | [[File:check.gif]] || This combined with the absence of other switches defines the level <br> ||   || infostore
|-
|Global Addressbook ||   || [[File:Cross_gray.gif]] ||  ||   || globaladdressbookdisabled
|-
|Tasks ||   || [[File:check.gif]] ||  ||   || tasks
|-
|   ||   ||   ||   ||   ||   ||  
|-
| rowspan="9" | '''Groupware Standard'''<br>Full Groupware functionality<br>Access restricted to Web GUI
|style="background-color:#F0F0F0" | Email ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || webmail
|-
|style="background-color:#F0F0F0" | Contacts ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || contacts
|-
|style="background-color:#F0F0F0" | Calendar ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || calendar
|-
|style="background-color:#F0F0F0" | Tasks ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || tasks
|-
|style="background-color:#C0C0C0" | Shared Folders ||style="background-color:#C0C0C0" | [[File:check.gif]] ||style="background-color:#C0C0C0" | [[File:check.gif]] || rowspan="3" | This defines the level<br>All need to be set together ||   || readcreatesharedfolders
|-
|style="background-color:#C0C0C0" | Public Folders ||style="background-color:#C0C0C0" | [[File:check.gif]] ||style="background-color:#C0C0C0" | [[File:check.gif]] ||   || editpublicfolders
|-
|style="background-color:#C0C0C0" | Task Delegation ||style="background-color:#C0C0C0" | [[File:check.gif]] ||style="background-color:#C0C0C0" | [[File:check.gif]] ||   || delegatetask
|-
|style="background-color:#F0F0F0" | Global Addressbook ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || globaladdressbookdisabled
|-
|InfoStore ||   || [[File:check.gif]] ||  ||   || infostore
|-
|   ||   ||   ||   ||   ||   ||  
|-
| rowspan="16" | '''Groupware Premium'''<br>Full Groupware functionality<br>All external clients enabled (Mobility, Outlook, Mac)
|style="background-color:#F0F0F0" | Email ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || webmail
|-
|style="background-color:#F0F0F0" | Contacts ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || contacts
|-
|style="background-color:#F0F0F0" | Calendar ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || calendar
|-
|style="background-color:#F0F0F0" | Tasks ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||  ||   || tasks
|-
|style="background-color:#F0F0F0" | Shared Folders ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || readcreatesharedfolders
|-
|style="background-color:#F0F0F0" | Public Folders ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || editpublicfolders
|-
|style="background-color:#F0F0F0" | Task Delegation ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || delegatetask
|-
|style="background-color:#F0F0F0" | Global Addressbook ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || globaladdressbookdisabled
|-
|style="background-color:#F0F0F0" | USM ||style="background-color:#F0F0F0" | [[File:check.gif]] ||style="background-color:#F0F0F0" | [[File:check.gif]] ||   ||   || usm
|-
|style="background-color:#C0C0C0" | OLOX2 ||style="background-color:#C0C0C0" | and/or ||style="background-color:#C0C0C0" | [[File:check.gif]] || rowspan="4" | This defines the level<br>At least one of these needs to be set.<br>Typically OLOX2 and Active Sync ||   || olox20 (deprecated)
|-
|style="background-color:#C0C0C0" | OLOX (Legacy) ||style="background-color:#C0C0C0" | and/or ||style="background-color:#C0C0C0" | [[File:check.gif]] ||   || webdavxml (deprecated)
|-
|style="background-color:#C0C0C0" | Active Sync ||style="background-color:#C0C0C0" | and/or ||style="background-color:#C0C0C0" | [[File:check.gif]] ||   || activesync
|-
|style="background-color:#C0C0C0" | SyncML ||style="background-color:#C0C0C0" | and/or ||style="background-color:#C0C0C0" | [[File:check.gif]] ||   || syncml (deprecated)
|-
|InfoStore ||   || [[File:check.gif]] ||  ||   || infostore
|-
|iCal Access ||   || [[File:check.gif]] ||  ||   || ical (deprecated)
|-
|vCard Access ||   || [[File:check.gif]] ||  ||   || vcard (deprecated)
|-
|}
<br>
<br>

== Additional Flexible Functions ==

The following functions can be added flexible to each permission level.

{|
|-
! Additional Functions !! Default !! Requirements / Description !!   !! API Parameter
|-
| rowspan="2" | '''Minimum Webmail'''
|Collect Emailaddresses || Email addresses typed into sent/reveived emails can be saved automatically in a dedicated folder ||   || collectemailaddresses
|-
|Edit Password || If a plugin to change the own password is installed on the system, it will be displayed in the settings area ||   || editpassword
|-
|   ||   ||   ||   ||  
|-
| rowspan="3" | '''Minimum PIM'''
|Multiple Mailaccounts || The user can use external IMAP/POP3 Mailaccounts within the OX WebGUI. Starting with 6.20 this can be configured per email service ||   || multiplemailaccounts
|-
|Subscriptions || The user can subscribe to external/social datasources, like LinkedIN (removed since 7.10.0), XING, Gmail, .... Starting with 6.20 this can be configured per subscription service ||   || subscriptions
|-
|Publications || [DEPRECATED] The user can publish his own data (contacts/documents) for other users in the internet ||   || publication
|-
|   ||   ||   ||   ||  
|-
| '''Minimum PIM + InfoStore'''
|WebDAV || Allows WebDAV access to InfoStore documents; Requires InfoStore ||   || webdav
|-
|   ||   ||   ||   ||  
|-
| rowspan="2" | '''Minimum GW Standard'''
|Manage Resources || The user is allowed to create and manage resources for the whole company ||   || editresource
|-
|Manage Groups || The user is allowed to create and manage groups for the whole company ||   || editgroup
|-
|   ||   ||   ||   ||  
|-
| rowspan="2" | '''Minimum GW Premium'''
|vCard || The user can download all his contacts via the vCard interface ||   || vcard (deprecated)
|-
|iCal || The user can download all his contacts via the iCal interface ||   || ical (deprecated)
|-
|}

AppSuite:User management

2018-11-26T13:39:39Z

Daniel.becker: Marked deprecated flags

== createuser ==

'''<code>createuser</code>''' is the tool to create new users in a given context. The displayname must be unique in one context.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show infoabout commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| --extendedoptions
|Set this if you want to see all options, use this instead of help option
|-
|csv-import <CSV file>
| Full path to CSV file with user data to import. This option makes mandatory options obsolete, except credential options (if needed).
|-
| -c,--contextid <integer>
|The id of the context
|-
| -u,--username <string>
|Username of the user
|-
| -d,--displayname <string>
|Display name of the user
|-
| -g,--givenname <string>
|Given name for the user
|-
| -s,--surname <string>
|Surname of the user
|-
| -p,--password <string>
|Password for the user
|-
| -e,--email <string>
|Primary mail address
|-
| -l,--language <lang>
|Language for the user (de_DE,en_US,fr_FR)
|-
| -t,--timezone <timezone>
|Timezone of the user (Europe/Berlin)
|-
| -x,--department <string>
|Department of the user
|-
| -z,--company <string>
|Company of the user
|-
| -a,--aliases <string>
|E-Mail aliases of the user, separated by ","
|-
| --access-combination-name <access-combination-name>
|Access combination name
|-
| --addguipreferences <addguipreferences>
|Add a GUI setting (key=value)
|}
For the GUI preferences please also see [http://oxpedia.org/wiki/index.php?title=Gui_path]

==== --csv-import <CSV file> ====

Full path to CSV file with user data to
import. This option makes mandatory command line options obsolete, except credential options (if needed). But they have to be set in the CSV file.

With this option you can specify a csv file
(a full pathname must be given) with the data which should be imported. The columnnames in the CSV file must be the same as the long-options of the command line tools, without the prefix
"--".

This option will normally be used to fill new large installations with the new data. So instead of calling the command line tools in a shell script every time, just a csv file needs to
be created, containing the whole data.

Note that the credentials of the masteradmin in the createcontext call must be given on the command line with the -A and -P options nevertheless - if
authentication is enabled. If the createuser command line tool is used, the credentials are part of the csv file, and cannot be set as options on the command line itself. The reason for this
different behavior is that different contexts have different credentials for the admin user, so they must be set in every line of the csv file. Opposed to this the credentials of the masteradmin
are always the same.

=== Extended options ===

{| border="1"
|-
| --email1 <string>
|Email1
|-
| --birthday <datevalue>
|Birthday
|-
| --anniversary <datevalue>
|Anniversary
|-
| --branches <string>
|Branches
|-
| --business_category <string>
|Business_category
|-
| --postal_code_business <string>
|Postal_code_business
|-
| --state_business <string>
|State_business
|-
| --street_business <string>
|Street_business
|-
| --telephone_callback <string>
|Telephone_callback
|-
| --city_home <string>
|City_home
|-
| --commercial_register <string>
|Commercial_register
|-
| --country_home <string>
|Country_home
|-
| --email2 <string>
|Email2
|-
| --email3 <string>
|Email3
|-
| --employeetype <string>
|EmployeeType
|-
| --fax_business <string>
|Fax_business
|-
| --fax_home <string>
|Fax_home
|-
| --fax_other <string>
|Fax_other
|-
| --imapserver <string>
|ImapServer
|-
| --imaplogin <string>
|ImapLogin
|-
| --smtpserver <string>
|SmtpServer
|-
| --instant_messenger1 <string>
|Instant_messenger1
|-
| --instant_messenger2 <string>
|Instant_messenger2
|-
| --telephone_ip <string>
|Telephone_ip
|-
| --telephone_isdn <string>
|Telephone_isdn
|-
| --mail_folder_drafts_name <string>
|Mail_folder_drafts_name
|-
| --mail_folder_sent_name <string>
|Mail_folder_sent_name
|-
| --mail_folder_spam_name <string>
|Mail_folder_spam_name
|-
| --mail_folder_trash_name <string>
|Mail_folder_trash_name
|-
| --mail_folder_archive_full_name <string>
|Mail_folder_archive_full_name
|-
| --manager_name <string>
|Manager_name
|-
| --marital_status <string>
|Marital_status
|-
| --cellular_telephone1 <string>
|Cellular_telephone1
|-
| --cellular_telephone2 <string>
|Cellular_telephone2
|-
| --info <string>
|Info
|-
| --nickname <string>
|Nickname
|-
| --number_of_children <string>
|Number_of_children
|-
| --note <string>
|Note
|-
| --number_of_employee <string>
|Number_of_employee
|-
| --telephone_pager <string>
|Telephone_pager
|-
| --password_expired <booleanvalue>
|Password_expired
|-
| --telephone_assistant <string>
|Telephone_assistant
|-
| --telephone_business1 <string>
|Telephone_business1
|-
| --telephone_business2 <string>
|Telephone_business2
|-
| --telephone_car <string>
|Telephone_car
|-
| --telephone_company <string>
|Telephone_company
|-
| --telephone_home1 <string>
|Telephone_home1
|-
| --telephone_home2 <string>
|Telephone_home2
|-
| --telephone_other <string>
|Telephone_other
|-
| --postal_code_home <string>
|Postal_code_home
|-
| --profession <string>
|Profession
|-
| --telephone_radio <string>
|Telephone_radio
|-
| --room_number <string>
|Room_number
|-
| --sales_volume <string>
|Sales_volume
|-
| --city_other <string>
|City_other
|-
| --country_other <string>
|Country_other
|-
| --middle_name <string>
|Middle_name
|-
| --postal_code_other <string>
|Postal_code_other
|-
| --state_other <string>
|State_other
|-
| --street_other <string>
|Street_other
|-
| --spouse_name <string>
|Spouse_name
|-
| --state_home <string>
|State_home
|-
| --street_home <string>
|Street_home
|-
| --suffix <string>
|Suffix
|-
| --tax_id <string>
|Tax_id
|-
| --telephone_telex <string>
|Telephone_telex
|-
| --telephone_ttytdd <string>
|Telephone_ttytdd
|-
| --uploadfilesizelimitperfile <string>
|Upload file size limit per file for mail attachments
|-
| --uploadfilesizelimit <string>
|Total upload file size limit for mail attachments
|-
| --url <string>
|Url
|-
| --userfield01 <string>
|Userfield01
|-
| --userfield02 <string>
|Userfield02
|-
| --userfield03 <string>
|Userfield03
|-
| --userfield04 <string>
|Userfield04
|-
| --userfield05 <string>
|Userfield05
|-
| --userfield06 <string>
|Userfield06
|-
| --userfield07 <string>
|Userfield07
|-
| --userfield08 <string>
|Userfield08
|-
| --userfield09 <string>
|Userfield09
|-
| --userfield10 <string>
|Userfield10
|-
| --userfield11 <string>
|Userfield11
|-
| --userfield12 <string>
|Userfield12
|-
| --userfield13 <string>
|Userfield13
|-
| --userfield14 <string>
|Userfield14
|-
| --userfield15 <string>
|Userfield15
|-
| --userfield16 <string>
|Userfield16
|-
| --userfield17 <string>
|Userfield17
|-
| --userfield18 <string>
|Userfield18
|-
| --userfield19 <string>
|Userfield19
|-
| --userfield20 <string>
|Userfield20
|-
| --city_business <string>
|City_business
|-
| --country_business <string>
|Country_business
|-
| --assistant_name <string>
|Assistant_name
|-
| --telephone_primary <string>
|Telephone_primary
|-
| --categories <string>
|Categories
|-
| --mail_folder_confirmed_ham_name <string>
|Mail_folder_confirmed_ham_name
|-
| --mail_folder_confirmed_spam_name <string>
|Mail_folder_confirmed_spam_name
|-
| --gui_spam_filter_capabilities_enabled <booleanvalue>
|GUI_spam_filter_capabilities_enabled
|-
| --mailenabled <true/false>
|Mailenabled
|-
| --defaultsenderaddress <stringvalue>
|DefaultSenderAddress
|-
| --title <string>
|Title
|-
| --position <string>
|Position
|-
| --access-calendar <on/off>
|Calendar module (Default is off)
|-
| --access-contacts <on/off>
|Contact module access (Default is on)
|-
| --access-delegate-tasks <on/off>
|Delegate tasks access (Default is off)
|-
| --access-edit-public-folder <on/off>
|Edit public folder access (Default is off)
|-
| --access-ical <on/off>
|Ical module access (Default is off)
|-
| --access-infostore <on/off>
|Infostore module access (Default is off)
|-
| --access-read-create-shared-Folders <on/off>
|Read create shared folder access (Default is off)
|-
| --access-syncml <on/off>
|Syncml access (Default is off)
|-
| --access-active-sync <on/off>
|Exchange Active Sync access (Default is off)
|-
| --access-usm <on/off>
|Universal Sync Module access (Default is off)
|-
| --access-tasks <on/off>
|Tasks access (Default is off)
|-
| --access-vcard <on/off>
|Vcard access (Default is off)
|-
|
--access-webmail <on/off>
|Webmail access (Default is on)
|-
| --access-publication <on/off>
|[DEPRECATED] Publication permission (Default is on). Note: access-publication needs access-infostore and is optional for Groupware+ and premium
|-
| --access-subscription <on/off>
|Subscription permission (Default is on)
|-
| --access-edit-group <on/off>
|Edit group access (Default is off)
|-
| --access-edit-resource <on/off>
|Edit resource access (Default is off)
|-
| --access-edit-password <on/off>
|Edit password access (Default is off)
|-
| --access-collect-email-addresses <on/off>
|Edit collect email addresses (Default is off)
|-
| --access-multiple-mail-accounts <on/off>
|Use multiple mail account feature (Default is off)
|-
| --access-global-address-book-disabled <on/off>
|Access to global address book (Default is off). Note: Setting this option to true is only allowed in combination with PIM and Webmail rights. Note: There is a 'restoregaddefaults' script to restore the default permissions of the global address book folder.
|-
| --access--voipnow <on/off>
|Access to VoiceOverIP feature.
|-
| --access-public-folder-editable <on/off>
|Access to public folders. Allows or denies to see public folders.
|-
| --foldertree <0/1>
|0 sets the OX standard folder tree and 1 sets the Outlook-like folder tree.
|-
| --access-olox20 <on/off>
| [DEPRECATED] Access to Olox2.0
|-
| --default-folder-mode
| The mode how the default folders should be created. 'default', 'default-deletable', 'no-default-folders'. If not selected, 'default' is applied.
|}

=== Open-Xchange module access ===

With Open-Xchange it is
possible to limit the access to the available modules per context i. e., all users in one context per default get the same access rights. The rights though can be changed per user. Currently,
following modules are implemented: access-calendar, access-contacts, access-delegate-tasks, access-edit-public-folder, access-ical, access-infostore, access-read-create-shared-Folders,
access-tasks, access-vcard, access-webdav, access-syncml and access-webmail. There are several combinations possible and four are supported (not mentioned modules need to be
disabled). This limitation is needed because some modules depend on access to others. There are different Open-Xchange packages available for the customer: Webmail+, PIM+, Groupware+, Premium.
These packages have to be configured per context i. e., all users in a context need to use the same package. Each package consists of a combination of modules that has to be set up appropriately.
The following sections quickly introduce the packages and their module configuration. Open-Xchange also provides the possibility to use "access combination names" when creating and changing
contexts/users. If you want to change the package acess rights for a context, you can simply add the "access-combination-name" switch to the appropriate tool
(createcontext,createuser,changecontext etc.).

==== Webmail+ ====

If there are no access rights specified when creating a new user Webmail+ is used as default. Webmail+ is a base package that allows access to the
webmail interface and a personal address book. To grant access to this package, the following modules have to be set to "on" for all users in a context:

{| border="1"
|-
|access-contacts
|Access combination name: webmail_plus
|-
|access-webmail
|Access combinationname: webmail_plus
|}

==== PIM+ ====

PIM+
is another base package that gives access to the webmailer, personal address book, calendar and tasks. Group appointments and delegating tasks are not supported. To grant access to this package,
the following modules have to be set to "on" for all users in a context:

{| border="1"
|-
|access-contacts
|Access combination name: pim_plus
|-
|access-webmail
|Access combination name: pim_plus
|-
|access-calendar
|Access combination name: pim_plus
|-
|access-delegate-tasks
|Access combination name: pim_plus
|-
|access-tasks
|Access combination name: pim_plus
|}

==== Groupware+ ====

Groupware+ is an upsell package that provides full groupware functionality: private, shared and public folders, conflict handling for appointments, team view. Furthermore, the InfoStore is
available. To grant access to this package, the following modules have to be set to "on" for all users in a context:

{| border="1"
|-
|access-contacts
|Access combination name: groupware_plus
|-
|access-webmail
|Access combination name: groupware_plus
|-
|access-calendar
|Access combination name: groupware_plus
|-
|access-delegate-tasks
|Access combination name: groupware_plus
|-
|access-tasks
|Access combination name: groupware_plus
|-
|access-edit-public-folder
|Access combination name: groupware_plus
|-
|access-infostore
|Access combination name: groupware_plus
|-
|access-read-create-shared-Folders
|Access combination name: groupware_plus
|}

==== Premium ====

Premium is a desktop integration package. It provides the functionality of the "Groupware+" package and comes with interfaces to integrate with other software: The OXtender for MS Outlook and the
WebDAV interface to integrate the InfoStore with desktops. To grant access to this package, the following modules have to be set to "on" for all users in a context:

{| border="1"
|-
|access-contacts
|Access combination name: premium
|-
|access-webmail
|Access combination name: premium
|-
|access-calendar
|Access combination name: premium
|-
|access-delegate-tasks
|Access combination name: premium
|-
|access-tasks
|Access combination name: premium
|-
|access-edit-public-folder
|Access combination name: premium
|-
|access-infostore
|Access combination name: premium
|-
|access-read-create-shared-Folders
|Access combination name: premium
|-
|access-ical
|Access combination name: premium
|-
|access-vcard
|Access combination name: premium
|-
|access-webdav
|Access combination name: premium
|}

==== All ====
The setting <code>all</code> is equivalent to <code>premium</code> for ordinary users. For context administrators, it adds the right <code>publicfoldereditable</code>, which allows the admin to change the access rights to public folders for groups.

==== Package access configuration ====

This section provides a quick overview about the different packages that can be configured per context and the
required access configuration:

{| border="1"
|-
|Module
|Webmail+
|PIM+
|Groupware+
|Premium
|-
| -access-calendar
|off
|on
|on
|on
|-
| -access-contacts
|on
|on
|on
|on
|-
| -access-delegate-tasks
|off
|on
|on
|on
|-
| -access-edit-public-folder
|off
|off
|on
|on
|-
| -access-ical
|off
|off
|off
|on
|-
| -access-infostore
|off
|off
|on
|on
|-
| -access-read-create-shared-Folders
|off
|off
|on
|on
|-
| -access-syncml
|off
|off
|off
|off
|-
|–access-tasks
|off
|on
|on
|on
|-
| -access-vcard
|off
|off
|off
|on
|-
| -access-webdav
|off
|off
|off
|on
|-
| -access-webmail
|on
|on
|on
|on
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Context admin user name
|-
| -P,--adminpass <string>
|Context admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

<code>contextid {adminuser adminpass} username displayname givenname surname password email</code>

=== Command output ===

On success:

<code>user <userid> in context <contextid> created</code>

On failure:

<code>user in context <contextid> could not be created: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/createuser -c 123 -u jd -d "john doe"
-g John -s Doe -p userpw -e jd@example.com</code>'''

<code>user 3 in context 123 created</code>

== deleteuser ==

'''<code>deleteuser</code>''' is the tool to delete a user in a given context. If you delete a user the public folder entries of this user are
transferred to the admin user. All other data are deleted.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of them context
|-
| -i,--userid <integer>
|Id of the user
|-
| -u,--username <string>
|Username ofthe user
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Context Admin user name
|-
| -P,--adminpass <string>
|Context Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===
<code>contextid {adminuser adminpass} (userid or username)</code>

=== Command output ===

On success:

<code>user <userid> in context <contextid> deleted</code>

On failure:

<code>user <userid> in context <contextid> could not be deleted: <reason from
server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code> /opt/open-xchange/deleteuser -c 123 -i 3</code>'''

<code>user 3 in context 123 deleted</code>

== listuser ==

'''<code>listuser</code>''' is the tool to list and search for users.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context
|-
| -s,--searchpattern <string>
|Search/List pattern, default “*”
|-
| --csv
|Command output as csv
|-
| -i,--ignorecase
|Do a case-insensitive search with the given search pattern
|-
| --includeguests
|Add guest users to listing '''Available with v7.8.0'''
|-
| --excludeusers
|Exclude usual users from listing '''Available with v7.8.0'''
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Context Admin user name
|-
| -P,--adminpass <string>
|Context Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===
<code>contextid adminuser adminpass</code>

=== Command output ===

Standard output (only a subset of available attributes are printed also only disabled
modules):

{| border="1"
|-
|id
|enabled
|imapServer
|smtpserver
|language
|Webdav
|-
|3
|true
|localhost
|localhost
|en_US
|false
|false
|}

csv output:
Name,Language,Id,Display_name,PrimaryEmail,MaxQuota,UsedQuota,Email1,Mailenabled,Password,Sur_name,Given_name,
FilestoreId,FilestoreOwner,Filestore_name,Birthday,Anniversary,Branches,Business_category,Postal_code_business,
State_business,Street_business,Telephone_callback,City_home,Commercial_register,Country_home,Company,Department,
Email2,Email3,EmployeeType,Fax_business,Fax_home,Fax_other,ImapServer,ImapLogin,SmtpServer,Instant_messenger1,
Instant_messenger2,Telephone_ip,Telephone_isdn,Mail_folder_drafts_name,Mail_folder_sent_name,
Mail_folder_spam_name,Mail_folder_trash_name,Mail_folder_archive_full_name,Manager_name,Marital_status,Cellular_telephone1,Cellular_telephone2,
Info,Nickname,Number_of_children,Note,Number_of_employee,Telephone_pager,Password_expired,Telephone_assistant,
Telephone_business1,Telephone_business2,Telephone_car,Telephone_company,Telephone_home1,Telephone_home2,
Telephone_other,Position,Postal_code_home,Profession,Telephone_radio,Room_number,Sales_volume,City_other,
Country_other,Middle_name,Postal_code_other,State_other,Street_other,Spouse_name,State_home,Street_home,Suffix,
Tax_id,Telephone_telex,Timezone,Title,Telephone_ttytdd,UploadFileSizeLimit,UploadFileSizeLimitPerFile,Url,
Userfield01,Userfield02,Userfield03,Userfield04,Userfield05,Userfield06,Userfield07,Userfield08,Userfield09,
Userfield10,Userfield11,Userfield12,Userfield13,Userfield14,Userfield15,Userfield16,Userfield17,Userfield18,
Userfield19,Userfield20,Aliases,City_business,Country_business,Assistant_name,Telephone_primary,Categories,
PasswordMech,Mail_folder_confirmed_ham_name,Mail_folder_confirmed_spam_name,GUI_Spam_filter_capabilities_enabled,
DefaultSenderAddress,FolderTree,UserAttributes,GuiPreferences,access-calendar,access-contacts,
access-delegate-tasks,access-edit-public-folder,access-ical,access-infostore,
access-read-create-shared-Folders,access-syncml,access-tasks,access-vcard,access-webdav,
access-webmail,access-edit-group,access-edit-resource,access-edit-password,access-collect-email-addresses,
access-multiple-mail-accounts,access-subscription,access-publication,access-active-sync,access-usm,
access-olox20,access-denied-portal,access-global-address-book-disabled,access-public-folder-editable

=== Example ===

<pre> root@oxhe:~# /opt/open-xchange/sbin/listuser -c 6 Id Name Displayname Email 2 admin admin admin@example.com 3 holger Holger
holger@example.com
</pre>

== getusercapabilities ==

'''<code>getusercapabilities</code>''' is the tool to list available capabilities for a certain user.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context
|-
| -i,--userid <userid>
|Id of the user
|-
| -u,--username <username>
|Username of the user
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Context Admin user name
|-
| -P,--adminpass <string>
|Context Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===
<code>contextid userid adminuser adminpass</code>

=== Command output ===

Either "There are no capabilities set for user <user-id> in context <context-id>"
or a line-wise listing of identifiers for available capabilities

=== Example ===

<pre> root@oxhe:~# /opt/open-xchange/sbin/getusercapabilities -c 6 -i 345
</pre>

== changeuser ==

The '''<code>changeuser</code>''' tool allows to modify attributes of an existing user in a given context. The displayname must be unique in
one context.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| --extendedoptions
|Set this if you want to see all options, use this instead of help option
|-
| -c,--contextid <integer>
|The id of the context
|-
| -i,--userid <integer>
|Id of the user
|-
| -u,--username <string>
|Username of the user
|-
| -d,--displayname <string>
|Display name of the user
|-
| -g,--givenname <string>
|Given name for the user
|-
| -s,--surname <string>
|Surname of the user
|-
| -p,--password <string>
|Password for the user
|-
| -e,--email <string>
|Primary mail address
|-
| -l,--language <lang>
|Language for the user (de_DE,en_US, fr_FR)
|-
| -t,--timezone <timezone>
|Timezone of the user (Europe/Berlin)
|-
| -x,--department <string>
|Department of the user
|-
| -z,--company <string>
|Company of the user
|-
| -a,--aliases <string>
|E-Mail aliases of the user, separated by ","
|-
| --access-combination-name <access-combination-name>
|Access combination name
|-
| --addguipreferences <addguipreferences>
|Add a GUI setting (key=value)
|-
| --removeguipreferences <removeguipreferences>
|Remove a GUI setting
|-
| --access-denied-portal <on/off>
|Denies portal access (Default is off)
|-
| --capabilities-to-add <capabilities-to-add>
| The capabilities to add as a comma-separated string (from 7.2.0 on)
|-
| --capabilities-to-remove <capabilities-to-remove>
|The capabilities to remove as a comma-separated string (from 7.2.0 on)
|-
| --capabilities-to-drop <capabilities-to-drop>
|The capabilities to drop; e.g. cleanse from storage; as a comma-separated string (from 7.6.0 on)
|}
For the GUI preferences please also see http://www.open-xchange.com/wiki/index.php?title=Gui_path

=== Extended options ===

{| border="1"
|-
| --email1 <string>
|Email1
|-
| --mailenabled <booleanvalue >
|Mailenabled
|-
| --birthday <datevalue>
|Birthday
|-
| --anniversary <datevalue>
|Anniversary
|-
| --branches <string>
|Branches
|-
| --business_category <string>
|Business_category
|-
| --postal_code_business <string>
|Postal_code_business
|-
| --state_business <string>
|State_business
|-
| --street_business <string>
|Street_business
|-
| --telephone_callback <string>
|Telephone_callback
|-
| --city_home <string>
|City_home
|-
| --commercial_register <string>
|Commercial_register
|-
| --country_home <string>
|Country_home
|-
| --email2 <string>
|Email2
|-
| --email3 <string>
|Email3
|-
| --employeetype <string>
|EmployeeType
|-
| --fax_business <string>
|Fax_business
|-
| --fax_home <string>
|Fax_home
|-
| --fax_other <string>
|Fax_other
|-
| --imapserver <string>
|ImapServer
|-
| --imaplogin <string>
|ImapLogin
|-
| --smtpserver <string>
|SmtpServer
|-
| --instant_messenger1 <string>
|Instant_messenger1
|-
| --instant_messenger2 <string>
|Instant_messenger2
|-
| --telephone_ip <string>
|Telephone_ip
|-
| --telephone_isdn <string>
|Telephone_isdn
|-
| --mail_folder_drafts_name <string>
|Mail_folder_drafts_name
|-
| --mail_folder_sent_name <string>
|Mail_folder_sent_name
|-
| --mail_folder_spam_name <string>
|Mail_folder_spam_name
|-
| --mail_folder_trash_name <string>
|Mail_folder_trash_name
|-
| --mail_folder_archive_full_name <string>
|Mail_folder_archive_full_name
|-
| --manager_name <string>
|Manager_name
|-
| --marital_status <string>
|Marital_status
|-
| --cellular_telephone1 <string>
|Cellular_telephone1
|-
| --cellular_telephone2 <string>
|Cellular_telephone2
|-
| --info <string>
|Info
|-
| --nickname <string>
|Nickname
|-
| --number_of_children <string>
|Number_of_children
|-
| --note <string>
|Note
|-
| --number_of_employee <string>
|Number_of_employee
|-
| --telephone_pager <string>
|Telephone_pager
|-
| --password_expired <booleanvalue>
|Password_expired
|-
| --telephone_assistant <string>
|Telephone_assistant
|-
| --telephone_business1 <string>
|Telephone_business1
|-
| --telephone_business2 <string>
|Telephone_business2
|-
| --telephone_car <string>
|Telephone_car
|-
| --telephone_company <string>
|Telephone_company
|-
| --telephone_home1 <string>
|Telephone_home1
|-
| --telephone_home2 <string>
|Telephone_home2
|-
| --telephone_other <string>
|Telephone_other
|-
| --postal_code_home <string>
|Postal_code_home
|-
| --profession <string>
|Profession
|-
| --telephone_radio <string>
|Telephone_radio
|-
| --room_number <string>
|Room_number
|-
| --sales_volume <string>
|Sales_volume
|-
| --city_other <string>
|City_other
|-
| --country_other <string>
|Country_other
|-
| --middle_name <string>
|Middle_name
|-
| --postal_code_other <string>
|Postal_code_other
|-
| --state_other <string>
|State_other
|-
| --street_other <string>
|Street_other
|-
| --spouse_name <string>
|Spouse_name
|-
| --state_home <string>
|State_home
|-
| --street_home <string>
|Street_home
|-
| --suffix <string>
|Suffix
|-
| --tax_id <string>
|Tax_id
|-
| --telephone_telex <string>
|Telephone_telex
|-
| --telephone_ttytdd <string>
|Telephone_ttytdd
|-
| --url <string>
|Url
|-
| --userfield01 <string>
|Userfield01
|-
| --userfield02 <string>
|Userfield02
|-
| --userfield03 <string>
|Userfield03
|-
| --userfield04 <string>
|Userfield04
|-
| --userfield05 <string>
|Userfield05
|-
| --userfield06 <string>
|Userfield06
|-
| --userfield07 <string>
|Userfield07
|-
| --userfield08 <string>
|Userfield08
|-
| --userfield09 <string>
|Userfield09
|-
| --userfield10 <string>
|Userfield10
|-
| --userfield11 <string>
|Userfield11
|-
| --userfield12 <string>
|Userfield12
|-
| --userfield13 <string>
|Userfield13
|-
| --userfield14 <string>
|Userfield14
|-
| --userfield15 <string>
|Userfield15
|-
| --userfield16 <string>
|Userfield16
|-
| --userfield17 <string>
|Userfield17
|-
| --userfield18 <string>
|Userfield18
|-
| --userfield19 <string>
|Userfield19
|-
| --userfield20 <string>
|Userfield20
|-
| --city_business <string>
|City_business
|-
| --country_business <string>
|Country_business
|-
| --assistant_name <string>
|Assistant_name
|-
| --telephone_primary <string>
|Telephone_primary
|-
| --categories <string>
|Categories
|-
| --mail_folder_confirmed_ham_name <string>
|Mail_folder_confirmed_ham_name
|-
| --mail_folder_confirmed_spam_name <string>
|Mail_folder_confirmed_spam_name
|-
| --gui_spam_filter_capabilities_enabled <booleanvalue>
|GUI_Spam_filter_capabilities_enabled
|-
| --defaultsenderaddress<string>
|DefaultSenderAddress
|-
| --title <string>
|Title
|-
| --position <string>
|Position
|-
| --access-calendar
<on/off>
|Calendar module (Default is off)
|-
| --access-contacts <on/off>
|Contact module access (Default is on)
|-
| --access-delegate-tasks <on/off>
|Delegate tasks access (Default is off)
|-
| --access-edit-public-folder <on/off>
|Edit public folder access (Default is off)
|-
| --access-ical <on/off>
|Ical module access (Default is off)
|-
| --access-infostore <on/off>
|Infostore module access (Default is off)
|-
| --access-read-create-shared-Folders <on/off>
|Read create shared folder access (Default is off)
|-
| --access-syncml <on/off>
|Syncml access (Default is off)
|-
| --access-active-sync <on/off>
|Exchange Active Sync access (Default is off)
|-
| --access-usm <on/off>
|Universal Sync Module access (Default is off)
|-
| --access-tasks <on/off>
|Tasks access (Default is off)
|-
| --access-vcard <on/off>
|Vcard access (Default is off)
|-
| --access-webdav <on/off>
|Webdav access (Default is off)
|-
| --access-webmail <on/off>
|Webmail access (Default is on)
|-
| --access-publication <on/off>
|[DEPRECATED] Publication permission (Default is on). Note: access-publication needs access-infostore and is optional for Groupware+ and premium
|-
| --access-subscription <on/off>
|Subscription permission (Default is on)
|-
| --access-edit-group <on/off>
|Edit group access (Default is off)
|-
| --access-edit-resource <on/off>
|Edit resource access (Default is off)
|-
| --access-edit-password <on/off>
|Edit password access (Default is off)
|-
| --access-collect-email-addresses <on/off>
|Edit collect email addresses (Default is off)
|-
| --access-multiple-mail-accounts <on/off>
|Use multiple mail account feature (Default is off)
|-
| --access-global-address-book-disabled <on/off>
|Access to global address book (Default is off). Note: Setting this option to true is only allowed in combination with PIM and Webmail rights. Note: There is a 'restoregaddefaults' script to restore the default permissions of the global address book folder.
|-
| --access--voipnow <on/off>
|Access to VoiceOverIP feature.
|-
| --access-public-folder-editable <on/off>
|Access to public folders. Allows or denies to see public folders.
|-
| --foldertree <0/1>
|0 sets the OX standard folder tree and 1 sets the Outlook-like folder tree.
|-
| --access-olox20 <on/off>
| [DEPRECATED] Access to Olox2.0
|}

=== Access changes for existing users ===

Changes to module access must be done for all users in a given context. On downgrade i. e., to revoke former given access, the data for objects will still be present in the database and on the filestore but is not visible to the customer any more. Please note that only the specified modules are changed. That is why it is required to explicitly turn modules off. A list of packages and the required module configuration is provided in [[the section called “Package access configuration”]].

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
|-A,--adminuser <string>
|Context Admin user name
|-
|-P,--adminpass <string>
|Context Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>contextid {adminuser adminpass} (userid or username) and at minimum one attribute to change</code>'''

primaryMail, Email1 and defaultSenderAddress must be present in set of aliases i. e., whenever you want to change one of
* --email
* --email1
* --defaultsenderaddress
you MUST take care, that the address you want to set is already contained in the aliases of the user.

So when user has aliases: foo, bar and you want to change email to anotheraddr, you
must add anotheraddr to the aliases, first.

If needed, this can be done with one commandline call, e.g.:

'''<code>/changeuser -A oxadmin -P secret -c 666 -i 4 -e
anotheraddr -a foo,bar,anotheraddr</code>'''

=== Command output ===

On success:

<code>user <userid> in <contextid> changed</code>

On failure:

<code>user
<userid> in <contextid> could not be changed: <reason from server></code>

=== Example ===

<code>root@oxhe~#</code>'''<code> changeuser -c 123 -i 3 -p newpwd</code>'''

<code>user 3 in context 123 changed</code>

[[Category: Administrator]]

[[Category: AppSuite]]
[[Category: AdminGuide]]
[[Category: CommandLineTools]]

Open-Xchange Publishing

2018-11-26T08:26:03Z

Daniel.becker: Removed article. Publishing mode was removed a while ago.

The publish mechanism was replaced with version 7.8.0 by the '''''Sharing and Guest Mode'''''. See [https://documentation.open-xchange.com/7.10.1/middleware/components/sharing_guest_mode.html documentation.open-xchange.com] for details.

AppSuite:Sharing and Guest Mode

2018-11-26T08:08:52Z

Daniel.becker: Page moved to https://documentation.open-xchange.com/7.10.1/middleware/components/sharing_guest_mode.html

This article was moved to [https://documentation.open-xchange.com/7.10.1/middleware/components/sharing_guest_mode.html documentation.open-xchange.com]

AppSuite:Sharing and Guest Mode

2018-11-26T08:02:22Z

Daniel.becker: Page moved to https://documentation.open-xchange.com/7.10.1/middleware/components/sharing_guest_mode.html

OX munin scripts

2016-12-08T12:31:30Z

Daniel.becker:

= How to install Munin scripts for Open-Xchange=

== Support for Jolokia ==

By Version 7.4.0, Munin Scripts do support [[Jolokia]] as a bridge to get their information.
This has been done to get less overhead and speak with the corresponding JMX-beans directly.

== Prerequisites ==

Munin node and munin master must be installed and configured prior using the Munin scripts package for Open-Xchange. The installation for this core components differs on various Linux distributions. For details, please visit:

http://munin-monitoring.org/

especially:

http://munin-monitoring.org/wiki/LinuxInstallation

=== open-xchange-munin-scripts ===

== Installation on OX App Suite ==

=== Debian GNU/Linux 7.0 (valid until v7.8.2)===

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/7.8.2/backend/DebianWheezy/ /

# 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/7.8.2/backend/updates/DebianWheezy/ /

and run

$ apt-get update
$ apt-get install open-xchange-munin-scripts

=== 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/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/DebianJessie/ /

and run

$ apt-get update
$ apt-get install open-xchange-munin-scripts

=== SUSE Linux Enterprise Server 11 (valid until v7.8.2) ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/appsuite/7.8.2/backend/SLES11 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/7.8.2/backend/updates/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-munin-scripts

=== 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/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/SLES11 ox-updates

and run

$ zypper ref
$ zypper in open-xchange-munin-scripts

=== 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/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/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-munin-scripts

=== 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/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/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-munin-scripts

=== 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/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/RHEL6/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-munin-scripts

=== 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/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/RHEL7/
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub
# enabled=1
# gpgcheck=1
# metadata_expire=0m

and run

$ yum update
$ yum install open-xchange-munin-scripts

=== open-xchange-munin-scripts-jolokia ===

Munin-scripts for Jolokia need an additional perl modules json and lwp, which are set inside the depenecies. Those should be installed automaticly.

If not, please install the following modules:

Debian: libwww-perl, libjson-perl

rpm: perl-JSON, perl-libwww-perl

== Configuring munin-node scripts for Open-Xchange ==

The configuration of the scripts is done automatically.

Note: The database pool monitoring script will get only configured if the Open-Xchange server is running and the database pools initialized when installing the open-xchange-munin-scripts package. That can be verified by e.g.:

# showruntimestats -x | grep "DB Pool"
com.openexchange.pooling:name=DB Pool 4,NumWaiting = 0
com.openexchange.pooling:name=DB Pool 4,PoolSize = 3
com.openexchange.pooling:name=DB Pool 4,NumBrokenConnections = 0
com.openexchange.pooling:name=DB Pool 4,NumActive = 0
com.openexchange.pooling:name=DB Pool 4,NumIdle = 3
com.openexchange.pooling:name=DB Pool 4,AvgUseTime = 4.948
com.openexchange.pooling:name=DB Pool 4,MaxUseTime = 16777
com.openexchange.pooling:name=DB Pool 4,MinUseTime = 0

=== Configuring for open-xchange-munin-scripts-jolokia ===

Munin Scripts for Jolokia do have some additional settings for [[jolokia]].

<code>vim /etc/munin/plugin-conf.d/ox</code>
{|width="100%" style="table-layout: fixed" class='wikitable sortable' border='1'
! scope="col" width="30%" | Key
! scope="col" width="20%" | Default value
! scope="col" width="35%" | Comment
|-
| env.oxJolokiaUrl
| http://localhost:8009/monitoring/jolokia
| Base url for jolokia
|-
| env.oxJolokiaUser
| "changeMe!Now"
| <nowiki>User used for authentication with HTTP Basic Authentication.</nowiki>
|-
| env.oxJolokiaPassword
| "s3cr3t!toBeChanged"
| <nowiki>Password used for authentification</nowiki>
|}

WARNING: If <code> env.oxJolokiaUser </code> is not changed from its default value <code> changeMe!Now </code>, monitoring will not work as the user <code> changeMe!Now </code> is set to stop monitoring inside the munin scripts.

Both, <code> env.oxJolokiaUser </code> and <code> env.oxJolokiaPassword </code> need to be set to the same value as set inside <code>jolokia.properties</code>

=== Configuring for OX Documents / Documentconverter ===

OX Documents and Documentconverter monitoring can used by installing the additional packages
<code>open-xchange-documents-monitoring</code> and <code>open-xchange-documentconverter-jolokia</code>. The Documentconverter uses a different port to access monitoring data. The corresponding oxJolokiaURL is has to be configured with an entry in the settings.
<pre>
[ox_documentconverter*]
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia
</pre>

See this [[AppSuite:DocumentsMonitoring|article]] for more details.

= Supplementary notes for distributed munin clients =

== Munin node ==
The default munin node configuration only allows connections from localhost, which means that munin master has to run on the same host. If there already is a munin master running, that master IP has to be added to the file <code>/etc/munin/munin-node.conf</code> on each node:

# A list of addresses that are allowed to connect. This must be a
# regular expression, since Net::Server does not understand CIDR-style
# network notation unless the perl module Net::CIDR is installed. You
# may repeat the allow line as many times as you'd like

allow ^127\.0\.0\.1$

== Munin master ==

Make sure the munin and apache packages are installed. If only localhost is going to be monitored, the default configuration is sufficient. Other munin nodes can be added in the <code>/etc/munin/munin.conf</code> file:

# a simple host tree
[localhost.localdomain]
address 127.0.0.1
use_node_name yes

By default, the munin monitoring web page is only reached from localhost, other hosts or networks can be added in <code>/etc/apache2/conf.d/munin</code>:

Allow from localhost 127.0.0.0/8 ::1 # the default setting
Allow from 10.99.0.0/8 # added network

The munin webpage is located at <code>http://yourhost_where_munin_is_running.org/munin</code>.

[[Category: OX6]]
[[Category: Administrator]]

AppSuite:Context management 7 2

2016-12-02T13:57:26Z

Daniel.becker: /* Command output */

== createcontext ==

'''<code>createcontext</code>''' is the tool to create new contexts. A context is an independent instance within the createcontext Open-Xchange system and holds users, groups
and resources and all their objects. Data from one context is not visible to other contexts. Module access (calendar, tasks, email) can be set via predefined "access combination names". These
names can be configured on the server side. All users which are created during later use of the "createuser" tool will inherit the module access rights from the context. If you do not specify any
access rights on createcontext minimal access rights will be granted. Currently, these are Webmail and Contacts access rights.

=== Parameters ===

{| border="1"
|-
| -h,--help
| Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| -c,--contextid <integer>
|The id of the context, when starting with 0, 0 is deleted
|-
| -q,--quota <integer>
|Context wide filestore quota in MB
|-
| -u,--username <string>
|Username for the new context admin user
|-
| -d,--displayname <string>
|Displayname for the new context admin user
|-
| -g,--givenname <string>
|Given name for the new context admin user
|-
| -s,--surname <string>
|Surname/last name for the new context Admin user
|-
| -p,--password <string>
|Password for the new context Admin user
|-
| -e,--email <string>
|Primary E-Mail address for the new context Admin user
|-
| -l,--lang <lang>
|Language for the new context Admin user
|-
| -t,--timezone <timezone>
|Timezone for the new context Amin user
|-
| -N,--contextname <string>
|Context name
|-
| -L,--addmapping <string>
|Add login mappings separated by ","
|-
| --access-combination-name <access-combination-name>
|Access combination name
|-
| --access-denied-portal <on/off>
|Denies portal access (Default is off)
|-
| --csv-import <CSV file>
| Full path to CSV file with user data to import. This option makes mandatory command line options obsolete, except credential options (if needed). But they have to be set in the CSV file.

With this option you can specify a csv file (a full pathname must be given) with the data which should be imported. The columnnames in the CSV file must be
the same as the long-options of the command line tools, without the prefix "--".

This option will normally be used to fill new large installations with the new data. So instead of calling
the command line tools in a shell script every time, just a csv file needs to be created, containing the whole data.
|}

Note that the credentials of the masteradmin in the createcontext call
must be given on the command line with the -A and -P options nevertheless - if authentication is enabled. If the createuser command line tool is used, the credentials are part of the csv file, and
cannot be set as options on the command line itself. The reason for this different behavior is that different contexts have different credentials for the admin user, so they must be set in every
line of the csv file. Opposed to this the credentials of the masteradmin are always the same.

=== Return value ===

<code>0</code> on success

<code><0</code> on failure

=== Mandatory parameters ===

'''<code>contextid {adminuser adminpass} quota username displayname givenname surname password email</code>'''

=== Command output ===

On success:

<code>context <contextid> created</code>

On
failure:

<code>context <contextid> could not be created: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/createcontext
-c 123 -q 1000 -N CompanyA -u "admin" -d "Admin of CompanyA" -g John -s Example -p newpw -e john@example.com</code>'''

<code>context 123
created</code>

== deletecontext ==

'''<code>deletecontext</code>''' is the tool to delete contexts and all data stored that belong to it. This includes all database entries and files in the infostore but no
E-Mail components.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| -c,--contextid <contextid>
|The id of the context
|-
| -N,--contextname <contextname>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>(contextid or contexname) {adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>context <contextid> deleted</code>

On failure:

<code>context <contextid> could not be deleted: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/deletecontext -c
123</code>'''

<code>context 123 deleted</code>

== listcontext ==

'''<code>listcontext</code>''' is the tool to list and search for contexts.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from
output
|-
| -s,--searchpattern <string>
|Search/List pattern, default “*”
|-
| --csv
|Command output as csv
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <adminuser>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>{adminuser adminpass}</code>'''

=== Command output ===

Standard output:

<pre>cid fid fname enabled qmax qused name
lmappings . . ... ... ... ... ... ...
</pre>

csv output:

<code>id,filestore_id,filestore_name,enabled,max_quota,used_quota,name,lmappings</code>

=== Example ===

<pre>root@oxhe:/opt/open-xchange/sbin# ./listcontexts cid fid fname
enabled qmax qused name lmappings 6 3 6_ctx_store true 1000 0 customerA 6,customerA,secondlogin
</pre>

== disablecontext ==

'''<code>disablecontext</code>''' is the tool to disable contexts. Whenever a customer tries to log in to a disabled context, the login is denied.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <string>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>(contextid or
contextname) {adminuser adminpass}</code>'''

=== Command output ===

On
success:

<code>context <contextid> disabled</code>

On failure:

<code>context <contextid> could not be disabled:
<reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/disablecontext -c 123</code>'''

<code>context 123
disabled</code>

== disableallcontexts ==

'''<code>disableallcontexts</code>''' is the tool to disable all contexts. Whenever a customer tries to log in to a disabled context, the login is denied.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user
name
|-
| -P,--adminpass <string>
|Master Admin password
|}
=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>{adminuser
adminpass}</code>'''

=== Command output ===

On success:

<code>all contexts disabled</code>

On failure:

<code>all contexts could not be disabled: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/disableallcontexts</code>'''

<code>all contexts disabled</code>

== enablecontext ==

'''<code>enablecontext</code>''' is the tool to enable a disabled context.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from
output
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <string>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <adminuser>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>(contextid or contextname) {adminuser
adminpass}</code>'''

=== Command output ===

On success:

<code>context <contextid> enabled</code>

On failure:

<code>context <contextid> could not be enabled: <reason from
server></code>

=== Example ===

<code>root@oxhe~#</code>'''<code>/opt/open-xchange/sbin/enablecontext -c 123</code>'''

<code>context <contextid> enabled</code>

== enableallcontexts ==

'''<code>enableallcontexts</code>''' is the tool to enable all disabled contexts.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from
output
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>{adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>all contexts enabled</code>

On failure:

<code>all contexts could not be enabled: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/enableallcontexts</code>'''

<code>all contexts enabled</code>

== changecontext ==

'''<code>changecontext</code>''' makes context-wide changes.<br>

If you specify module access options; e.g. "--access-edit-password on"; then please be aware that basic module access set is the one from context's administrator. Meaning any option not explicitly specified as CLI argument will fall-back to context administrator setting for _every_ user in associated context.<br>

You can use changecontext to change the current quota for a given context. When the context has more changecontext space in use than the new quota allows, the customer is only able to delete files until the usage is below quota. Module access (calendar,tasks,email) can be set via predefined "access combination names". These names can be configured on the server side. All users which are created during later use of the "createuser" tool will inherit the module access rights from the context. If you do not specify any access rights on createcontext minimal access rights will be granted. Currently, these are Webmail and Contacts access rights.

There are some default combinations in the ModuleAccessDefinitions.properties file on the admin server, like:

{| border="1"
|-
|webmail
|webmail, contacts, globaladdressbookdisabled, collectemailaddresses, editpassword
|-
|pim
|webmail, calendar, contacts, tasks, globaladdressbookdisabled, collectemailaddresses, multiplemailaccounts, subscription, publication, editpassword
|-
|pim_infostore
|webmail, calendar, contacts, tasks, infostore, webdav, globaladdressbookdisabled,
collectemailaddresses, multiplemailaccounts, subscription, publication
|-
|pim_mobility
|webmail, calendar, contacts, tasks, syncml, usm, activesync, globaladdressbookdisabled, collectemailaddresses, multiplemailaccounts, subscription, publication, editpassword
|-
|groupware_standard
|webmail, calendar, contacts, infostore, tasks, webdav, ical, vcard, readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, collectemailaddresses, multiplemailaccounts, subscription, publication (Groupware Standard always gets new features except mobility and OXtender. )
|-
|groupware_premium
|webmail, calendar, contacts, infostore, tasks, webdav, webdavxml, ical, vcard, syncml, usm, olox20, activesync, readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, collectemailaddresses, multiplemailaccounts, subscription, publication
|-
|all
|webmail, calendar, contacts, infostore, tasks, webdav, webdavxml, ical, vcard, syncml, usm, olox20, activesync, readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, publicfoldereditable, collectemailaddresses, multiplemailaccounts, subscription, publication
|}

When having changed the access rights of the context and its users with "changecontext" the "downgrade" command should be called on the admin server. All unnecessary data are removed from
the data base via "groupware api". If e. g. the context 1 is changed from "pim_infostore" to "webmail", the "downgrade" command has to be called for this context then. Then, all unnecessary
folders for this context are removed from the data base.

=== Parameters ===

{| border="1"
|-
| -h,--help
| Prints a help text
|-
| --environment
| Show info about commandline environment
|-
| --nonl
| Remove all newlines (\n) from output
|-
| -A,--adminuser <adminuser>
| master Admin user name
|-
| -P,--adminpass <adminpass>
| master Admin password
|-
| -c,--contextid <contextid>
| The id of the context
|-
| -N,--contextname <contextname>
| context name
|-
| -q,--quota <quota>
| Context wide filestore quota in MB.
|-
| --extendedoptions
| Set this if you want to see all options, use this instead of help option
|-
| -L,--addmapping <addmapping>
| Add login mappings.Seperated by ","
|-
| -R,--removemapping <removemapping>
| Remove login mappings.Seperated by ","
|-
| --access-combination-name <access-combination-name>
| Access combination name
|-
| --capabilities-to-add <capabilities-to-add>
| The capabilities to add as a comma-separated string; e.g. "portal, -autologin"
|-
| --capabilities-to-remove <capabilities-to-remove>
| The capabilities to remove as a comma-separated string; e.g. "cap2, cap2"
|-
| --quota-module <quota-module>
| The (comma-separated) list of identifiers for those modules to which to apply the quota value; currently supported values: [task, calendar, contact, infostore]
|-
| --quota-value <quota-value>
| The numeric quota value specifying the max. number of items allowed for context; zero is unlimited
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,- -adminuser <string>
|Master Admin
user name
|-
| -P,- -adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>(contextid or
contextname) {adminuser adminpass} and at minimum one attribute to change</code>'''

=== Command output ===

On success:

<code>context <contextid> changed</code>

On failure:

<code>context
<contextid> could not be changed: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/changecontext -c 123 -q
500</code>'''

<code>context 123 changed</code>

== getAdminId ==

Returns the ID of the context administrator.

[[Category: Administrator]]

[[Category: AppSuite]]
[[Category: AdminGuide]]
[[Category: Administrator]]

== getSchemaName (since v7.4.2) ==

Returns the name of the database schema in which a specified context is located.

=== Parameters ===

{| border="1"
|-
| -h,--help
| Prints a help text
|-
| --environment
| Show info about commandline environment
|-
| --nonl
| Remove all newlines (\n) from output
|-
| -A,--adminuser <adminuser>
| master Admin user name
|-
| -P,--adminpass <adminpass>
| master Admin password
|-
| -c,--contextid <contextid>
| The id of the context
|-
| -N,--contextname <contextname>
| context name
|}

=== Mandatory parameters ===

'''<code>(contextid or contexname) {adminuser adminpass}</code>'''

=== Command output ===

"Schema name for context " + <context-id> + ": " + <schema-name>

== includestacktrace (since v.7.4.2) ==
Enables/disables to include stack trace information (if any) in HTTP-API JSON responses for a certain user

=== Parameters ===

{| border="1"
|-
| -h,--help
| Prints usage of the command line tool
|-
| -e,--enable
| Enables to include stack trace information (if any) in HTTP-API JSON responses)
|-
| -d,--disable
| Disables to include stack trace information (if any) in HTTP-API JSON responses
|-
| -c,--context <contextid>
| The context identifier
|-
| -u,--user <userid>
| The user identifier
|}

The flags -e and -d are mutually exclusive.

=== Mandatory parameters ===

'''{<code>context</code>} {<code>user</code>} {<code>enable|disable</code>}'''

=== Command output ===

Including stack trace information successfully enabled|disabled for user <user-id> in context <context-id>

=== Examples ===
Enable to include stack trace information for user 1618 in context 314

<code># includestacktrace -u 1618 -c 314 -e

== sanitizefilemimetypes (since v.7.4.2) ==
Sanitizes those file entries that hold a broken/corrupt MIME type information

=== Parameters ===

{| border="1"
|-
| -h,--help
| Prints usage of the command line tool
|-
| -c,--context <contextid>
| The context id
|-
| -a,--all
| The flag to signal that all contexts shall be processed. Hence option -c/--context is then obsolete.
|-
| -i,--invalids
| An optional comma-separated list of those MIME types that should be considered as broken/corrupt. Default is "application/force-download, application/x-download, application/$suffix"
|}

The options -c/--context and -a/--all are mutually exclusive.

=== Mandatory parameters ===

'''contextid or all'''

=== Command output ===
A short result description; e.g. "Fixed 123 documents with a broken/corrupt MIME type in context 456"

== checkloginmappings (since v.7.6.0) ==
Checks (and fixes) those context-related entries in login2context mappings that miss the actual context identifier

=== Parameters ===

{| border="1"
|-
| -h,--help
| Prints usage of the command line tool
|-
| -c,--context <contextid>
| The context id
|-
| -a,--all
| The flag to signal that all contexts shall be processed. Hence option -c/--context is then obsolete.
|-
| -A,--adminuser
| Admin username. In case -a/--all is provided master administrator's user name is required; else the one for context administrator
|-
| -P,--adminpass
| Admin password. In case -a/--all is provided master administrator's password is required; else the one for context administrator
|}

The options -c/--context and -a/--all are mutually exclusive.

=== Mandatory parameters ===

'''contextid or all'''

=== Command output ===
A short result description; e.g. "Fixed 123 documents with a broken/corrupt MIME type in context 456"

[[Category: Administrator]]

[[Category: AppSuite]]
[[Category: AdminGuide]]
[[Category: Administrator]]
[[Category: CommandLineTools]]

AppSuite:Filestorages

2016-10-17T10:38:34Z

Daniel.becker: /* Registering your app */

= Common preparations =
This page shows how to setup external file stores. For all of these file stores you have to install the package "open-xchange-oauth", which provides the necessary authentication mechanisms.

Moreover your setup is required to be reachable via HTTPS, since the providers expect that a call-back URL to your setup is specified. Such a call-back URL is only accepted if it contains the <source enclose="none" lang="java">"https://"</source> scheme., e.g.:
<syntaxhighlight lang="java">
"https://my.oxsetup.invalid/ajax/defer"
</syntaxhighlight>

== Keep HTTPS protocol ==
[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the Open-Xchange nodes. To let the Open-Xchange application know about the HTTPS protocol that is used to communicate with the Apache server:
* Either set a special header in the SSL virtual hosts configurations in Apache to forward this information. The de facto standard for this is the <source enclose="none" lang="java">"X-Forwarded-Proto"</source> header. See [[Appsuite:Grizzly#X-FORWARDED-PROTO_Header]] for how to setup that header.
* Or force the Open-Xchange application to assume it is reached via SSL through setting property <source enclose="none" lang="properties">"com.openexchange.forceHTTPS=true"</source> in file ''/opt/open-xchange/etc/server.properties''.

== Deferrer URL ==
Open-Xchange application uses the deferrer URL as call-back for some of the providers, which use OAuth v2.0 authentication (such as Google).

If your OX server is reachable only via one host name, you won't have to do anything. If it is reachable by more than one host name, create or open the file ''/opt/openexchange/etc/groupware/deferrer.properties'' and set the properties therein as such:
<syntaxhighlight lang="properties">
com.openexchange.http.deferrer.url=https://mymaindomain.invalid
</syntaxhighlight>

= Dropbox =

To setup the Dropbox file store you have to install the package "open-xchange-file-storage-dropbox".

== Registering your app ==
* Log in to your Dropbox account [https://www.dropbox.com/login here], and create your Dropbox app [https://www.dropbox.com/developers/apps/create here]
* There are two options available creating an app, Drops-in App & Dropbox API App. Please select '''Dropbox API''' app and enter the name of your app.
* Go to [https://www.dropbox.com/developers/apps App Console] and select your created app. Select settings tab to view the <source enclose="none" lang="java">APP_KEY</source> (App key) and <source enclose="none" lang="java">SECRET_KEY</source> (App secret)

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/dropboxoauth.properties'':

* Enable the OAuth connector to Dropbox OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.apiKey=REPLACE_THIS_WITH_DROPBOX_APP_KEY
com.openexchange.oauth.dropbox.apiSecret=REPLACE_THIS_WITH_DROPBOX_APP_SECRET
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-dropbox|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Google Drive =

To setup the Google Drive file store you have to install the package "open-xchange-file-storage-googledrive".

== Registering your app ==
* Sign in to [https://console.developers.google.com/ Google Developers Console] using your Google account
* Please follow [https://developers.google.com/identity/sign-in/web/devconsole-project these] instructions to create a new project with a client ID, which is needed to call the sign-in API
* Enable the following APIs for your project
** BigQuery API
** Calendar API
** Contacts API
** Drive API
** Drive SDK
** Gmail API
** Google Cloud SQL
** Google Cloud Storage
** Google Cloud Storage JSON API

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/googleoauth.properties'':

* Enable the OAuth connector to Google OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.google=true
</syntaxhighlight>
<br>

* Set the API key and secret, which is Client ID and Client Secret to call the sign-in API (Select your project, select API manager from upper left burger menu, select credentials in left side bar, select Client ID for Web application)
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.apiKey=REPLACE_THIS_WITH_YOUR_CLIENT_ID
com.openexchange.oauth.google.apiSecret=REPLACE_THIS_WITH_YOUR_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL. Please ensure the following conditions are met:
** The redirect URL specified in the Google App needs to be the same as the one specified by this property.
** The redirect URI uses <source enclose="none" lang="java">"https://"</source> as protocol
** The redirect URI follows the pattern: <source enclose="none" lang="java">"https://" + <host-name> + "/ajax/defer"</source>
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.redirectUrl=
</syntaxhighlight>
E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
<br>

* Set the product ID of the registered Google app
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.productName=
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-googledrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Microsoft Onedrive =
To setup the Microsoft OneDrive file store you have to install the package "open-xchange-file-storage-onedrive".

== Registering your app ==
* Please follow [https://msdn.microsoft.com/en-us/library/ff751474.aspx this guide] to create/register your app

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/msliveconntectoauth.properties'':

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect.apiKey=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_KEY
com.openexchange.oauth.msliveconnect.apiSecret=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.msliveconnect.redirectUrl=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_REDIRECT_URL
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-onedrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Box.com =
To setup the Box.com file store you have to install the package "open-xchange-file-storage-boxcom".

== Registering your app ==
* Sign in to [https://developers.box.com/ box Developers]
* Select '''Create a Box Application'''
* Select '''Box Content'''
* Hit '''Configure your application'''
* Enter ''redirect_uri''' (the deferrer URL; e.g. <source enclose="none" lang="java">"https://my.oxsetup.invalid/ajax/defer"</source>)
* Enable ''Read and write all files and folders''

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/boxcomoauth.properties'':

* Enable the OAuth connector
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom=true
</syntaxhighlight>
<br>

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.apiKey=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_KEY
com.openexchange.oauth.boxcom.apiSecret=REPLACE_THIS_WITH_YOUR_BOX_CLIENT_SECRET
</syntaxhighlight>
<br>

* Set the redirect URL
<syntaxhighlight lang="properties">
com.openexchange.oauth.boxcom.redirectUrl=REPLACE_THIS_WITH_YOUR_BOX_REDIRECT_URL
</syntaxhighlight>
<br>

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-boxcom|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

Login variations

2016-10-14T08:13:15Z

Daniel.becker: /* IP Check */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store.

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

====Security of a cookie====
Cookies can be configured in different ways to be secure. For further information visit [[OXSessionSecurityFeatures]]

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges. For further information on the configuration see [https://oxpedia.org/wiki/index.php?title=AppSuite:Configuration_properties_7.8.2 configuration properties].

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

For further information on the session see [[OXSessionLifecycle]].

For further information on HTTP API visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T08:08:45Z

Daniel.becker: /* Authentication against other services */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store.

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

====Security of a cookie====
Cookies can be configured in different ways to be secure. For further information visit [[OXSessionSecurityFeatures]]

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

For further information on the session see [[OXSessionLifecycle]].

For further information on HTTP API visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T08:01:33Z

Daniel.becker: /* Authentication against other services */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store.

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

====Security of a cookie====
Cookies can be configured in different ways to be secure. For further information visit [[OXSessionSecurityFeatures]]

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

For further information on the session visit [[OXSessionLifecycle]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T07:57:48Z

Daniel.becker: /* Cookie Handling */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store.

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

====Security of a cookie====
Cookies can be configured in different ways to be secure. For further information visit [[OXSessionSecurityFeatures]]

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T07:52:05Z

Daniel.becker: /* Only one cookie per client session type */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store.

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T07:48:41Z

Daniel.becker: /* Lifetime of cookies */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T07:48:33Z

Daniel.becker: /* Naming of cookies */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

===Lifetime of cookies===
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T07:48:21Z

Daniel.becker: /* Only one cookie per client session type */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

=== Naming of cookies ===
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

===Lifetime of cookies===
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T07:40:15Z

Daniel.becker: /* IP Check */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

=== Only one cookie per client session type ===
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

=== Naming of cookies ===
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

===Lifetime of cookies===
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-14T07:39:47Z

Daniel.becker: /* Access via web browser with user credentials */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

=== Only one cookie per client session type ===
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

=== Naming of cookies ===
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

===Lifetime of cookies===
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-10-10T12:51:51Z

Daniel.becker: /* Access via web browser with user credentials */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

=== Only one cookie per client session type ===
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

=== Naming of cookies ===
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

===Lifetime of cookies===
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange Server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 8. - 10. until end of session

For any details on the requests please visit https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

Login variations

2016-09-29T09:48:09Z

Daniel.becker: /* Access via web browser with user credentials */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

=== Only one cookie per client session type ===
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

=== Naming of cookies ===
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

===Lifetime of cookies===
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the valid session after the authentication:

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

# Browser sends initial request to the Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# Open-Xchange Server sends AJAX application to browser it is loaded, no data is exchanged
# User enters username and password in the front-end
# Username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request
# The server authenticates and sends following data back to the browser via JSON (the data are all saved in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser. If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# AJAX front-end saves the SessionID in memory. AJAX front-end ignores random token
# AJAX sends initial data request via JSON to the Open-Xchange Server and provides following data:
## SessionID in JSON object
## Open-Xchange Server processes this data request and requests from browser the cookie with Session-Secret
# Open-Xchange Server compares:
## SessionID for validity in sessiond
## Session-Secret from Cookie for validity with sessiond
# Request is correctly authenticated and is answered
# Random token is discarded after timeout from sessiond
# If persistent auto-login is selected
## Cookie with SessionID is set to the browser. The cookie is configured with the relevant type and validity
# Repeat 7. - 10. until end of session

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]
* [[Authentication LDAP Plugin description]]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]