Pearson
Always Learning

Authentication is required so that LearningStudio and MyLabs Plus client institutions only access the information that they are authorized to access. All SIS APIs require a username and password, provided by your Strategic Customer Operations (SCO) team during the initial API set-up.

SOAP Standards to Use

WS-Security

All SIS APIs require the use of the WS-Security standard (i.e., the OASIS Web Services Security Username Token Profile 1.0 framework). For Terms and Courses, you send the username and password as plain text values (over SSL), but for Users and Enrollments you will send the password as a password digest.

Implementing WS-Security can be tricky and time consuming, so we strongly recommend that you utilize a library available for your programming language. This library may be built into your SOAP toolkit by default. We include more detailed information on the requirements for each set of services below, but most of the time, the library you use will handle these details by default. We have additional information and links to possible libraries available on the Implementation Resources page.

Note that these services always require sending a nonce and created element with the request, even if it’s not strictly required by the standard. You will need to ensure your code library always sends these values, even for plain text passwords. Some libraries may need to be modified; we’ve primarily seen this with Java libraries.

WS-Addressing

You will use SSL to securely communicate with all SIS APIs. The Terms and Courses services, however, utilize SSL offloading once the transaction reaches our network; this means the request is forwarded to the correct application to handle the request. In order to forward the message correctly, you will use WS-Addressing for Terms and Courses services. Details are below. Users and Enrollments services do not use WS-Addressing.

Terms and Courses

Authentication for Terms and Courses services require WS-Security using a plain text password. The WS-Security library or toolkit you use will include a element with the following child elements. You will need to provide your library/toolkit the username and password, and set it to use plain text passwords.

Element Description
wsse:Username Username that is provided by SCO.
wsse:Password Password that is provided by SCO. Set your library/toolkit to use plain text passwords.
wsse:Nonce A random value that is used by the framework to ensure against replay attacks. This value should be automatically supplied by the WS-Security module of the SOAP toolkit you use.
wsu:Created The date and time that a particular request was generated. This value should be automatically inserted by the WS-Security module of the SOAP toolkit in a predefined UTC format.

Important: By default, some third-party implementations do not include the Nonce and Created elements when plain text passwords are used (we’ve mainly seen this in some Java implementations). You will need to modify or otherwise enforce the use of Nonce and Created child elements in the <usernametoken></usernametoken> .

Tip: If you are programming in .NET, use WCF 4.0 for communicating with Terms & Courses services.

WS-Addressing for Terms and Courses Services

You will communicate with these services using SSL for encrypted traffic; however once the request reaches our system, the Terms and Courses services forward the request to the appropriate subsystem. In order to route your request correct, use the WS-Addressing component of your SOAP library or toolkit. Your library should include a element containing the address you specify.

For any Course-related requests, including Create Empty Course, Copy Course Section with Content, Copy Course without Content, Copy Content, and Update Course, use this WS-Address:

  • http://ccws-services.ecollege.com/EnterpriseServices/v2.2/EnterpriseCourse.svc

For the request to Create a Term, use this WS-Address:

  • http://ccws-services.ecollege.com/EnterpriseServices/v2.2/EnterpriseTerm.svc

Example Request Header

<header xmlns:wsa="http://www.w3.org/2005/08/addressing"><security soap:mustunderstand="true" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"><usernametoken wsu:id="UsernameToken-1" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><username>{USERNAME}</username><password type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-usernametoken-profile-1.0#PasswordText">{PLAINTEXT_PASSWORD}</password><nonce encodingtype="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soapmessage-security-1.0#Base64Binary">{RANDOM_VALUE}</nonce><created>{UTC_TIMESTAMPE}</created></usernametoken></security><action>{ACTION_DEFINED_BY_WSDL}</action><to>{ADDRESSING_URL}</to></header>

Users and Enrollments

Authentication for Users and Enrollments services require WS-Security, using a password digest. The WS-Security library or toolkit you use will include a element with the following child elements. You will need to provide your library/toolkit the username and password, and set it to use password digest.

Element Description
wsse:Username Username that is provided by SCO.
wsse:Password A hashed digest of the password provided by SCO.
wsse:Nonce A random value that is used by the framework to ensure against replay attacks. This value should be automatically supplied by the WS-Security module of the SOAP toolkit you use.
wsu:Created When the message was created. This value should be automatically supplied by the WS-Security module of the SOAP toolkit you use.

Tip: If you are programming in .NET, use WSE 3.0 for communicating with Users & Enrollments services.

Example Request Header

Using the above WS-Security guidelines, the SOAP request header you create should look something like this:

<header><security soap:mustunderstand="1"><timestamp wsu:id="..."><created>{UTC_TIMESTAMP}</created><expires>{UTC_TIMESTAMP}</expires></timestamp><usernametoken wsu:id="..."><username>{USERNAME}</username><password type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">{PASSWORD_DIGEST}</password><nonce>{RANDOM_VALUE}</nonce><created>{UTC_TIMESTAMP}</created></usernametoken></security></header>

Technical Details for WS-Security

The SOAP toolkit or WS-Security library you use should handle creating these elements according to the standard, however if you need to modify them or implement custom functionality, here are additional guidelines for timestamps and the password digest.

Created and Expired Timestamps

The Created and Expired elements specify the date range for which the security element is still valid.

  • The date/time value complies with the ISO 8601 standard.
  • The combined date and time typically look like this: 2007-05-01T21:05:01Z
  • Note that the combined date and time designates the Time portion by inserting the "T" between the date and time.
  • Because the SIS and LearningStudio are likely to be in different local time zones, we recommend setting your timestamps to GMT/UTC, as designated by a "Z" at the end of the string.
  • ISO 8601 provides more information on the standard.

Password Digest (Users & Enrollments Services)

The basic formula for the password digest element is: Password Value = Base 64(SHA-1(Nonce + Created + Password))

  • The element must indicate the password type of #PasswordDigest.
  • WS-Security specifies that the hash is the Base 64 representation of a SHA-1 hash of the password, as well as the Nonce and Created values if those are being used.
  • The Nonce value must base64 encoded and 16 bytes in length. When generating the password value, ensure the nonce used is the raw bytes and not the base64 encoded bytes. See the OASIS group website for more details.
2840 reads
Always Learning
Pearson