User Authentication
User authentication refers to verifying a user’s identity--in this case, a user
seeking access to the WizIQ Virtual
Classroom API. This process ensures that only genuine requests reach the
API, protecting users from attempts to fake their identities.
Once you arrange for an API-enabled premium
plan, you’ll receive your Access Key and your Secret Key. These two keys
are used during the authentication process.
When you perform a request with WizIQ Virtual Classroom API, you assemble the request,
calculate the signature using your Secret Key, attach the signature to the request,
and send it to WizIQ Virtual Classroom API. WizIQ Virtual Classroom API verifies
the signature of the request and, if authenticated, processes the request.
The WizIQ Virtual Classroom API user authentication process
The WizIQ Virtual Classroom API user authentication process looks like this:
As you can see, your site:
- Prepares your method request.
- Calculates the HMAC authentication signature using your Access Key and your Secret
Key.
- Sends the request to the WizIQ servers.
When the WizIQ servers receive your request, they:
- Use the included Access Key to look up your Secret Key.
- Calculate the HMAC authentication signature using your Access Key and your Secret
Key.
- Respond to a correct signature by processing your request, or respond to an incorrect
signature by returning an error.
Now let’s look at each of these elements in more detail.
Note: You don’t need to write your own authentication code!
See the SDK download page for Java, .NET, PHP, and RubyOnRails libraries
that handle WizIQ Virtual Classroom authentication and more.
WizIQ Virtual Classroom API authentication building blocks
In order for the WizIQ Virtual Classroom API to authenticate a
method request from your site, three pieces of information must be included:
your access key, your security signature, and a timestamp stating when the request
was created. The SDK contains
libraries that handle this process for you, but we’ve included the details below
so you have a better understanding of what’s happening.
WizIQ Virtual Classroom API authentication: Access Key
Every WizIQ Virtual Classroom-enabled account has a
unique Access Key. This key looks similar to the following:
022QF06E7MXBSH9DHM02
Your Access Key must be included with every WizIQ Virtual Classroom API request.
WizIQ Virtual Classroom API authentication: Secret Key
Every WizIQ Virtual Classroom-enabled account has a
unique Secret Key. This key will look similar to the following:
kWcrlUX5JEDGM/LtmEENI/aVmYvHNif5zB+d9+ct
Never include the Secret Key, by itself, with a WizIQ Virtual Classroom API request.
If your Secret Key becomes compromised (publicly visible or copied for someone else’s
use), contact WizIQ support
immediately.
WizIQ Virtual Classroom API authentication: Timestamp
Each request through the WizIQ Virtual Classroom API must contain the date and time
it was created. Through the API, this value is represented in epoch time, calculated from
the time the message was created in
Coordinated Universal Time (UTC). Epoch time is the number of seconds between
midnight on January 1, 1970 in GMT/UTC and the time you’re referring to.
Note: For the purposes of the WizIQ Virtual Classroom API, UTC
and Greenwich Mean Time (GMT) are considered equivalent.
So for a request created at Mon, 20 Jun 2011 02:17:06 GMT/UTC, its epoch time would
be as follows:
1308536226
Note: If you’re not familiar with epoch time, the Epoch Converter is an excellent
resource, with interactive calculators and code examples for many different languages.
WizIQ Virtual Classroom API authentication: Signature
Calculating the WizIQ Virtual Classroom API authentication signature involves making
a HMAC-SHA1 hash of the API request parameters:
For the purpose of these calculations, if there are any URLs in the message, some
characters must be converted to their hex codes before hashing to prevent errors.
These two characters are the plus (+) and the forward slash (/). Instead of using
these literally in URLs, the SDK libraries replace all pluses in your URLs with
%2B, and all forward slashes with
%2F.
For example:
status_ping_URL="http://www.example.com/Linux+StudyGuide"
would need to be converted to the following before you calculate your hash:
status_ping_URL="http:%2F%2Fwww.example.com%2FLinux%2BStudyGuide"
Once you have the hash, create the Base64-encoded signature using the Secret Key.
Doing so gives you an ASCII string you can attach to your request. When WizIQ receives
the request, it will then decode the string to authenticate that the request came
from you.
See the complete list of API methods in WizIQ Virtual Classroom API documentation