Pearson
Always Learning

Overview

When you don't have a reason to know the user's password, or if the password is not managed by LearningStudio, you can generate a user token with the Assertion grant type.

The assertion is a concatenated string of values that identify you and the user for whom you want a token. Then you use that assertion to generate a signature, which is appended to the assertion and submitted to the Authentication API. This page will describe creating the assertion and signing it. You can also view the step by step how-to guide for assertions.

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.

Important: You must save the values you use in the assertion to create the assertion signature because you will include them in the POST /tokens request. LearningStudio uses these values to validate the assertion signature.

Important: You must ensure that the values you submit in the POST /tokens exactly match the values used to generate the assertion signature. Failure to do so is one of the most common reasons why requests are denied.


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 2 sample code for working examples.


Assertion Syntax

Here is the syntax of the assertion string you'll use to generate the signature:

{applicationName}|{consumerKey}|{applicationId}|{clientString}|{userName}|{timestamp}

Values are separated with pipe characters ( | ).

Important: The order of the values is important - always place these values in this order.

Assertion Parameters

Name Description Valid Values
{applicationName} Application name (used for description only - not validated against database). Must be alphanumeric value only with no spaces or special characters.
{consumerKey} Educational Partner consumer key (also called "key moniker" or "public key").
{applicationId} ID of the application making the authentication request.
{clientString} Educational Partner client string.
{userName} Use one of the following:
  • {username} - Educational Partner username.
  • {source}:{sourcedId}
    • {source} - Educational Partner source value.
    • {sourcedId} - Educational Partner user sourced ID.
{timestamp} Date and time when the token request was signed. Format is YYYY-MM-DDTHH:MM:SS.SSSZ. Time is in UTC (no timezone offset).

Signed Assertion

Create Assertion Signature

To create the assertion signature, you will do the following:

  1. After you have assembled the assertion, you use it to create the signature for the request using the CMAC-AES process. See Authentication Sample Code for code samples in several languages that automate this process. Or use the LearningStudio libraries to make development even simpler.
  2. You hex-encode the signature using the process appropriate to your language.
  3. You then append the signature to the assertion.

Signed Assertion Syntax

Here is the syntax of the signed assertion. It's the same as the base string version above, but with an additional pipe and the signature hash appended.

{applicationName}|{consumerKey}|{applicationId}|{clientString}|{userName}|{timestamp}|{hexEncodedSignature}

Use Signed Assertion

Once you have created the signed assertion, you can request the access token using POST /tokens request (see URI: Request OAuth 2.0 Tokens).

  1. You add the signature and appropriate values from the assertion to the grant_type parameter in the request body and submit the request.
  2. LearningStudio validates the signature information.
    1. LearningStudio uses the signed assertion and the stored consumer secret for that Educational Partner (also called "shared secret" or "private key") to generate a duplicate signature.
    2. If the duplicate signature does not match the assertion signature, LearningStudio denies the request.
    3. If the duplicate signature matches the assertion signature, LearningStudio creates an access token for the user and returns the access token to the application.
  3. You then use the access token to authorize subsequent API requests made on behalf of that user.

Example Signed Assertions

Following are example signed assertions. In these examples, the {clientString} is used as the {applicationName}.

Signed Assertion:

987654|4101E3E3-1234-4C53-955F-A597A3F2C017|3D936DA01F-1234-4d9d-80C7-02AF85C8D2A8|987654|jsmith456|2013-09-24T09:17:48.000Z|0664bacb65d33b693e859dd567fefd88

Signed Assertion:

987654|4101E3E3-1234-4C53-955F-A597A3F2C017|3D936DA01F-1234-4d9d-80C7-02AF85C8D2A8|987654|jsmith456|2013-09-24T09:42:42.000Z|e207ca5d571dd085cf851156850ce2e9

4086 reads
Always Learning
Pearson