Difference between revisions of "Implementing an Application Integration Server"

[unchecked revision]

Revision as of 15:26, 23 March 2015

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 - Inside the Instance.

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
}

@@ 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_Management_-_Instance_Administration#Inside_the_Instance|Instance Administration - Inside the Instance]].
-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 ===
@@ Line 161: / Line 155: @@
 }
 </source>
-== 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'''<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 ===
-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.