Detailed Authentication Handshake Process

Presently, only .NET and JavaScript client APIs are supported by GeoStream. For other client types (for example a PHP client) it will be necessary to perform the handshaking process directly with the server as outlined below.

For a client to successfully login to a GeoStream server, the client must retrieve from the server, the following two tokens:

• Login Token
• Authentication Token

The client initiates the handshaking process using the interface of the active server page auth.aspx. Two methods are exposed in this interface: GetLoginToken, and GetAuthToken, and are used in the following steps:

1. Client requests Login Token from GeoStream server (GetLoginToken)
2. GeoStream server sends Login Token to client
3. Client requests Authentication Token from GeoStream server (GetAuthToken)
4. GeoStream server sends Authentication Token to client

The handshaking process outlined above is described in more detail in the following sections below.

A client that wants to establish a connection with the GeoStream server makes a login request to the server's active server page, auth.aspx, with a login string, comprising:

• ?m=GetLoginToken
• &username=[client's user name]
• &mask=[IP address range bit mask]
• &expiry=[requested session expiry time]
• &ipAddress=[client's IP address]

The expiry time is given as an absolute time, measured in ticks since the epoch. The following PHP snippet can calculate an expiry time, relative to the current server time.

// Returns the number of ticks for the current epoch plus $durationInMinutes
// minutes. You can check the return value here: http://www.epochconverter.com/
// There are 10,000 ticks in each millisecond.
public function GetExpiryTimeForDuration($durationInMinutes) {
        $durationInSeconds = 60 * $durationInMinutes;
        $retval = time() + $durationInSeconds; // seconds since epoch + duration
        $retval .= "000"."0000"; // conversion: seconds -> milliseconds, milliseconds -> ticks
        return $retval;
}

Example Line breaks between arguments have been inserted for clarity.

http://server_address/geostream/auth.aspx?
  m=GetLoginToken
  &username=user_name
  &mask=32
  &expiry=633968640000000000
  &ipAddress=127.0.0.1

The GeoStream server will check that the username exists as a valid user, and will also check that the expiry time required by the client is not too long. If both arguments are valid, then the GeoStream server responds to the client with the Login Token string, which comprises:

• Login Token
• Login ID

The response from the server will appear similar to:

895e5210-9cb2-4461-8d7a-078aea7a97e6,67

Tip
If the username is not valid, a NoSuchUserException is generated and a 403 error is returned by the GeoStream server.

The Login Token is a GUID, of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. The Login ID is an integer value, appended to the Login Token, separated by a comma (in the above example the Login ID is 67). Both Login Token and Login ID are recorded by the server, ready for the next stage of the login handshake process.

If the expiry time request is too long, or too short (less than 1 minute), then the expiry time is reset to MaxSessionLength as defined in the web.config configuration file.

On receiving the Login Token, the client needs to retrieve the Authentication Token. To get this, the client creates Login Credentials based on:

• User name
• Password
• Login Token

The three elements listed above are encrypted using the MD5 cryptographic hash function.

Creating Login Credentials

// [username][password][Login Token, bytes as string]
$credentials = $username.$password;

// now append the string representation of the Login Token byte array
for ($i = 0; $i < count($byteArray); $i++) {
        $credentials .= chr(hexdec($byteArray[$i]]));
}

$hash = md5($credentials);
$hashByteArray = str_split($hash, 2); // this array has 16 elements

// next, rearrange the bytes and insert hyphens like so:
// [3][2][1][0]-[5][4]-[7][6]-[8][9]-[10][11][12][13][14][15]
// ...now we have all we need to create the Login Credentials.

When the login credentials have been created as a GUID string, the client requests the authentication token from the server with the following arguments:

• m=GetAuthToken
• &logintok=[Login Credentials – the login credentials created with the MD5 encryption of the user name, password and Login Token]
• &id=[Login ID – the same integer value that was received from the GeoStream server with the Login Token]

Example

http://server_address/geostream/auth.aspx?
  m=GetAuthToken
  &logintok=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  &id=1

The GeoStream server will check first, that the login has not already expired. If it has, a login exception is thrown "Login request expired". If the login has not expired, the authentication process continues with the server generating credentials based on what it learnt from the client in steps 1 & 2 above. If the server-generated credentials and the client-supplied credentials match, the server responds with the Authentication Token string, comprising:

• Authentication Token
• Expiry time
• IP address mask

The response from the server will appear similar to:

5390e277-46ef-6b62-259e-897eed04dca7,634214904952102000,32

When the client receives the token, it is saved to a cookie on the browser. When requesting tiles from the server, the client has the option to pass the Authentication Token with the query string (see GeoStream Tile Coordinates for more information on the structure of the query string). As an example:

http://serverURL/tile.aspx?t=0,0,300,4,1&a=5390e277-46ef-6b62-259e-897eed04dca7

Appending the Authentication Token to the query string as shown in the example above, gives a client the ability to request tiles from more than one server if separate authentication is required. If a token is attached to the query string, the server will use the given token. However, if no token is attached to the query string, then the server will look for the cookie instead.

Note
The server's token checking behavior, described above, is correct for GeoBase 3.5.1 onwards. With previous versions the server would look for the cookie first and if it found it, it would ignore the token passed with the query string.