Difference between revisions of "Implementing an Application Integration Server"

[unchecked revision][checked revision]
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
In addition to adding users manually, an instance can synchronize its internal user database with different directory services like Active Directory, MDaemon, IceWarp MailServer or Kerio Connect.
+
The following describes how to implement your own Application Integration server to synchronize users from sources that are not natively supported by MailStore. This can be virtually any user database that can be accessed via programming or scripting languages, for instance SQL server databases or plain text files. Using an Application Integration server as a directory service for synchronization and authorization in a MailStore SPE Instance is described in [[Instance Administration]].
  
The following describes how to synchronize users from sources that are not natively supported by MailStore Service Provider Edition. This can be virtually any user database that can be accessed via programming or scripting languages, for instance SQL server databases or plain text files.
+
Application Integration servers can be written in any programming or scripting language. They must either provide their own HTTP server interface or be accessible through an existing HTTP server.
 
 
== Implementing an Application Integration Server ==
 
 
 
Before connecting an instance to a user directory using the Application Integration, an appropriate Application Integration server has to be created first.
 
 
 
Application Integration servers can be written in any programming or scripting language. They must either provide their own HTTP server interface or be accessible via an existing HTTP server.
 
 
 
=== Synchronizing Users ===
 
  
 +
== Synchronizing Users ==
 
The Application Integration server must accept the following parameter via HTTP POST request to initialize the synchronization.
 
The Application Integration server must accept the following parameter via HTTP POST request to initialize the synchronization.
  
Line 88: Line 81:
 
</source>
 
</source>
  
=== Authenticating Users ===
+
== Authenticating Users ==
 
The Application Integration server must accept the following parameters via HTTP POST request to authenticate users.
 
The Application Integration server must accept the following parameters via HTTP POST request to authenticate users.
  
Line 162: Line 155:
 
</source>
 
</source>
  
== Using the Application Integration ==
+
== Example Server Implementations ==
During synchronization, user information such as user names and email addresses are read and recorded in the instance's user database. No changes are made to the source database where user information is synchronized from.
+
<div class=msnote>'''Important notice:''' The Application Integration Server implementations on this website is to be regarded as example implementations. These examples should help system administrators and developers to quickly understand how an Application Integration Server works and how to use them in their own environment.<br/>
 
+
Please understand that beyond this documentation no further support for the Application Integration Server examples are provided. Unless stated otherwise, these examples are released under the terms and conditions of the [[wikipedia:MIT_License|MIT License]].</div>
=== Accessing Directory Service Integration ===
 
* Log on to the MailStore Service Provider Edition instance as an administrator.
 
* Click on ''Administrative Tools'' > ''Users and Privileges'' and then on ''Directory Services''.
 
* In the ''Integration'' section, change the directory service type to ''Application Integration''.
 
 
 
=== Connection ===
 
For synchronization, the instance requires information on how to connect to the Application Integration server.
 
 
 
* '''URL'''<br/>URL which the instance should connect to.
 
** ''Ignore SSL warnings''<br/>Activate this option if a self-signed or non-public certificate is used on the HTTP server.
 
** ''Server requires authentication''<br/>If the HTTP server requires authentication to access the specified URL, check this option to enable the ''User Name'' and ''Password'' fields.
 
* '''User Name'''<br/>User name for basic authentication to access the given URL.
 
* '''Password'''<br/>Password for basic authentication to access the given URL.
 
 
 
=== Options ===
 
* '''Automatically delete users in MailStore Server'''<br/>Here you can choose whether users whose accounts have been deleted in the source database will also be deleted in MailStore Server's user database by the synchronization. If the archive folder of such a user already contains archived emails, only the user entry but not its archive folder will be deleted in MailStore Server. Additionally, only MailStore Server users that have their authentication method set to ''Directory Services'' will be deleted.
 
 
 
=== Assign Default Privileges ===
 
By default, users that have been synchronized to an instance have the privilege to log on as well as read access to their own user archive.
 
You can configure those default privileges before synchronization, for example, to assign the privilege ''Archive E-mail'' to all new users. To do this, click on ''Default Privileges...''
 
  
=== Run Directory Services Synchronization ===
+
=== Python ===
Click on ''Test Settings'' to check synchronization configuration and the results returned by the Application Integration server without any changes to the instance's user database being actually committed.
+
An implementation of a modular Application Integration Server written in Python can be found in the [[Media:Application-integration-server.zip|Application-integration-server.zip]] file.
To finally run the synchronization, click on ''Synchronize now''. The results are shown with any changes committed to the instance's user database.
 

Latest revision as of 14:39, 19 April 2017

The following describes how to implement your own Application Integration server to synchronize users from sources that are not natively supported by MailStore. This can be virtually any user database that can be accessed via programming or scripting languages, for instance SQL server databases or plain text files. Using an Application Integration server as a directory service for synchronization and authorization in a MailStore SPE Instance is described in Instance Administration.

Application Integration servers can be written in any programming or scripting language. They must either provide their own HTTP server interface or be accessible through an existing HTTP server.

Synchronizing Users

The Application Integration server must accept the following parameter via HTTP POST request to initialize the synchronization.

Name Description
cmd For synchronizing users the cmd parameter must be set to list.

The returned HTTP response must contain valid JSON formatted data. When synchronizing users, the following data structure is expected for each user object. Multiple users must be returned as an array of JSON objects.

Name Type
userName string
distinguishedName string (optional)
fullName string (optional)
emailAddresses array (optional)

Example

HTTP Request

POST /mailstore-integration/index.php HTTP/1.1
Authorization: Basic bWFpbHN0b3JlQGV4YW1wbGUudGVzdDpQYXNzdzByZA==
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
Host: mail.example.test
Accept: */*
Content-Length: 8
Content-Type: application/x-www-form-urlencoded
 
cmd=list

HTTP Response

HTTP/1.1 200 OK
X-Powered-By: PHP/5.4.4-14+deb7u5
Content-Type: text/json; charset=utf8
Date: Fri, 13 Dec 2013 14:20:27 GMT
Server: lighttpd/1.4.31
Content-Length: 23812
Accept-Ranges: none
Connection: Keep-Alive

[
  {
    "userName": "john.doe",
    "distinguishedName": "UID=john.doe,DC=example,DC=com",
    "fullName": "john.doe",
    "emailAddresses": [
      "[email protected]",
      "[email protected]"
    ]
  },
  {
    "userName": "jane.doe",
    "distinguishedName": "UID=jane.doe,DC=example,DC=com",
    "fullName": "jane.doe",
    "emailAddresses": [
      "[email protected]",
      "[email protected]"
    ]
  }
]

Authenticating Users

The Application Integration server must accept the following parameters via HTTP POST request to authenticate users.

Name Description
cmd For authenticating users the cmd parameter must be set to auth.
user The user parameter contains the user name to be authenticated.
pass The pass parameter contains the password to be verified.

The returned HTTP response must contain valid JSON formatted data. When authenticating users, the following data structure is expected.

Name Type
succeeded boolean

Examples

HTTP Request

POST /mailstore-integration/index.php HTTP/1.1
Authorization: Basic bWFpbHN0b3JlQGV4YW1wbGUudGVzdDpQYXNzdzByZA==
User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
Host: mail.example.test
Accept: */*
Content-Length: 8
Content-Type: application/x-www-form-urlencoded

cmd=auth&user=john.doe&pass=Passw0rd

HTTP Response - Authentication Successful

HTTP/1.1 200 OK
X-Powered-By: PHP/5.4.4-14+deb7u5
Content-Type: text/json; charset=utf8
Date: Fri, 13 Dec 2013 14:20:27 GMT
Server: lighttpd/1.4.31
Content-Length: 21
Accept-Ranges: none
Connection: Keep-Alive

{
  succeeded: true
}

HTTP Response - Authentication Failed

HTTP/1.1 200 OK
X-Powered-By: PHP/5.4.4-14+deb7u5
Content-Type: text/json; charset=utf8
Date: Fri, 13 Dec 2013 14:20:27 GMT
Server: lighttpd/1.4.31
Content-Length: 22
Accept-Ranges: none
Connection: Keep-Alive

{
  succeeded: false
}

Example Server Implementations

Important notice: The Application Integration Server implementations on this website is to be regarded as example implementations. These examples should help system administrators and developers to quickly understand how an Application Integration Server works and how to use them in their own environment.
Please understand that beyond this documentation no further support for the Application Integration Server examples are provided. Unless stated otherwise, these examples are released under the terms and conditions of the MIT License.

Python

An implementation of a modular Application Integration Server written in Python can be found in the Application-integration-server.zip file.