Single Sign On (SSO)

Matthew Simons

What You'll Need

Client's email address or clientID
Your vendor password
Your vendor ID
MD5 Hash (created on-the-fly)

How it Works

To pass through authentication from your web service to ours, you will simply need to send a GET or POST request to the following URL:

http://client.virtualagentconnect.com/signin.php

You can load this URL in the current window or in a new window, tab, or frame (we discourage the use of i-frames due to complications with how browsers interpret document and window properties for content within i-frames). These are the parameters to send in your request:

'email' OR 'clientID' - The client's email address or clientID in the Virtual Agent system
'vendorid' - Your vendor ID
'timestamp' - the current UNIX timestamp created on-the-fly*
'token' - An MD5 hash of the above fields plus the vendor password

By using a token generated from your vendor password, you avoid needing to know the client's password within our system and you avoid directly passing through unencrypted passwords through an unsecured web server.

* Please note that the login will fail if the timestamp is 10+ hours old. Current time is calculated based on Central Standard Time.

Creating the MD5 Hash Token

To create the MD5 hash, concatenate the following fields together in this exact order with no extra characters before, after, or in between:

email + timestamp + vendor password

or if you are using the client ID instead:

clientID + timestamp + vendor password

Most web programming languages have a built-in md5 function. The following example shows how you would achieve this in php:

$timestamp = time(); $token = md5($email . $timestamp . $vendorpass);

Note: You will use this timestamp again in your GET or POST request

The GET Request

Now that you have all the required fields, all that is left to do is create your GET or POST request. You can add the fields to the query string for a GET request, like this:

http://client.virtualagentconnect.com/signin.php?email=<email>&vendorid=<vendorid>&timestamp=<timestamp>&token=<token>

If you are using the clientID instead, replace email=<email> with clientID=<clientID>

When Things Go Wrong

By default, if a sign-on request fails, the user is redirected to our standard login page. You can set up a custom URL to be redirected to. We can pass back a clientID or email address plus an error code in the query string (ex: http://www.example.com/fail.php?clientID=1234&errorID=2). Possible error codes include:

0: unauthorized - the token doesn't match what our system is expecting
1: missing parameters - a required parameter wasn't passed in
2: no match - the client ID or email address doesn't exist in our system
3: expired - the timestamp given is invalid or more than 10 hours in the past
4: duplicate - the same email/password combination exists multiple times in our system

Please email us to get your redirect URL registered with our system.

Logging Out / Expired Sessions

We also support the ability to redirect to a custom URL when the session dies or the user logs out. If you need to log a user out from a link on your end, you may link to http://client.virtualagentconnect.com/logout.php

Please email us to get your redirect URL registered with our system.

Questions

If you have any questions or are missing any of the required information, please contact us at support@virtualagentconnect.com