Implementing an Application Integration Server

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 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.

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

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
}

Using the Application Integration

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.

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
  URL which the instance should connect to.
  • Ignore SSL warnings
    Activate this option if a self-signed or non-public certificate is used on the HTTP server.
  • Server requires authentication
    If the HTTP server requires authentication to access the specified URL, check this option to enable the User Name and Password fields.
• User Name
  User name for basic authentication to access the given URL.
• Password
  Password for basic authentication to access the given URL.

Options

• Automatically delete users in MailStore Server
  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

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. To finally run the synchronization, click on Synchronize now. The results are shown with any changes committed to the instance's user database.