Pearson
Always Learning

Overview

OAuth 2.0 requests are used by applications to make authentication/authorization requests to a system (such as LearningStudio) on behalf of a specific user. Access is provided within the context of the provided user identification and is bounded by the rights and restrictions for that user. Thus, OAuth 2.0 provides authentication at the user level.

These requests also are called an "authorization grant." Depending on the authorization grant type being used (see Authorization Grant Types below), the application must know the user's username and either the user's password or the Educational Partner's system credentials. When using the OAuth 2.0 protocol, the application requests Access Tokens from LearningStudio using the user credentials, caches the tokens locally, and includes the appropriate token in each consecutive access attempt.

OAuth 2.0 Terminology

Following are some key terms used within these pages to describe the OAuth 2.0 protocols as implemented in the LearningStudio APIs:

  • Application - The application, process, or system that is making user-level authorization and processing requests to information and resources in LearningStudio. Also called "client application," but within these pages, the term "application" will be used to help prevent confusion with the Educational Partner.
  • User - The person on whose behalf the application is requesting access to his/her information and resources in LearningStudio. Also called "resource owner."
  • User Credentials - The method used to identify and authorize a user within an application - either the combination of a username and password or the combination of username and Educational Partner's system credentials.
  • Authorization grant - An authorization grant is the user's permission to access his/her information and resources in LearningStudio.
  • Authorization grant type - The specific method used to request access to a user's information and resources in LearningStudio. See Authorization Grant Types below for more information about the authorization grant types supported by the LearningStudio APIs.
  • Access Token - Access Tokens are credentials that an application uses to access protected resources, such as a user's information or resources in LearningStudio. An access token is a string representing an authorization issued to the application. Access tokens allow specific accesses, actions, and duration of access as enforced by LearningStudio.
  • Refresh Tokens - Refresh Tokens are credentials that an application uses to request a new set of access token and refresh token from LearningStudio when the current access token becomes invalid or expires. Only the Password Grant type allows refresh tokens (see Authorization Grant Types below).
  • Educational Partner - The system into which the application is requesting access to its information and resources in LearningStudio. Also called "client."
  • 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 within an Educational Partner 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.
  • Assertion - Pipe-delimited string of specified values used to create an assertion signature and to request an Access TOken.
  • Assertion signature - Value generated using the assertion and the CMAC algorithm that is used to sign a token request using the OAuth 2.0-Assertion protocol. Also called the "signature hash."

Authorization Grant Types

Although the OAuth 2.0 specification supports multiple authorization grant types, LearningStudio only supports the following two types:

  • Password Grant - The Password Grant type requires the user to provide a username and password to the application. The application uses the username/password to request an Access Token that allow access to the user's information and resources in LearningStudio. See Password Grant High-level Process Flows below for a description of the basic processes using this grant type. Some common use cases for this grant type are mobile applications that ask users to log in or a web application that requires user credentials.

    Caution: The application must not locally store, save, or cache the user credentials (username and password) because this action can cause a high security risk. Violating this policy can result in immediate termination of the application’s authorization to use LearningStudio APIs.

    You can store the username alone without violating this policy.

  • Assertion Grant - The Assertion Grant type allows the application to use only the username to request an Access Token to the user's information and resources. The application must also provide additional information that identifies it as a source that is trusted to make this type of authorization grant request. Some common use cases for this grant type are a web application being loaded inside of another application, a user widget in the Educational Partner's application, or a mobile application that is acting on behalf of a user, but that doesn't ask for the user credentials. See Assertion Grant High-level Process Flows below for a description of the basic processes using this grant type.

Note: Some LearningStudio clients manage their users' credentials outside of LearningStudio, using single sign-on to launch the user into a course. In these cases, you cannot use the Password grant type (because the user will not know their LearningStudio credentials. If you are building an application where the user should sign in with their password, you will need to work with these clients on an alternate authorization scheme.

Password Grant High-level Process Flows

Following are high-level process flows describing the Password Grant type as implemented in LearningStudio. See the Authentication How-To section for the detailed, step-by-step procedures to use this grant type.

Password Grant User Login Authentication

Here is a high-level process overview of the OAuth 2.0 authentication performed when a user logs into an application with their LearningStudio username and password.

Password Grant User Login Authentication

  1. The user logs into a course in the application with username and password.
  2. The application builds the token request and submits it to the LearningStudio Authentication API.
  3. The Authentication API verifies that the application is authorized to access LearningStudio and that the username/password is authorized to access the Educational Partner data.
    • If the application or username/password is not authorized (for example, the user is not enrolled in the course), the request is denied.
    • If the application and username/password are authorized, the API generates two tokens: the Access Token and the Refresh Token. These tokens are returned to the application. Included in the token data is the expires-in value, which indicates the number of seconds when the access token will expire (default is 60 minutes). The Refresh Token will roughly 10 minutes longer.
  4. The application stores these tokens in cache.

Password Grant Refresh Token Authentication

Because tokens expire after an hour, they must be regenerated if the user is still active in their session. Rather than sign the user out of your application and forcing them to re-authenticate, you can use the Password Refresh Token to generate a new Access Token.

The Refresh Token is provided at the same time as the Access Token, and should be stored in your application for this purpose. The refresh token will expire roughly 70 minutes after it's issued, so you should be quick about using it after the access token expires. Here is a high-level process flow of getting a fresh Access Token using a Refresh Token. "Overlapping" Access Token are allowed - new tokens can and should be requested while the cached tokens are still active.

Password Grant Refresh Token Authentication

  1. The application determines that the time defined in the expires-in value has almost passed.
  2. The application builds the Refresh Token request using the cached Refresh Token and submits it to the LearningStudio Authentication API. By using the Refresh Token process, the application does not force the user to re-provide username and password.
  3. The Authentication API verifies that the application is authorized to access LearningStudio and that the Refresh Token is valid.
    • If the application or the Refresh Token is not valid, the Refresh Token request is denied.
    • If the application and the Refresh Token are valid, the API generates two new tokens: the Access Token (X-Authorization token) and the Refresh Token, including the expiration values, and returns them to the application.
  4. The application stores these new tokens in cache and uses them for subsequent user actions.
  5. When the previous tokens expire, any further API actions submitted using them will be denied with a "401 - Unauthorized" response.
  6. Steps 1 through 5 can be repeated as many times as needed to support the user in the active application session.

Assertion Grant High-level Process Flows

When you don't have a reason to ask for the user's password (or they don't have a LearningStudio password, see above), you can use the Assertion Grant type. Here is the high-level overview describing how this works in LearningStudio. See the Authentication How-To for the detailed, step-by-step procedure to use this grant type.

Note the Assertion Grant type does not use Refresh Tokens. A new Access Token can be re-requested using the same process. "Overlapping" authorization tokens are allowed - new tokens can and should be requested while the cached tokens are still active.

Assertion User Authentication

  1. The application requests the Access Token by building the signed assertion using the known username, the proper API keys, and a generated signature. It then submits the signed assertion to the LearningStudio Authentication API.
  2. The Authentication API verifies that the signed assertion is valid for the application and that the username is authorized to access the requested data.
    • If the assertion string or the username is not authorized (for example, the user is not enrolled in the course), the request is denied.
    • If the assertion string and username are authorized, the API generates a single Access Token (X-Authorization token). The Access Token is returned to the application. Included in the token data is the expires-in value, which indicates the number of seconds when the token will expire (default is 60 minutes).
  3. The application stores the Access Token in cache.

Using the OAuth 2 Tokens

Once you have an Access Token, you'll include it with every subsequent API request in an X-Authorization HTTP header. The format of the header should be:

X-Authorization: Access_Token access_token={token}

(Replace {token} with the Access Token.)

4771 reads
Always Learning
Pearson