Pearson
Always Learning

Overview

The OAuth 1.0a protocol is used by applications to perform API requests to a system (such as LearningStudio) on behalf of another system (such as a LearningStudio client institution) - this is also known as "system-to-system requests." Each time the application makes a request to a LearningStudio API, it uses the required campus keys and details of the request to generate a unique signature. It then includes the system credentials and the signature in the request header before submitting the request. This process must be repeated for every request because the generated signature will differ each time. LearningStudio verifies that the system credentials and signature are valid before processing the request. See OAuth 1.0a High-level Process Flow below for a description of the process flow.

Because requests made using OAuth 1.0a are outside of the context of a "user," these kinds of requests are not bounded by typical user-level restrictions. For example, if a user had logged in using OAuth 2.0 (user-level authentication), the user cannot see or access data for a course in which the user is not enrolled. However, if an application makes a request using OAuth 1.0a, the application can access data and resources anywhere within the client's campus that are available to the supported LearningStudio APIs (see Supported LearningStudio APIs below for more information). Thus, OAuth 1.0a provides authentication at the system level within each Educational Partner's data and resources within LearningStudio.

Note: There are slight differences between the official OAuth 1.0a standard and the LearningStudio implementation. Please review this documentation carefully, or leverage one of our LearningStudio Libraries to make authentication much simpler.

OAuth 1.0a Terminology

Here are some of the key terms used within these pages to describe the OAuth 1.0a protocols as implemented in the LearningStudio APIs:

  • Application - The application, process, or system that is making system-level authorization and processing requests to information and resources in LearningStudio. Sometimes called "client application."
  • Educational Partner - The system on whose behalf the application is requesting access to its information and resources in LearningStudio. Also called "client" or "institution;" the OAuth 1.0a protocol calls this a "resource owner."
  • System Credentials - The method used to identify and authorize an Educational Partner within LearningStudio - typically, the combination of the consumer key, application ID, and consumer secret.
  • Consumer Key - Unique GUID assigned by Pearson to each Educational Partner. Also called "token key moniker" or "public key" (as defined within the IETF OAuth 1.0 Protocol).
  • Consumer Secret - Unique alphanumeric key assigned by Pearson to each Educational Partner that is known only to Pearson and the Educational Partner. Also called "shared secret" or "private key" (as defined within the IETF OAuth 1.0 Protocol).

    Important: The Consumer Secret must be kept secure and restricted. If your Consumer Secret ever becomes known outside of your authorized systems, your transactions with the LearningStudio API may be compromised.

  • Application ID - Unique GUID assigned by Pearson to each application or system that may use the LearningStudio APIs. Each Educational Partner may have multiple application IDs - for example, one application ID for a web-based classroom instruction application and another application ID for a mobile service. An application ID may be shared between multiple Educational Partners - for example, the Educational Partners all may use the same third-party application.
  • Signature - Generated value used to secure API requests using the OAuth 1.0a protocol. You create the signature using the CMAC-AES algorithm, the combination of the above and additional values, and the specific API request. Also called the "signature hash."

OAuth 1.0a High-level Process Flow

Following is the high-level process flow describing the OAuth 1.0a authentication protocol every time an API request is submitted, as implemented in LearningStudio. See the Create Request Using OAuth 1.0a use case for the detailed, step-by-step procedure to use this authentication protocol.

OAuth 1.0a Request Authentication

  1. The application builds the API request with the appropriate data in the request header.

    1. The application builds the signature base string using the system credentials for the Educational Partner and the additional required information (see OAuth 1.0a Signature Base String for more information).
    2. Using the request and the signature base string, the application generates the signature using the CMAC-AES algorithm and adds the signature and required signature base string values to the request header (see OAuth 1.0a Signature and X-Authorization for more information).
  2. The application sends the API request.
  3. LearningStudio verifies that the application is authorized to make the request and that the Educational Partner is authorized to access the requested data.
    1. LearningStudio generates a duplicate signature string using the submitted API request and the system credentials saved in LearningStudio for the Educational Partner.
    2. It compares the duplicate signature string to the signature string submitted in the request header.
    • If the two signature strings do not match, the request is denied.
    • If the two signature strings do match, the request is authorized and the API request is processed normally.

Supported LearningStudio APIs

The OAuth 1.0a authentication protocol is currently supported only in the following LearningStudio RESTful API resources:


OAuth 1.0a currently is not supported for Announcements, Doc Sharing, MS Office Docs, TempFiles, Text/Multimedia, Web Content Upload, and Webliography.

Supported User and Course Identification Methods

See User and Course Identification for more information about identifying users and courses in LearningStudio API requests. Below are the exceptions that the OAuth 1.0A protocol does not support.

Supported User Identification Methods

When using the OAuth 1.0a authentication protocol, you cannot use the /me shortcut in API calls. Therefore where with an OAuth 2 token you could call /me/courses, in OAuth 1 you must use /users/{userId}/courses.

Supported Course Identification Methods

During course identification, you must be aware of the following caveat if you use any request that uses the /courses/ccn={courseCallNumber} overload. Each Educational Partner defines its own course call numbers; therefore, it is possible that the same course call number may be used by multiple Educational Partners for different courses (course call numbers are not required to be unique across all Educational Partners in LearningStudio). LearningStudio determines the Educational Partner making any request by the context of the request in which the course call number is used. If LearningStudio cannot determine the Educational Partner for a request made using OAuth 1.0a, it denies the request. The recommended practice is to use /courses/{courseId} to specifically identify a course.

5017 reads
Always Learning
Pearson