help centre
For more info visit status.atmail.com

How can we help?


Search our knowledge base for answers to
common questions and latest updates.



My activities New request

Follow

CSRLogin Plugin

Stewart -

PROBLEM

I require single sign on for my users. My Admins require access to user account.

ENVIRONMENT

  • On-Premise Server + WebMail Installations: Version 6.0 > 7.3.2
  • Webmail Only Installations: Version 6.0 > 7.3.2

CAUSE

Allows login to Atmail using a time limited and encrypted authentication token. This can be used for SSO or for providing support technicians logins to user accounts without them knowing the password. Framework plugin provided, must be customized to your environment.

RESOLUTION

Applications

SSO

If your user is already logged into another system and you wish to provide a link to your Atmail WebMail system and have them auto logged in and taken directly to their inbox then the CSRLogin plugin can do this for you. You simply create a link to a special URL and pass an encrypted authentication token to it, the plugin will log the user into the system and send them to their inbox

Provide temporary access to user accounts for support staff

There may be cases where support staff need to access user accounts but you do not want to expose passwords for those accounts. The CSRLogin (Customer Support Representative Login) plugin can allow you to do this. The authentication token that CSRLogin plugin uses is encrypted and contains all information required to complete the login without the CSR having access to any passwords. All the CSR needs is a link with the auth token embedded in it. The token can also be given an expiry date so it cannot be used by the CSR to log into an account indefinitely.

Download

The CSRLogin Plugin can be downloaded via the following URL.

http://download.atmail.com/plugins/mail-plugins/CSRLogin.tgz

Installation

Upload

Upload via Atmail WebAdmin > Plugins > Add Plugin.

The Authentication Token

The authentication token is an encrypted JSON object that contains the following fields:

    1. account (user's account name)
    2. password
    3. mailserver (IMAP/POP3 server to auth against)
    4. expires (the expiry date/time in the form of a UNIX timestamp)

As the JSON object is encrypted the data contained within it is not easily exposed to misuse, for example the password cannot be seen in clear text by any third party.

Creating the Authentication Token

To create the authentication token we need 5 pieces of information:

1. secretKey - this is the password/passphrase used to encrypt (and later decrypt) the token
2. account - the Atmail user account that is to be logged into
3. password - the password for the account
4. mailserver - the hostname/IP for the IMAP server the user is to be authed against
5. expiry - a UNIX timestamp that represents the date and time that the token will expire

The following is a sample PHP function that can be used to create the authentication token, it requires the json and mcrypt extensions for PHP enabled:

<?php

function createCSRLoginAuthToken($secretKey, $account, $password, $mailserver, $expires=null)
{
    // If expires is not set then make it a year into the future
    if (is_null($expires)) {
        $expires = strtotime("+1 year");
    }
        
    $data = array('account' => $account, 'password' => $password, 'mailserver' => $mailserver, 'expires' => $expires);

    $json = json_encode($data);
                
    return trim(
        base64_encode(
        @mcrypt_encrypt(
            MCRYPT_RIJNDAEL_128,
            $secretKey,
            $json,
            MCRYPT_MODE_ECB,
                    @mcrypt_create_iv(@mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_ECB), MCRYPT_RAND)
            )
            )
    );
}

?>

Using the Authentication Token to Login

In order to make use of the authentication token and login a user with one click we simply need to create a link that the user can click on that uses a special URL with the token embdded in it which will activate the CSRLogin plugin and log the user into the system (providing the details are corrrect!)

The URL must take the following form:

http://$domain/$pathToAtmail/index.php/mail/auth/processlogin/authObj/$authToken

Where:

  • $domain = Your webmail domain
  • $pathToAtmail = Any additional path required to access Atmail webmail app
  • $authToken = The authentication token created for this user

Configuring the CSRLogin plugin

The only configuring the plugin requires is for you to specify the secret (password) used to encrypt the authentication token so that the plugin can successully decrypt it. To configure the plugin so it knows the secret the secret needs to be entered into the "settings" field in the "Plugins" table under the entry for the CSRLogin plugin. As the "settings" field is expected to contain a serialised array of name/value pairs we need to format it to suit. For example if my secret is "thisismysecret" we would enter a:1:{s:6:"secret";s:14:"thisismysecret";} into the database.

Some PHP code to easily create the serialized secret in the format required:

<?php
$secret = "thisismysecret"; // change to your real secret
echo serialize(array("secret" => $secret));
?>

Once you have the serialized version of your secret you can enter it into the DB as such:

mysql> update Plugins set settings = 'a:1:{s:6:"secret";s:14:"thisismysecret";}' where name = "CSRLogin";

Now your CSRPlugin can decrypt the authentication token sent to it (so long as you enter the correct secret!) and log in your users with one click!
 

 

Have more questions? Submit a request

Comments


Contact our support team


+61 (7) 5357 6605       support@atmail.com