Integration

One of the best parts of Ajax IM is that it can be integrated with your existing website's authentication.

Before you begin...

The gist of integration is that Ajax IM needs to talk to your existing website and authenticate against the user's existing session. Typically, it has been found that the best way to do this is by calling a URL on your website designed to return user information as a JSON object based on a session ID passed as a cookie or GET/POST parameter.

If this sounds complicated, don't worry. It isn't as bad as it sounds; just follow along below.

Authentication library

In Ajax IM, we need to create an authentication library. If you open the folder server/libs/authentication in your Ajax IM installation, you'll find a folder for the default library. We need to create our own.

1. Create a new folder in the authentication folder — let's call it yoursite. In that folder, we need to create a new file called index.js.

  cd server/libs/authentication
  mkdir yoursite
  touch index.js

2. index.js is the file Node.js will load to use your authentication library. In the file, there are three things that are required — one variable and two functions (see default/index.js for an example).

  var http = require('http');

  // The name of the cookie that contains your session ID. By default, PHP uses PHPSESSID.
   exports.cookie = 'PHPSESSID';

  // The function that will be called first, to authenticate the user based on their session ID.
  exports.authenticate = function(request, callback) {
  };

  // After authentication, this function is called to retrieve a list of friends.
  exports.friends = function(request, data, callback) {
  };

3. In exports.authenticate, we need to make a request to our existing application. We're going to assume our authentication script is located at http://yoursite.com/chat.php?action=auth.

  exports.authenticate = function(request, callback) {
      var host = 'yoursite.com',
           site = http.createClient(80, host),
           auth = site.request('GET', '/chat.php?action=auth',
                               {'host': host,
                                'cookie': exports.cookie + '=' + request.sessionID});
      auth.end();
      auth.on('response', function(response) {
          var data = '';
          response.setEncoding('utf8');
          response.on('data', function(chunk) {
              data += chunk;
          });
          response.on('end', function() {
              try {
                  var user = JSON.parse(data);
                  user.host = host;
                  callback(user);
              } catch(e) {
                  callback();
              }
          });
      });
  };

4. We need to do the same thing in exports.friends. We're going to assume our friends list script is located at http://yoursite.com/chat.php?action=friends.

  exports.friends = function(request, data, callback) {
      var host = data.host, // retrieve the hostname
           site = http.createClient(80, host),
           auth = site.request('GET', '/chat.php?action=friends',
                               {'host': host,
                                'cookie': exports.cookie + '=' + request.sessionID});
      auth.end();
      auth.on('response', function(response) {
          var data = '';
          response.setEncoding('utf8');
          response.on('data', function(chunk) {
              data += chunk;
          });
          response.on('end', function() {
              try {
                  callback(JSON.parse(data));
              } catch(e) {
                  callback();
              }
          });
      });
  };

5. Save and close index.js — that's all the work we'll need to do here.

Your website

On our website, we need to take the authentication data (the session ID) and return information about the user. This varies greatly from web app to web app, so the solution shown below is just a generic example.

Format of what we need to return:

• On a request to /chat.php?action=auth (called from exports.authentication): {"username":"johnsmith"}
• On a request to /chat.php?action=friends (called from exports.friends): ["username1","username2","username3"]

chat.php

<?php
  session_start();
  
  if($_GET['action'] == 'auth') {
      echo json_encode(array('username' => $_SESSION['username']));
  } else if($_GET['action'] == 'friends') {
      // we're going to assume $_SESSION['friends'] has a list of friends stored within.
      echo json_encode($_SESSION['friends']);
  }
?>

Server configuration

To fully integrate Ajax IM with your website, we'll need to proxy the Ajax IM server through your website. This works best with an asynchronous or evented server, such as nginx, lighttpd, or a load balancer.

Note: Apache is not recommended, as it is not evented, and will not handle Ajax IM well under load.

To configure nginx, you need to add a few directives to your nginx conf file to proxy a URL through to the IM server:

location /chat { 
   rewrite            /chat(/.+)$ $1 break; 
   proxy_pass         http://localhost:8000; 
   proxy_set_header   Host $host; 
   proxy_set_header   Cookie $http_cookie; 
   proxy_buffering    off; 
   proxy_send_timeout 310; 
}

Save your nginx configuration and reload the server.