Performing Axigen WebMail Single Sign-on

WebMail Integrations

Do you have a Customer Portal or Web application where your users usually sign in? 

Here's how you can perform single sign-on in the backend so that you also authenticate them in your Axigen WebMail.

This article assumes that your application can access your Axigen users' credentials and pass them further to the WebMail application.

This article involves performing HTTP calls for authentication. To ensure proper security, please make sure that the calls are triggered via SSL.


1. Account provisioning

Before implementing the single sign-on, you will need to manage the account provisioning. This is typically handled using Axigen's CLI API.

When provisioning the accounts in Axigen, please make sure that the accounts use the same login credentials used for the portal.  

2. Performing the single sign-on

For performing single sign-on, there are three main actors involved:

  • The client (user's Web browser)
  • Your Customer Portal
  • Your Axigen WebMail

Depending on your setup, we will further split the single sign-on part into two different scenarios:

2.1. The Customer Portal and the WebMail share the same domain

In this scenario, at least one of the two applications uses a subdomain, but they both have the same domain. Setups covered by this scenario:

  • The Portal uses the domain, the WebMail uses a subdomain
    • Portal URL: example.com
    • WebMail URL: webmail.example.com

  • The Portal and WebMail use their own dedicated subdomain
    • Portal URL: portal.example.com
    • WebMail URL: webmail.example.com

  • The Portal uses a subdomain, The WebMail uses the domain
    • Portal URL: portal.example.com
    • WebMail URL: example.com


2.1.1. Authenticate in the WebMail from your Portal 

When the portal authentication is performed, an Axigen WebMail authentication should be triggered in the back-end (using sockets).

An authentication request (to Axigen WebMail) should look like:

GET [wmUrl]/?action=login&username=<client's username>&password=<client's password>&custom=ajax HTTP/1.0

If the last parameter: custom=ajax is missed, then the login will be executed in the Standard WebMail Interface. 

2.1.2. Fetch and store the Axigen authentication keys 

If both Portal authentication and WebMail authentication succeed, the newly created Portal session should contain two properties, corresponding to the two authentication keys Axigen generated (these should be stored for later usage).

The result of a successful Axigen authentication request would look like:

HTTP/1.0 303 Moved Temporarily
Cache-Control: no-cache, no-store, must-revalidate, proxy-revalidate
Pragma: no-cache
Last-Modified: Thu, 5 Jun 2008 10:26:14 GMT
Expires: Thu, 29 May 2008 10:26:14 GMT
Server: Axigen-Webmail
Content-Type: text/html; charset=utf-8
Date: Thu, 5 Jun 2008 10:26:14 GMT
Set-Cookie: _hmail=485876d52164154bf7a98840940195cb;Path=/;Version=1;
Location: /?_h=242fa2fea1d86d902341edb8331df405
Cache: no-cache
Pragma: no-cache
Connection: Close
 
{ success: true, sessionKey: "f2531832aba5b28a947b35dfe3481b54" }

Observe the two keys, one is the cookie key, the other is the URL key. The cookie key should also be presented to the user by means of a Set-Cookie header in the current response.

The actual redirection of the user's browser from the Portal context to the WebMail context is performed by means of a link that should contain the URL key:

This link assumes the cookie key retrieved from the initial Axigen auth request has already been presented to the browser by means of a Set-Cookie key.

2.2. The Customer Portal and the WebMail use different domains

To simplify the implementation of the examples below, starting with Axigen 10.3.1.19, you will find the sso-init.hsp script and a sample PHP implementation in the sso folder of your webmail that comes with the Axigen distribution.  

In this scenario, each of the application uses its own different domain (or subdomain). Setups covered by this scenario:

  • The Portal uses its own domain, the WebMail uses its own domain:

    • Portal URL: portal.com

    • WebMail URL: webmail.com

  • The Portal uses its own domain, the WebMail uses a subdomain under a different domain:
    • Portal URL: portal.com
    • WebMail URL: webmail.example.com

  • The Portal uses a subdomain under its own domain, the WebMail its own domain:
    • Portal URL: portal.test.com
    • WebMail URL: webmail.com

  • The Portal uses a subdomain under its own domain, the WebMail uses a subdomain under a different domain:
    • Portal URL: portal.test.com
    • WebMail URL: webmail.example.com

2.2.1. Authenticate in the WebMail from your Portal 

When the portal authentication is performed, an Axigen WebMail authentication should be triggered in the back-end (using sockets).

An authentication request (to Axigen WebMail) should look like:

GET [wmUrl]/?action=login&username=<client's username>&password=<client's password>&custom=ajax HTTP/1.0

2.2.2. Fetch and store the Axigen authentication keys 

If both Portal authentication and WebMail authentication succeed, the newly created Portal session should contain two properties, corresponding to the two authentication keys Axigen generated (these should be stored for later usage).

The result of a successful Axigen authentication request would look like:

HTTP/1.0 303 Moved Temporarily
Cache-Control: no-cache, no-store, must-revalidate, proxy-revalidate
Pragma: no-cache
Last-Modified: Thu, 5 Jun 2008 10:26:14 GMT
Expires: Thu, 29 May 2008 10:26:14 GMT
Server: Axigen-Webmail
Content-Type: text/html; charset=utf-8
Date: Thu, 5 Jun 2008 10:26:14 GMT
Set-Cookie: _hmail=485876d52164154bf7a98840940195cb;Path=/;Version=1;
Location: /?_h=242fa2fea1d86d902341edb8331df405
Cache: no-cache
Pragma: no-cache
Connection: Close
 
{ success: true, sessionKey: "f2531832aba5b28a947b35dfe3481b54" }

Observe the two keys, one is the cookie key, the other is the URL key. 

2.2.3. Single sign-on using an Ajax call (recommended)

The actual redirection of the user's browser from the Portal context to the WebMail context is performed by means of a link that should contain the URL key:

2.2.3.2. Set the cookie via the WebMail using an AJAX call

Here's a snippet of how your AJAX call would look like:

GET [wmUrl]/sso-init.hsp?_hmail=<stored Axigen Cookie key> HTTP/1.1

And here's a sample response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate, proxy-revalidate
Pragma: no-cache
Last-Modified: Tue, 9 Jun 2020 14:20:35 GMT
Expires: Tue, 2 Jun 2020 14:20:35 GMT
Server: Axigen-Webmail
Content-Type: text/html; charset=utf-8
Date: Tue, 9 Jun 2020 14:20:35 GMT
Access-Control-Allow-Origin: https://portal.com
Access-Control-Allow-Credentials: true
Set-Cookie: _hmail=hRfgEqtHGsBtRdvpmAAmTkiIozsZ49lsRlmn4MprOw0_; SameSite=None; HttpOnly; domain=webmail.com
Content-Type: application/json
Content-Encoding: gzip
Connection: Keep-Alive
Content-Length: 39

The sso-init.hsp script will present the cookie key to the browser by means of a Set-Cookie key.

2.2.4. Single sign-on using a redirect

2.2.4.1. Redirect the Client to the WebMail and back to the Portal

This step is necessary as the cookie can only be set from the WebMail domain. 

The sso-init.hsp script will present the cookie key to the browser by means of a Set-Cookie key and then redirect back to the portal.


The Client follows the redirect and then gets redirected back to the portal:

The actual redirection of the user's browser from the Portal context to the WebMail context is performed by means of a link that should contain the URL key:

3. WebMail session keep-alive

The Axigen Sessions expire if they are not refreshed periodically. The portal must do that by calling, for each stored active session (see the Fetch and store the Axigen authentication keys section above), periodically:

GET [wmUrl]/images/dot.gif?_h=<stored Axigen URL key> HTTP/1.0
Cookie: _hmail=<stored Axigen Cookie key>

This request should be performed in the back-end (socket) and should be linked with every authenticated request for one of the Portal's pages.

4. Signing out

Should you want to also sign out from the WebMail when the user signs out from the Portal, this can be done though a request similar to the one below:

GET [wmUrl]/?_h=<stored Axigen URL key>&action=logout HTTP/1.0
Cookie: _hmail=<stored Axigen Cookie key>

5. Password synchronization (change / reset)

This SSO approach requires that, for an account, the portal password and Axigen password are in sync. To avoid desynchronization, a separate process must be implemented to handle the password change / reset process in a single place (i.e. your portal).

This means that:

  • users will change / reset their password in your portal, and with each such operation the portal will also propagate the new password into Axigen. 
  • you will need to disable the password change in Axigen.

You can hide the password change context in WebMail from the private/config_settings.hsp in your webmail folder: