Implementing an Application Integration Server

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.