Pearson
Always Learning

Overview

OAuth 1.0a protocols require you to create a unique signature (i.e., a hash) for every API request. The signature takes all the components of the request (URI, body, query string, etc) and some OAuth values, and using the Shared Secret, generates a hash. This is then included in the API request.

To generate the signature, you first create a base string with the appropriate parameters in the appropriate order, and then create the signature. You also must include the the values from the signature base string in the X-Authorization request header as part of the API request signature information. LearningStudio takes the components of the request and using the same Shared Secret, creates it's own signature. If the signatures match, the request is processed.

Important: In the X-Authorization request header, you must include the signature hash and the values you used for the signature base string. You must ensure that these values exactly match the values that you used to generate the signature. Failure to do so is one of the most common reasons why OAuth 1.0a requests are denied.

Important: LearningStudio uses the AES-CMAC algorithm for generating hashes. This is a somewhat unusual choice, but will not be changed and no alternative will be available. The libraries and sample code leverage third party libraries to generate this hash, you're encouraged to use these to get started faster.


Libraries & Sample Code

Reading the documentation is wise to better understand how to create a signature and use it in a request. To make implementation easier, we have the LearningStudio Libraries that can generate a signature for a request, and even fire the request handling authentication behind the scenes. If you want to roll your own code, check out the OAuth 1 sample code for working examples.


URL Components

You will be manipulating separate parts of your complete API request to create the signature base string and X-Authorization header used during OAuth 1.0a authentication. Here are the definitions we will use to identify these components in the documentation below.

Structure of a typical API request:

verb https://domain/route?queryStringParameter requestHeader { requestBody }

Sample URL request used in the Example column:

GET https://api.learningstudio.com/users/123456/courses/upcomingevents?since=03/01/2013&until=12/31/2013

Term Definition Example
verb One of the RESTful verbs: GET, POST, PUT, or DELETE. GET
domain API hostname. api.learningstudio.com
route The relative URI with route parameters. Does not include the verb, domain, or any query strings. /users/123456/upcomingevents
queryString One or more query strings used to modify the request. See Query Strings for more information. ?since=03/01/2013&until=12/31/2013
requestHeader Header information for the API request. It must contain the X-Authorization request header with the signature authorization information for the request. See X-Authorization Syntax below.
requestBody Request body or "data payload" of the URL request. { "readstatus":{ "markedAsRead": {markedAsReadFlag} } }
url Full URL for the API request, including verb, domain, route, and query strings. Do not include the request header or the request body. GET https://api.learningstudio.com/users/123456/upcomingevents?since=03/01/2013&until=12/31/2013
domainRoute Domain and route for the API request, but without the verb or any query strings. https://api.learningstudio.com/users/123456/upcomingevents

Encoding

As part of building the signature base string and signature hash, you must repeatedly encode specific values using either URL-encoding or Base64-encoding to support the security requirements of sending data across the internet. See the step-by-step how to guide for the detailed process to create and encode the parameters you must include in the signature base string and that you will use to create the signature hash.

URL Encoding

Internet communication uses special characters to control processing. For example, a forward slash ("/") is used to separate different parts of a URL request. If you want to include the forward slash as a literal character in a string, you must replace the forward slash with its URL-encoded equivalent.

For example, you URL-encode a forward slash ("/") as "%2F." Thus, you encode the following:

/user/123456/courses

as

%2Fuser%2F123456%2Fcourses

The following discussions show the URL-encoded format that you would use for the signature base string; you must use the URL-encoded syntax to create the signature. If you do not, your API request will be denied because the signature was not created properly.

Signature Base String Syntax

After you have performed the required encoding of the parameter values, you will use them to build the signature base string. You then will use the resulting signature base string to create the signature hash (see the step-by-step how to guide).

Following is the syntax of the signature base string with the appropriate URL-encoded separators:

{verb}&{route}&application_Id%3D{applicationId}%26body%3D{requestBody}%26oauth_consumer_key%3D{consumerKey}%26oauth_nonce%3D{nonce}%3Doauth_signature_method%3D{hashMethod}%26oauth_timestamp%3D{timestamp}

Important: After the {route} value, you must list the signature base string parameters in alphabetic order by parameter name.

Note that the first two ampersands are not encoded.

Following is the non-encoded syntax to assist understanding:

{verb}&{route}&application_Id={applicationId}&body={requestBody}&oauth_consumer_key={consumerKey}&oauth_nonce={nonceValue}&oauth_signature_method={hashMethod}&oauth_timestamp={timestamp}

Query Strings

If your URL request includes query strings, you must include each one in the signature base string in the appropriate alphabetic order. Also, if the query string value includes non-alphanumeric characters, you must URL-encode the value.

For example, the API request:

GET /users/123456/upcomingevents?since=03/01/2013&until=05/31/2014&includeFutureTerms=true

would require the following signature base string syntax with the additional query string parameters:

{verb}&{route}&application_Id%3D{applicationId}%26includeFutureTerms%3Dtrue%26oauth_consumer_key%3D{consumerKey}%26oauth_nonce%3D{nonce}%3Doauth_signature_method%3D{hashMethod}%26oauth_timestamp%3D{timestamp}%26since%3D03%2F01%2F2013%26until%3D05%2F31%2F2014

Following is the non-encoded syntax to assist understanding:

{verb}&{route}&application_Id={applicationId}&body={requestBody}&includeFutureTerms=true&oauth_consumer_key={consumerKey}&oauth_nonce={nonceValue}&oauth_signature_method={hashMethod}&oauth_timestamp={timestamp}&since=03/01/2013&until=05/31/2014

Signature Base String Parameters

Note: The following descriptions assume you have performed the appropriate encoding on the values.

Name Description Valid Values
{verb} RESTful verb for the API request being made.
  • GET
  • POST
  • PUT
  • DELETE
{route}

The relative URI with route parameters. Does not include the verb, domain, or any query strings.

{applicationId} ID of the application making the authentication request.
{requestBody} Request body for the API request being made. Required if the request verb is PUT or POST. Remove entire parameter if the request verb is GET or DELETE.
{consumerKey} Educational Partner consumer key (also called "key moniker" or "public key").
{nonceValue} Random, alphanumeric value generated specifically for this request. Length must be between 1 and 32 characters. Alphanumeric values only - no special characters.
{hashMethod} Encryption method used to created the signature. CMAC-AES
{timestamp} Epoch time stamp of the request (the number of seconds elapsed since 1/1/1970 12:00 AM UTC until the API request is being signed).

X-Authorization Syntax

After you have used the signature base string to create the signature hash (see Submit API Request Using OAuth 1.0a for the step-by-step sequence), you must add the signature information to the X-Authorization request header in the API request before submitting it for processing.

Note: Do not encode the X-Authorization request header itself nor any of its values.

Following is the syntax:

X-Authorization: OAuth realm="{domainRoute}",application_id="{applicationId}",oauth_consumerkey="{consumerKey}",oauth_nonce="{nonceValue}",oauth_signature_method="{hashMethod}",oauth_timestamp="{timestamp}",oauth_signature="{signatureValue}"

Following are the rules for these values:

  • The entire header must be a single line with no line breaks or spaces between the parameters after the realm= parameter.
  • There is no required order for the parameters.
  • The values must exactly match the values used to create the signature base string that was used to generate the signature hash.
  • If the signature base string included query strings, do not include them in the header.

X-Authorization Parameters

Name Description Valid Values
{domainRoute} Domain and route for the API request.
{applicationId} ID of the application making the authentication request.
{consumerKey} Educational Partner consumer key (also called "key moniker" or "public key").
{nonceValue} Random, alphanumeric value generated specifically for this request. Length must be between 1 and 32 characters. Alphanumeric values only - no special characters.
{hashMethod} Encryption method used to created the signature. CMAC-AES
{timestamp} Epoch time stamp of the request (the number of seconds elapsed since 1/1/1970 12:00 AM UTC until the API request is being signed).
{signatureValue} Base64-encoded signature generated from the signature base string using the CMAC-AES process.

Example Signature Base Strings

Following are example signature base strings.

GET Courses Request

API request:

GET /courses/123456

Signature base string:

GET&%2Fcourses%2F123456&application_id%3D936DA01F-1234-4d9d-80C7-02AF85C8D2A8%26oauth_consumer_key%3D4101E3E3-4240-4C53-955F-A597A3F2C017%26oauth_nonce%3DAVQEVmrmSPJtf35L1CYSM20J04WRRZUE%26oauth_signature%3DQAzisyz5QaMDV3SRqIKmcA==%26oauth_signature_method%3DCMAC-AES%26oauth_timestamp%3D1314216476

PUT User Grades Request

API Request:

PUT /users/654321/courses/123456/gradebookItems/9a02aee9-7a10-1234-82c9-b7ca4a53928a/grade

Signature base string:

PUT&%2Fusers%2F654321%2Fcourses%2F123456%2FgradebookItems%2F9a02aee9-7a10-1234-82c9-b7ca4a53928a%2Fgrade&application_id%3D936DA01F-1234-4d9d-80C7-02AF85C8D2A8%26body%3DeyJncmFkZSI6eyJpZCI6NDkxMzc4OTgzLCJwb2ludHMiOjEwLjAwLCJsZXR0ZXJHcmFkZSI6IkEiLCJjb21tZW50cyI6Ik9BdXRoIDEuMCBQVVQgVGVzdCJ9fQ%25253D%25253D%26oauth_consumer_key%3D4101E3E3-4240-4C53-955F-A597A3F2C017%26oauth_nonce%3DAVQEVmrmSPJtf35L1CYSM20J04WRRZUE%26oauth_signature_method%3DCMAC-AES%26oauth_timestamp%3D1314216476

GET Upcoming Events

API Request:

GET /users/123456/upcomingevents?since=03/01/2013&until=05/31/2014&includeFutureTerms=true

Signature base string:

GET&%2Fusers%2F654321%2Fcourses%2F123456%2Fupcomingevents&application_id%3D936DA01F-1234-4d9d-80C7-02AF85C8D2A8%26includeFutureTerms%3Dtrue%26oauth_consumer_key%3D4101E3E3-4240-4C53-955F-A597A3F2C017%26oauth_nonce%3DAVQEVmrmSPJtf35L1CYSM20J04WRRZUE%26oauth_signature_method%3DCMAC-AES%26oauth_timestamp%3D1314216476%26since%3D03%2F01%2F2013%26until%3D05%2F31%2F2014

Example X-Authorization Headers

GET https://api.learningstudio.com/courses/123456/items/home HTTP/1.1 X-Authorization: OAuth realm="https://api.learningstudio.com/courses/123456/items/home",oauth_consumer_key="04b11650-1234-41d6-91a6-c19936aaf4e5",application_id="d23df54b-1234-4dbb-b394-cdb10d4a35cf",oauth_signature_method="CMAC-AES",oauth_timestamp="1363901402",oauth_nonce="3dqmx4whqjix25kd5fn2bceg24cr5qdr",oauth_signature="6cBLj3GGihdGaYLv2HrFQw%3D%3D"

GET https://api.learningstudio.com/users/123456/classmates&courseid=987654 HTTP/1.1 X-Authorization: OAuth realm="https://api.learningstudio.com/users/123456/classmates",oauth_consumer_key="04b11650-1234-41d6-91a6-c19936aaf4e5",application_id="d23df54b-1234-4dbb-b394-cdb10d4a35cf",oauth_signature_method="CMAC-AES",oauth_timestamp="1363902514",oauth_nonce="3dqasfdljix25kd5fn2bceg24cr5qdr",oauth_signature="5iABi46MihdGaYLv2HrFQw%3D%3D"

13416 reads
Always Learning
Pearson