Beginning with SSP versions 2.0.0-b3 and 1.2.2, SSP supports a simple single-sign-on (SSO) protocol based on signed URLs. Historically it has been used primarily for "deep-linking" from a LMS to the SSP Early Alert creation form.

To use this feature, clients submit signed URLs via HTTP POST via back-channel requests (i.e. not via the end-user browser), to which SSP will respond with a JSON object containing a temporarily authorized URL to which to redirect the end-user's browser.

This document describes how to enable this feature in a SSP deployment and invoke it from an external system.

Deployment

Configuration

The following properties in {ssp-platform-src}/uportal-war/src/main/properties/portal.properties configure the SSO feature. Aside from forking and editing that file inline (a bad idea), properties set to ${environment.*} can be overridden in two different ways, depending on the version of SSP you're running:

Prior to v2.2.0: At build time by setting corresponding values in your environment-specific filters file ({ssp-platform-src}/filters/*.properties).
With v2.2.0+: At run time by setting corresponding values in ({SSP_CONFIGDIR}/ssp-platform-config.properties).

For v2.2.0+, check {ssp-platform-src}/uportal-war/src/main/resources/properties/ssp-platform-config.default.properties for defaults.

portal.properties

[...]

## SSO Properties
##
org.jasig.portal.security.sso.mvc.SsoController.requireSecure=${environment.build.sso.requireSecure}
org.jasig.portal.security.sso.mvc.SsoController.sharedSecret=${environment.build.sso.sharedSecret}
org.jasig.portal.security.sso.JpaSsoTicketDao.timeToLiveMinutes=${environment.build.sso.ticketTimeToLiveMinutes}
org.jasig.portal.security.sso.mvc.SsoController.checkTimeStampRange=${environment.build.sso.checkTimeStampRange}
org.jasig.portal.security.sso.mvc.SsoController.signedUrlToLiveMinutes=${environment.build.sso.signedUrlToLiveMinutes}

`requireSecure`

This setting should be set to true in production. It forces the SSO exchange to take place over SSL. Default is true.

`sharedSecret`

This value is used in the MD5 hashing process (see below). Choose something secure and reasonably long. This value will need to be shared with clients integrating via this SSO feature. If this left empty, the SSO feature will be effectively disabled. Default is empty (disabled).

`timeToLiveMinutes`

Sets the maximum amount of time in minutes for which a temporarily authorized redirect URL is valid. Default is 5.

`checkTimeStampRange`

Boolean. If true, signed backchannel request must include a timestamp to prevent replay attacks. If false, the timestamp can be included and, if present, will be included in the signature validation, but needn't pass a "freshness" check. Default is true.

`signedUrlToLiveMinutes`

If checkTimeStampRange is true, timestamps sent on signed backchannel requests must evaluate to a time within this number of minutes (plus or minus) of current server time. Default is 5.

Invocation

To use this feature, you must obtain a URL from the SSO service using a signed backchannel, i.e. server-to-server request. This request must be a HTTP POST. Two styles of URL are supported, one with query params appropriate for targeting the SSP Early Alert creation form, and one for targeting the user's default SSP Platform view. Security-related parameters are the same for both URL styles.

Invocation - Targeting Early Alert Portlet

Here are example server-to-server URL that will generate a temporarily authorized URL pointing to a pre-populated SSP Early Alert form. (URLs are artificially wrapped for readability)

Example SSO URL

# formattedCourse only roster/section identifier supported pre-2.5.0
http://localhost:8080/ssp-platform/sso?view=ea.new&username=foo&formattedCourse=ENC1101_1502_0455
 &studentSchoolId=00024328123&timeStamp=2013-08-26T16%3A44%3A03Z&token=a62e92eec800a52cf6d4c7a6288f4209
 
# studentUserName supported added in 2.5.0
http://localhost:8080/ssp-platform/sso?view=ea.new&username=foo&formattedCourse=ENC1101_1502_0455
 &studentUserName=s.tudent1&timeStamp=2013-08-26T16%3A44%3A03Z&token=a62e92eec800a52cf6d4c7a6288f4209
 
# termCode supported added in 2.5.0
http://localhost:8080/ssp-platform/sso?view=ea.new&username=foo&formattedCourse=ENC1101_1502
 &termCode=0455&studentSchoolId=00024328123&timeStamp=2013-08-26T16%3A44%3A03Z
 &token=a62e92eec800a52cf6d4c7a6288f4209
 
# sectionCode supported added in 2.5.0
http://localhost:8080/ssp-platform/sso?view=ea.new&username=foo&sectionCode=ENC1101_1502_0455
 &studentSchoolId=00024328123&timeStamp=2013-08-26T16%3A44%3A03Z&token=a62e92eec800a52cf6d4c7a6288f4209

The URL options shown above are comprehensive for SSP versions prior to 2.5.0. Starting with 2.5.0, a variety of parameters can be used to specify the target roster/section and enrollment when targeting the Early Alert form.

To target a roster/section, specify one of the following parameter combinations:

formattedCourse - Will yield unpredictable results unless v_external_faculty_course.formatted_course and v_external_faculty_course_roster.formatted_course uniquely identify sections/rosters (which is no longer recommended).
formattedCourse and termCode - Will yield unpredictable results unless v_external_faculty_course and v_external_faculty_course_roster uniquely identify rosters/sections using formatted_course and term_code pairs, which is still required even as of 2.5.0 in order to support legacy roster selection behavior in the Early Alert portlet UI.
sectionCode - The recommended approach for 2.5.0, assuming v_external_faculty_course and v_external_faculty_course_roster uniquely identify rosters/sections with section_code (which they should).

To target an enrollment within a roster/section, specify one of:

studentSchoolId - Should map to v_external_faculty_course_roster.school_id
studentUserName - Will be effectively resolved to a studentSchoolId using v_external_person and person. Ignored if studentSchoolId is present.

Invocation - Targeting Default Portlet

Here is an example server-to-server URL that will generate a temporarily authorized URL pointing to the user's default SSP Platform view.

Example SSO URL

http://localhost:8080/ssp-platform/sso?username=foo&timeStamp=2013-08-26T16%3A44%3A03Z&token=e1325557c1d8f2c78acb21715acdb42e

And here is breakdown of the syntax...

SSO URL Syntax

{protocol}://{hostname}/ssp-platform/sso?[view={viewId}&]username={username}&[formattedCourse={formattedCourse}&studentSchoolId={studentSchoolId}&][timeStamp={utcTimestamp}&]token={token}

`protocol`

Should be https for production, though you can use http (non-SSL) on a local environment for development. The SSO will reject http requests unless the org.jasig.portal.security.sso.SsoController.requireSecure is set tofalse.

`hostname`

The host – and port, if required – where SSP is installed.

`view`

Only currently supported value is ea.new, referring to the Early Alert creation form. If this query parameter is not specified or does not equal ea.new, the resulting temporarily authorized URL will send the user to her default SSP view.

`username`

This is the username of the end user to be logged in to SSP when redirected to the resulting temporarily authorized URL. Should correspond to to external_person.username and person.username in the SSP database. If targeting the Early Alert form, this value will be resolved to a Platform user account which must in some way (either via Platform directory attribute or SSP database content) be associated with a schoolId which matches v_external_faculty_course.faculty_school_id and v_external_faculty_course_roster.faculty_school_id for the roster/roster enrollment being targeted.

`schoolId`

New as of SSP 2.5.0.

This is the schoolId of the end user to be logged in to SSP. Should correspond to to external_person.school_id and person.school_id in the SSP database. If targeting the Early Alert form, this should also match v_external_faculty_course.faculty_school_id and v_external_faculty_course_roster.faculty_school_id for the roster/roster enrollment being targeted.

If username is present, this field is ignored.

If this field is present and not obscured by username, token will be validated against this field rather than username.

`formattedCourse`

This is the identifier of a section for which the authenticated user is a faculty member of record, and in which the targeted student (studentSchoolId or studentUserName) is enrolled. As such, this field is only relevant if view=ea.new, but in that case, if this field is sent, its value must match v_external_faculty_course.formatted_course and v_external_faculty_course_roster.formatted_course.

Will be 'and-ed' with termCode and sectionCode when looking up the targeted roster/roster enrollment if either or both of those fields are also present. When sent by itself (i.e. without sectionCode and/or termCode), formattedCourse is an ambiguous roster identifier unless SSP external data has been configured to treat this as a unique section identifier (as was traditionally done in very early 1.x deployments, but is no longer recommended). Otherwise sending this identifier by itself may result in unpredictable behavior.

`sectionCode`

New as of SSP 2.5.0.

This is the actual identifier for the roster being targeted for an Early Alert. As such, this field is only relevant if view=ea.new. If sent, this field's value must match v_external_faculty_course.section_code and v_external_faculty_course_roster.section_code.

Will be 'and-ed' with formattedCourse and termCode when looking up the targeted roster/roster enrollment if either or both of those fields are also present. But this field is sufficient to uniquely identify a roster when sent by itself. As such, as of 2.5.0, it is the preferred means for identifying the targeted roster via this protocol.

`termCode`

This is the identifier of the academic term in which the targeted section is offered. Should correspond to v_external_term.code, v_external_faculty_course.term_code, and v_external_faculty_course_roster.term_code.

When sent by itself (i.e. without formattedCourse and/or sectionCode, this identifier is an ambiguous roster identifier and will be considered an error condition). In pre-2.5.0 deployments prior to 2.5.0, it was often sufficient to send only formattedCourse, but this was dependent v_external_faculty_course and v_external_faculty_course_roster uniquely identifying a section using only that field, which is at odds with that field's usage elsewhere in external_* tables, and is not recommended when using this protocol in 2.5.0+. (It may still be necessary for formatted_course and term_code to uniquely identify a section in those tables, though, in order to support the Early Alert portlet's native roster selection UI.)

`studentSchoolId`

This is the identifier of a student who is enrolled in the targeted section/roster. This value must match the school_id column in the v_external_faculty_course_roster view for the targeted section/roster, and it must also be consistent with values in external_person.school_id and person.school_id representing this student in the SSP database.

Only relevant if view=ea.new. In that case, at least one of studentSchoolId and studentUserName is required as of 2.5.0. Prior to that, only studentSchoolId was required. If this field is present, studentUserName is ignored.

`studentUserName`

New as of SSP 2.5.0.

This is the identifier of a student who is enrolled in the specified section/roster. Will be resolved to a school_id, which will then effectively be treated the same way as studentSchoolId.

Only relevant if view=ea.new. In that case, at least one of studentSchoolId and studentUserName is required as of 2.5.0. Prior to that, only studentSchoolId was required. If studentSchoolId is present, this field is ignored.

`timeStamp`

This should be the requesting client's server timestamp in UTC time, formatted as yyyy-MM-dd'T'kk:mm:ss'Z' using Java SimpleDateFormat notation, e.g. 2013-08-26T16:44:03Z. Required if

org.jasig.portal.security.sso.mvc.SsoController.checkTimeStampRange=true in SSP Platform's portal.properties.

TBD: When was this added?

`token`

This parameter is the most complex. It must be equal to the result of hashing (using the MD5 algorithm) the URL-decoded value of the username or schoolId parameter, the URL-decoded value of the timeStamp parameter if present, and the sharedSecret (from portal.properties). The SSO Servlet performs this computation on its own, then compares it's result with the token parameter passed by the client. This is a security measure intended to verify that the client system is authorized to use this service: any client that knows the secret is deemed to be authorized. If the values match, the SSO will be allowed.

If username is present on the request, its value will be validated against token and schoolId will be ignored.

Here is the Java code in SSP that calculates this hash:

MD5 Hashing Java Code

    private boolean validateToken(final String usernameOrSchoolId, final String timestamp, final String token) throws UnsupportedEncodingException, NoSuchAlgorithmException {
        final MessageDigest md = MessageDigest.getInstance("MD5");
        md.update(usernameOrSchoolId.getBytes());
        if(timeStamp != null){
        	md.update(timestamp.getBytes("UTF-8"));
        }
        md.update(sharedSecret.getBytes());
        final byte[] hash = md.digest();
        final String md5 = new String(Hex.encode(hash));
        return md5.equals(token);
    }

    // if username="foo", timestamp="2013-08-26T16:44:03Z" and token="monkey", the md5 string will be a62e92eec800a52cf6d4c7a6288f4209

MD5 Hashing ASP Code

     'converts string to UTF8 to ensure there are no non-ascii characters
     Function ConvertFromUTF8(sIn)
        Dim oIn: Set oIn = CreateObject("ADODB.Stream")
        oIn.Open
        oIn.CharSet = "WIndows-1252"
        oIn.WriteText sIn
        oIn.Position = 0
        oIn.CharSet = "UTF-8"
        ConvertFromUTF8 = oIn.ReadText
        oIn.Close
     End Function

     dim token
     token = hex_md5(ConvertFromUTF8("foo") & ConvertFromUTF8("2013-08-26T16:44:03Z") & ConvertFromUTF8("monkey"))

     'if username="foo", timestamp="2013-08-26T16:44:03Z" and token="monkey", the md5 string will be a62e92eec800a52cf6d4c7a6288f4209

Response

On successful use of the SSO handshake component, the client system will receive a JSON response similar the following:

Successful SSO Response

{"URL":"http://localhost:8080/ssp-platform/Login?ticket=foo&refUrl=%2Fssp-platform%2Fp%2Fearly-alert%3FpP_action%3DenterAlert%26pP_schoolId%3Dstudent0%26pP_formattedCourse%3DMTH101","success":true}

TBD: Need to add new messages for 2.5.0 and note any others that were version specific. Esp timestamp-related errors.

Possible SSO Error Responses

    HTTP 403 {"message":"The SSO handshake requires a secure connection  (SSL)","success":false}
       org.jasig.portal.security.sso.mvc.SsoController.requireSecure was turned  on, but the request was HTTP.

    HTTP 400 {"message":"One or more required inputs was not  specified","success":false}
       Missing input(s).

    HTTP 403 {"message":"Not authorized","success":false}
       Token was invalid.
 
    HTTP 403 {"message":"SSO key not configured","success":false}
       Feature is disabled

    HTTP 500 {"message":"Authorization check error","success":false}
       System-level failure while handling request, usually during token or timestamp validation.

If, then, the client system redirects the user to the URL provided in this response, that user will be logged into SSP, taken to the Early Alert portlet, and arrive at a pre-populated submission screen like the following...

SSP Signed URL SSO

Deployment

Configuration

requireSecure

sharedSecret

timeToLiveMinutes

checkTimeStampRange

signedUrlToLiveMinutes

Invocation

Invocation - Targeting Early Alert Portlet

Invocation - Targeting Default Portlet

protocol

hostname

view

username

schoolId

formattedCourse

sectionCode

termCode

studentSchoolId

studentUserName

timeStamp

token

Response

`requireSecure`

`sharedSecret`

`timeToLiveMinutes`

`checkTimeStampRange`

`signedUrlToLiveMinutes`

`protocol`

`hostname`

`view`

`username`

`schoolId`

`formattedCourse`

`sectionCode`

`termCode`

`studentSchoolId`

`studentUserName`

`timeStamp`

`token`