ExternalAppsSync
Version 2 (tash, Apr 07, 2012 07:13 pm) → Version 3/5 (diabeteman, Apr 08, 2012 03:31 am)
{{toc}}
h1. Synchronization of External Applications with ECM
{{toc}}
</span>
ECM has a binding system that allows external applications (such as forums, wikis, killboards, etc.) to fetch their security access configuration (basically which users are in which groups) from ECM.
h2. How does it work?
First, you must note that ECM has its own user database with their passwords. The users are automatically assigned to groups by the scheduler so that group assignations match the In-Game titles of the characters owned by each user.
To make it simple: *One In-Game title <
h1.
> One ECM group*. Users have *all groups that match the titles of the characters* they own.
ECM database also contains a table where you can add external applications (_common_externalapplication_). With this table, two other tables __== common_groupbinding ==__, `common_userbinding` allow the association of one ECM internal user or group with an external id.
With this information, ECM can easily provide a *translation* of its internal security access configuration (which users are in which groups) for any external application *that has group & user bindings*.
As a schema is often better than an explanation:
!external_app_sync.png!
(1) You must provide a HTTP front-end (php, python, perl script) which will return a user_id of the external application when requested with a username and password. You will find more information about this [ExternalAppsSync#Prepare_and_install_a_script_attached_to_your_external_applicati here].
(2) You must provide a script that will fetch JSON data from ECM and update the external application _user_groups_ table from this data. There is an "example script for PHPBB3":http://code.google.com/p/eve-corp-management/source/browse/src/scripts/phpbb3_sync.php in ECM package.
h2. Kewl, how do I use this? (Example)
Here is a detailed example on how to setup sync between ECM and a "PHPBB":http://www.phpbb.com forum. Let's say we want five PHPBB groups to be synchronized with In-Game titles.
|| *PHPBB group* ||
|| Corp Members ||
|| Directors ||
|| Cap Pilots ||
|| Production Manager ||
|| HR Team ||
h3. Create an External Application
Let's login to the administration panel in ECM via [http://ecm.myserver.com/admin/]. Here, you can manage most of the objects stored in ECM database. We will focus on the **Common** frame for this tutorial.
!app.jpg!
First thing we want to do is create an external application, click on the corresponding *Add* button, and fill the fields.
!add.jpg!
* *name*: An internal name for your application in ECM. This name will be displayed when members activate the binding of their account.
* *url*: An URL accessible from ECM server. This URL should return a _user_id_ when challenged with a username and password. More information on this in the next section.
When you are done, click *Save*.
h2. = Prepare and install a script attached to your external application
The URL you gave in the previous step points to a php script. This script should accept POST requests with 2 parameters: *username* and *password*. If the *username* is present in the forum's database and matches with the *password*, the script should return a simple response with the *user_id* corresponding to the *username*.
You will find an "example script for PHPBB3":http://code.google.com/p/eve-corp-management/source/browse/src/scripts/phpbb3_simple_auth.php embedded in ECM installation. Depending on the version of PHPBB you use (or if you don't use PHPBB), the script may vary (could be a perl script, CGI, python, whatever...). *It just needs to be accessible through an HTTP POST request and comply to the spec above*.
Look at [ExternalAppsSync#How_does_it_work? the schema at the beginning] around the yellow (1) mark for an illustration.
h3. Create group bindings
Next step is to create group bindings. We want some PHPBB groups to be associated with multiple In-Game titles. This way, if a player owns a character that has at least one of these titles, she/he will be put in the associated PHPBB group.
Here are the associations we want to have:
|| *ECM group (In-Game title)* || *PHPBB group* || *PHPBB group_id* ||
|| Junior Member || Corp Members || 5 ||
|| Member || Corp Members || 5 ||
|| Senior Member || Corp Members || 5 ||
|| Directors || Directors || 1547 ||
|| Cap Pilot || Cap Pilots || 45 ||
|| Production Officer || Production Manager || 167 ||
|| Production Director || Production Manager || 167 ||
|| HR Officer || HR Team || 457 ||
In ECM administration panel, you can create *Group bindings* to reflect the table above.
!groupbinding.jpg!
h3. Ask users to activate the binding of their accounts
Once the group bindings are created, you must ask users to activate the binding of their accounts with the external application. In order to do that, they must log-in to ECM, go to their profile and follow these steps:
* Click on *Bind*
!bindingnone.jpg!
* Enter their username and password of the external application (forum) and
!bindingnew.jpg!
* Hit Bind again :) If they provided valid information, and that the script we talked about earlier is working, they should see this
!bindingok.jpg!
MORE TO COME... :)
h1. Synchronization of External Applications with ECM
{{toc}}
</span>
ECM has a binding system that allows external applications (such as forums, wikis, killboards, etc.) to fetch their security access configuration (basically which users are in which groups) from ECM.
h2. How does it work?
First, you must note that ECM has its own user database with their passwords. The users are automatically assigned to groups by the scheduler so that group assignations match the In-Game titles of the characters owned by each user.
To make it simple: *One In-Game title <
h1.
> One ECM group*. Users have *all groups that match the titles of the characters* they own.
ECM database also contains a table where you can add external applications (_common_externalapplication_). With this table, two other tables __== common_groupbinding ==__, `common_userbinding` allow the association of one ECM internal user or group with an external id.
With this information, ECM can easily provide a *translation* of its internal security access configuration (which users are in which groups) for any external application *that has group & user bindings*.
As a schema is often better than an explanation:
!external_app_sync.png!
(1) You must provide a HTTP front-end (php, python, perl script) which will return a user_id of the external application when requested with a username and password. You will find more information about this [ExternalAppsSync#Prepare_and_install_a_script_attached_to_your_external_applicati here].
(2) You must provide a script that will fetch JSON data from ECM and update the external application _user_groups_ table from this data. There is an "example script for PHPBB3":http://code.google.com/p/eve-corp-management/source/browse/src/scripts/phpbb3_sync.php in ECM package.
h2. Kewl, how do I use this? (Example)
Here is a detailed example on how to setup sync between ECM and a "PHPBB":http://www.phpbb.com forum. Let's say we want five PHPBB groups to be synchronized with In-Game titles.
|| *PHPBB group* ||
|| Corp Members ||
|| Directors ||
|| Cap Pilots ||
|| Production Manager ||
|| HR Team ||
h3. Create an External Application
Let's login to the administration panel in ECM via [http://ecm.myserver.com/admin/]. Here, you can manage most of the objects stored in ECM database. We will focus on the **Common** frame for this tutorial.
!app.jpg!
First thing we want to do is create an external application, click on the corresponding *Add* button, and fill the fields.
!add.jpg!
* *name*: An internal name for your application in ECM. This name will be displayed when members activate the binding of their account.
* *url*: An URL accessible from ECM server. This URL should return a _user_id_ when challenged with a username and password. More information on this in the next section.
When you are done, click *Save*.
h2. = Prepare and install a script attached to your external application
The URL you gave in the previous step points to a php script. This script should accept POST requests with 2 parameters: *username* and *password*. If the *username* is present in the forum's database and matches with the *password*, the script should return a simple response with the *user_id* corresponding to the *username*.
You will find an "example script for PHPBB3":http://code.google.com/p/eve-corp-management/source/browse/src/scripts/phpbb3_simple_auth.php embedded in ECM installation. Depending on the version of PHPBB you use (or if you don't use PHPBB), the script may vary (could be a perl script, CGI, python, whatever...). *It just needs to be accessible through an HTTP POST request and comply to the spec above*.
Look at [ExternalAppsSync#How_does_it_work? the schema at the beginning] around the yellow (1) mark for an illustration.
h3. Create group bindings
Next step is to create group bindings. We want some PHPBB groups to be associated with multiple In-Game titles. This way, if a player owns a character that has at least one of these titles, she/he will be put in the associated PHPBB group.
Here are the associations we want to have:
|| *ECM group (In-Game title)* || *PHPBB group* || *PHPBB group_id* ||
|| Junior Member || Corp Members || 5 ||
|| Member || Corp Members || 5 ||
|| Senior Member || Corp Members || 5 ||
|| Directors || Directors || 1547 ||
|| Cap Pilot || Cap Pilots || 45 ||
|| Production Officer || Production Manager || 167 ||
|| Production Director || Production Manager || 167 ||
|| HR Officer || HR Team || 457 ||
In ECM administration panel, you can create *Group bindings* to reflect the table above.
!groupbinding.jpg!
h3. Ask users to activate the binding of their accounts
Once the group bindings are created, you must ask users to activate the binding of their accounts with the external application. In order to do that, they must log-in to ECM, go to their profile and follow these steps:
* Click on *Bind*
!bindingnone.jpg!
* Enter their username and password of the external application (forum) and
!bindingnew.jpg!
* Hit Bind again :) If they provided valid information, and that the script we talked about earlier is working, they should see this
!bindingok.jpg!
MORE TO COME... :)