-
Notifications
You must be signed in to change notification settings - Fork 157
API Login
Cypht ships with an "api login" module set to make it possible to integrate Cypht with other web applications to achieve "single sign on", or SSO. There are other ways to integrate Cypht into web applications using the site module set, but this method is more flexible since it's language agnostic, and can be used from different domains.
The API login procedure uses a 2 step process to facilitate SSO. The first step is to make an HTTP POST request to a specific endpoint in Cypht with the username and password to perform authentication. The second step is to do another HTTP POST request to Cypht when users wants to access webmail, that uses the results of the first request. Users can still login normally even with the API login module set activated.
Note that the idle_timer module set currently does not play nice with API logins, be sure to disable that module set in your hm3.ini!
The api login module needs to be enabled in the site hm3.ini file by uncommenting the following line:
modules[]=api_login
Also a shared key needs to be set to a random value. The shared key replaces the CSRF token usually required to perform a POST request in Cypht.
api_login_key='random value here'
Now rerun the scripts/config_gen.php script to enable the module
Here is an example of how to do the first step of SSO in PHP:
<?php
$user = 'username';
$pass = 'password';
$api_key ='api key value from your hm3.ini file';
$url = 'http://your-cypht-install/';
function format_post_data($data) {
$post = array();
foreach ($data as $name => $value) {
$post[] = urlencode($name).'='.urlencode($value);
}
return implode('&', $post);
}
function request_login($url, $user, $pass, $api_key) {
$post = format_post_data(array('username' => $user,
'password' => $pass, 'api_login_key' => $api_key));
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$res = curl_exec($ch);
// uncomment to troubleshoot problems
//print_r(curl_error($ch));
return json_decode($res);
}
print_r(request_login($url, $user, $pass, $api_key));
/**
* Result on success:
*
* {
* "hm_id":"3MN4DcfWBTstILGTizOoJjr3nJtB+k...",
* "hm_session":"eHUX6T66JlD30YLc54t97h..."
* }
*
* Result on failure:
*
* {
* "hm_id":"",
* "hm_session":""
* }
*
*/
If hm_id and hm_session keys are not empty, the user successfully authenticated to Cypht. Cypht supports a number of different authentication methods, and you can roll your own using the site module set. You will need to save the hm_id and hm_session values to be used when a user wants to access Cypht from your application.
Using the results from step 1, and the shared api key defined in your hm3.ini file, you can automatically log a user into Cypht from your application with the following form:
<html><body>
<form method="POST" action="http://localhost/?page=process_api_login">
<input type="text" name="hm_id" value="<hm_id from step 1>" />
<input type="text" name="hm_session" value="hm_session value from step 1" />
<input type="text" name="api_login_key" value="shared api key" />
<input type="submit" value="Webmail" />
</form>
</body></html>
If you want to integrate Cypht into an existing PHP application, and Cypht will be hosted on the same subdomain, you can use a functional interface to log a user into Cypht when they login to your application. To use this option, first set disable_fingerprint to true, and disable the idle_timeout module set, both in your hm3.ini file, and rerun your config_gen.php script. Then from your application code, perform a cypht login with the following code:
require '<your path to Cypht>/modules/api_login/api.php';
cypht_login($user, $pass, $url);
Where $user and $pass are the username and password of the user to login, and $url is the URL of your Cypht install. Logging a user out can be done with the cypht_logout() function:
require '<your path to Cypht>/modules/api_login/api.php';
cypht_logout();