Ijax Authentication

It is your responsibility to grant the proper level of access to Ijax market data to your users.

You might have a login process and session cookies and classes of users with different permissions levels, but it is outside the scope of Ijax.

In the server-side XML case, Ijax has no way of tracking the user so we rely on your requests coming from a trusted IP.

In the client-side Javascript case, the interaction is between the user's browser and the Ijax server directly without you as an intermediary and Ijax cannot know for sure what website originated the request. In this case you will need to obtain a token from the Ijax server that you then give to the user to use.

Tokens

A user is authenticated to us by a token that you obtain in a separate request.

It consists of 16 lowercase hexadecimals characters and it will time out after a certain period of inactivity or, optionally an absolute time limit.

You can also "unauthenticate" the token at any time, such as when the user signs out of your website.

User Identities

It is important to understand that Iguana does not need to know your clients' usernames, passwords, or email addresses or any other personal information.

For some requests, notably live data, we might need some kind of identifier that is unique per user. It could be their encrypted username or better still, a random number that you associate with the user.

We store this identifier in our logs for stock exchange requirements: we must be able to identify any user that we have provided live data to, if asked. So however you choose to identify your users to us, you must be able to translate that to a real user if required.

If we are managing royalty calculations on your behalf, then we need to be able to separate requests per user for proper accounting.

XML

Authentication of server side applications is done by IP address.

You need to tell Iguana in advance what IP address(es) will be accessing the service. There can be multiple addresses and blocks of addresses.

If you do not know the IP address of your server, make a request to the index page of the Ijax server you will be working with and it will tell you. e.g. http://ijax.iguana2.com will tell you the IP address that you appear to be coming from, according to the Ijax server.

You do not need to supply the auth parameter in any requests since you are authorized by IP, but you may still want to identify the user by supplying the user parameter.

You might want to do this if Iguana is managing your royalties or if guests should only get delayed data and you aren't controlling that some other way.

JSON

The intention with AJAX is that the user contacts the Ijax server directly, from any IP. We need some way of knowing that the user is a client of yours, but in general the Ijax server cannot know for sure what website the request is coming from.

For simple applications, such as Investor Relations pages, that only require delayed data for a very small number of stocks, Iguana may elect to drop proper authentication requirements but check the Referer or Origin HTTP header fields.

These may not always be provided, and if they aren't then the user will still be allowed. It is merely there to make sure that nobody can run a public website using the same service (since most users would provide the Referer and therefore be declined).

For all other cases, regardless of whether the user requires live or delayed data, you must obtain an authentication token for the user even if you have no way of identifying them.

To clarify: you may obtain a token for a user or a guest. Your configuration may have different permissions for guests and users so you should identify the user when appropriate. It is also imperative that you do so if we are managing royalty calculations for you so that user fees can be properly capped.

Authentication merely entails you obtaining a token on behalf of the user that allows the user to access the Ijax server. This request is made from your servers and would usually be an XML request. Your authentication request will be authenticated by your IP; see the discussion under XML above.

An example request and response for authenticating a guest user is:

Request: http://ijax.iguana2.com/auth?site=my_site

Response: <ijax_response><auth>abc123</auth></ijax_response>

Authenticating a logged in user is:

Request: http://ijax.iguana2.com/auth?site=my_site&user=USERID

Response: <ijax_response><auth>abc123</auth></ijax_response>

In each case above the authentication token is "abc123". You will then need to ensure that all of the user's requests to the Ijax server include "auth=abc123" as a parameter. If you use our Ijax library, this will be done automatically.

A reminder: if you ask for a token on behalf of a user, you should not identify them to us with any personal information such as their username on your site, or their email address. For example, you could encrypt the username or you could use a random id so long as it was unique. No personal information about the user should be sent.

You could obtain the token using an AJAX request to your server that causes an XML request to the Ijax server, or you could obtain it when the page is served to the user although you might need to note that you had authenticated them with us to avoid flooding our servers with authentication requests.

For example, if a guest user of yours who has no login to your site loads a page from your server that will make requests to an Ijax server for some free delayed data, then you could obtain a token by making an XML request from your server to the Ijax server when you are generating the page. If you are using our Ijax library described below, you would then need to dynamically write a javascript call in to the page for the user, such as: Ijax.authenticate("abc123").

If the token expires or is not given, then the next Ijax query will failed with ERR_AUTH_REQUIRED. If you are using our Javascript libarary then you can supply a function that will be called back when reauthentication is required.

Example Code

The following PHP code is a minimal example of how you might obtain an authentication token. It does no error checking or reauthentication.

<?
function ijax_authenticate()
{
  $site = 'my_site_code';
  $fh = fsockopen('ijax.iguana2.com', 80);
  fputs($fh, "GET /auth?site=$site&fmt=xml HTTP/1.0\r\n\r\n");
  while ($s = fgets($fh, 100)) {
    if (ereg('<auth>(.*)</auth>', $s, $m)) {
      $auth = $m[1];
    }
  }
  fclose($fh);
  return $auth;
}
?>

You could then initialize Ijax with the token as follows:

<?
<script>
Ijax.initialize({
   site: 'my_site_code',

   // call the php function "ijax_authenticate" and write the result as a javascript string
   auth: '<?= ijax_authenticate(); ?>', 

   // either perform an AJAX request to your own server to obtain a new token or just reload the page
   onAuthenticate = function() {      
     window.location.reload();
   }
});
</script>
?>