imip-agent

Annotated docs/wiki/WebServerIntegration

1214:3bc482b5f33e
1024:48b37822d2a0
988:d1375269e287
2016-01-29 Paul Boddie file changeset files shortlog Moved common test initialisation into a separate script.
paul@933 1 
= Web Server Integration =
paul@933 2 
 
 paul@934      3 
Although imip-agent is mostly concerned with e-mail messaging, it can
 
 paul@934      4 
integrate with a Web server for the following purposes:
 
 paul@933      5 
 
 paul@961      6 
 * To [[../FreeBusyPublishing|publish free/busy information]] for calendar users
 
 paul@961      7 
 * To provide a [[../CalendarManager|management interface]] for calendar users
 
 paul@933      8 
 
 paul@934      9 
Currently, imip-agent provides configuration files for Apache, but other Web
 
 paul@934     10 
servers may also be supported.
 
 paul@933     11 
 
 paul@961     12 
== Authentication and Access Control in Apache ==
 
 paul@933     13 
 
 paul@934     14 
Apache supports a range of mechanisms for protecting resources and
 
 paul@934     15 
authenticating users. Most usefully for imip-agent given the
 
 paul@934     16 
[[../MailIntegration|e-mail integration]] requirements, modules supporting
 
 paul@934     17 
[[http://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html|LDAP]] and
 
 paul@949     18 
[[http://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html|text-based lists]]
 
 paul@949     19 
of users are available for such purposes.
 
 paul@961     20 
 
 paul@961     21 
== Configuring Web Servers for Free/Busy Publishing ==
 
 paul@961     22 
 
 paul@961     23 
Each user may request the [[../FreeBusyPublishing|publishing]] of their
 
 paul@961     24 
free/busy information by configuring certain settings. The
 
 paul@961     25 
`conf/apache/imip-agent.conf` file provides a configuration file for
 
 paul@961     26 
deployment with the Apache Web server software that exposes a directory for
 
 paul@961     27 
Web publishing containing the published free/busy information.
 
 paul@961     28 
 
 paul@963     29 
On Debian, to enable the serving of free/busy data, copy the configuration
 
 paul@963     30 
file to the Apache configuration and enable it as follows
 
 paul@963     31 
 
 paul@963     32 
{{{
 
 paul@963     33 
cp conf/apache/imip-agent.conf /etc/apache2/sites-available/
 
 paul@963     34 
a2ensite imip-agent
 
 paul@963     35 
}}}
 
 paul@963     36 
 
 paul@961     37 
Access to free/busy information may not be moderated, but Web server
 
 paul@961     38 
directives can be introduced to impose access controls. Mail programs that
 
 paul@961     39 
wish to consult the free/busy information may have problems in dealing with
 
 paul@961     40 
authentication mechanisms, however, and it may be regarded as acceptable in
 
 paul@961     41 
certain environments to expose such information publicly or with
 
 paul@961     42 
network-specific access constraints.
 
 paul@961     43 
 
 paul@961     44 
== Configuring Web Servers for the Calendar Management Interface ==
 
 paul@961     45 
 
 paul@961     46 
A [[../CalendarManager|calendar management interface]] is provided to allow
 
 paul@961     47 
users to view and interact with their calendars through the Web. The
 
 paul@961     48 
`conf/apache/imip-manager.conf` file provides a configuration file for
 
 paul@961     49 
deployment with the Apache Web server software that enables this interface.
 
 paul@961     50 
 
 paul@988     51 
=== Configuring the Management Interface ===
 
 paul@988     52 
 
 paul@988     53 
The `config.py` file described in the [[../Configuration|configuration guide]]
 
 paul@988     54 
provides some settings that can be adjusted to configure the management
 
 paul@988     55 
interface.
 
 paul@988     56 
 
 paul@988     57 
{{{{#!table
 
 paul@988     58 
'''Setting''' || '''Result'''
 
 paul@988     59 
==
 
 paul@988     60 
`MANAGER_INTERFACE`
 
 paul@988     61 
|| If set to `True`, causes links to the interface to be included in
 
 paul@988     62 
.. notification messages sent by imip-agent. If set to `False`, such links
 
 paul@988     63 
.. will be omitted.
 
 paul@988     64 
==
 
 paul@988     65 
`MANAGER_URL`
 
 paul@988     66 
|| The deployment URL of the management interface. Together with the
 
 paul@988     67 
.. `MANAGER_PATH` described below, this forms the basis of the links
 
 paul@988     68 
.. described above. Some examples:
 
 paul@988     69 
{{{
 
 paul@988     70 
http://webserver.example.com/
 
 paul@988     71 
http://webserver.example.com/webapps/
 
 paul@988     72 
}}}
 
 paul@988     73 
It can be left as `None` and a default URL will be built using the
 
 paul@988     74 
hostname of the system running the software.
 
 paul@988     75 
==
 
 paul@988     76 
`MANAGER_URL_SCHEME`
 
 paul@988     77 
|| The URL scheme or protocol employed if a default URL is being constructed
 
 paul@988     78 
.. instead of `MANAGER_URL` providing a value. Some examples:
 
 paul@988     79 
{{{
 
 paul@988     80 
http://
 
 paul@988     81 
https://
 
 paul@988     82 
}}}
 
 paul@988     83 
Since the manager is only likely to be available via common Web protocols,
 
 paul@988     84 
other values may not make much sense.
 
 paul@988     85 
==
 
 paul@988     86 
`MANAGER_PATH`
 
 paul@988     87 
|| The "path info" added to the `MANAGER_URL` that locates the management
 
 paul@988     88 
.. interface in its deployment location. Some examples:
 
 paul@988     89 
{{{
 
 paul@988     90 
/
 
 paul@988     91 
/imip-agent
 
 paul@988     92 
}}}
 
 paul@988     93 
This setting affects the `imip-manager.conf` file, whose `Alias`, `ScriptAlias`
 
 paul@988     94 
and `Location` directives should be changed if this setting is changed.
 
 paul@988     95 
}}}}
 
 paul@988     96 
 
 paul@988     97 
=== Deploying the Configuration ===
 
 paul@988     98 
 
 paul@963     99 
On Debian, to enable the management interface, copy the configuration file to
 
 paul@963    100 
the Apache configuration and enable it as follows:
 
 paul@963    101 
 
 paul@963    102 
{{{
 
 paul@963    103 
cp conf/apache/imip-manager.conf /etc/apache2/sites-available/
 
 paul@963    104 
a2ensite imip-manager
 
 paul@963    105 
}}}
 
 paul@963    106 
 
 paul@961    107 
The management interface is deployed as a CGI program, meaning that a suitable
 
 paul@961    108 
module must be enabled in the Apache configuration. On Debian, this is done as
 
 paul@961    109 
follows:
 
 paul@961    110 
 
 paul@961    111 
{{{
 
 paul@961    112 
a2enmod cgi
 
 paul@961    113 
}}}
 
 paul@961    114 
 
 paul@961    115 
Since such access to calendars should only be performed by identified
 
 paul@961    116 
users, access controls are suggested in the configuration file. Modules
 
 paul@961    117 
providing additional authentication support may need to be enabled. For
 
 paul@961    118 
example, on Debian, the LDAP authentication/authorisation support is enabled
 
 paul@961    119 
as follows:
 
 paul@961    120 
 
 paul@961    121 
{{{
 
 paul@961    122 
a2enmod authnz_ldap
 
 paul@961    123 
}}}
 
 paul@988    124 
 
 paul@988    125 
=== Authenticating Users ===
 
 paul@988    126 
 
 paul@988    127 
The `imip-manager.conf` file contains example directives for accessing
 
 paul@988    128 
authentication services or data.
 
 paul@988    129 
 
 paul@988    130 
Where LDAP authentication is to be used, the appropriate LDAP URL needs to be
 
 paul@988    131 
specified using a directive. For example:
 
 paul@988    132 
 
 paul@988    133 
{{{
 
 paul@988    134 
AuthLDAPUrl "ldap://localhost/ou=People,dc=example,dc=com?mail?sub"
 
 paul@988    135 
}}}
 
 paul@988    136 
 
 paul@988    137 
Here, the `mail` attribute is used to match the username provided in the
 
 paul@988    138 
authentication dialogue. Configuration changes may be required within the LDAP
 
 paul@988    139 
infrastructure to allow this mechanism to function, but this is not described
 
 paul@988    140 
here.
 
 paul@988    141 
 
 paul@988    142 
Meanwhile, particularly where [[../MailIntegration/Simple|simple integration]]
 
 paul@988    143 
strategies have been chosen, a plain text user file can be employed to
 
 paul@988    144 
authenticate users. For example:
 
 paul@988    145 
 
 paul@988    146 
{{{
 
 paul@988    147 
AuthUserFile /var/www/imip-agent/users
 
 paul@988    148 
}}}
 
 paul@988    149 
 
 paul@988    150 
Such a file should be created using the usual tools provided by the Apache Web
 
 paul@988    151 
server distribution.