Overview

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:

1. Prior to v2.2.0: At build time by setting corresponding values in your environment-specific filters file ({ssp-platform-src}/filters/*.properties).
2. 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.

[...]

## 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 - Identifying End User

The SSO-ing end user can be identified with either of two parameters sent on the server-to-server URL:

1. username - Identifies the end user by her "Net ID", i.e. the value she would normally key into a login form. Should correspond with person.username and v_external_person.username in the SSP database. This was the only end user identifier supported pre-2.5.0.  If present, schoolId is ignored.
2. schoolId - Identifies the end user by an immutable identifier, which may or may not be known to the end user. Should correspond with person.school_id and v_external_person.school_id in the SSP database. Support for this field was added in 2.5.0. Ignored if username is present.

For example:

# End user identifier via 'username'
https://ssp.domain.edu/ssp-platform/sso?username=foo&timeStamp=2013-08-26T16%3A44%3A03Z&token=e1325557c1d8f2c78acb21715acdb42e
 
# End user identifier via 'schoolId'
https://ssp.domain.edu/ssp-platform/sso?schoolId=00011145692&timeStamp=2013-08-26T16%3A44%3A03Z&token=e1325557c1d8f2c78acb21715acdb42e

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)

# formattedCourse only roster/section identifier supported pre-2.5.0
https://ssp.domain.edu/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
https://ssp.domain.edu/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
https://ssp.domain.edu/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
https://ssp.domain.edu/ssp-platform/sso?view=ea.new&username=foo&sectionCode=ENC1101_1502_0455
 &studentSchoolId=00024328123&timeStamp=2013-08-26T16%3A44%3A03Z&token=a62e92eec800a52cf6d4c7a6288f4209

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

1. formattedCourse - Will yield unpredictable results unless v_external_faculty_course.formatted_course and v_external_faculty_course_roster.formatted_course uniquely identify rosters/sections (which is no longer recommended). This is the only roster identifier supported pre-2.5.0.
2. 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. This combination not supported pre-2.5.0.
3. 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). Not supported pre-2.5.0.

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

1. studentSchoolId - Should map to v_external_faculty_course_roster.school_id. This is the only student identifier supported pre-2.5.0.
   
2. studentUserName - Will be effectively resolved to a studentSchoolId using v_external_person and person. Ignored if studentSchoolId is present. Not supported pre-2.5.0.

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 because the view parameter is not specified.

https://ssp.domain.edu/ssp-platform/sso?username=foo&timeStamp=2013-08-26T16%3A44%3A03Z&token=e1325557c1d8f2c78acb21715acdb42e

Invocation - URL 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.

Invocation - Parameter Definitions

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 v_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 v_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/enrollment being targeted.

If using this field, it must be possible to look up SSP-Platform users by their schoolId attribute using whatever directory services have been integrated.

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 a partial or complete identifier of a roster/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 roster/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 roster/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 a wholly ambiguous roster identifier and will be considered an error condition).

This field is usually only sent in combination with formattedCourse, in which case v_external_faculty_course and v_external_faculty_course_roster must 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 (even if section_code also uniquely identifies rosters/sections).

studentSchoolId

This is the identifier of a student who is enrolled in the targeted roster/section. This value must match the school_id column in the v_external_faculty_course_roster view for the targeted roster/section, and it must also be consistent with values in v_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 roster/section. Will be resolved to a school_id using v_external_person and person, 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.

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:

    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

     '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:

{"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}

Error responses will use HTTP-standard status codes and messages. Further details are rendered as JSON in the response body:

    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).
 
    # New as of SSP 2.5.0
    HTTP 400 {"message":"Timestamp parse failure","success":false}
       Timestamp param not in correct format
 
    # New as of SSP 2.5.0
    HTTP 400 {"message":"Missing or invalid end user identifier(s)","success":false}
       End user identifier/s not sent or did not resolve to a Platform account

    HTTP 403 {"message":"Not authorized","success":false}
       Token was invalid.
 
    HTTP 403 {"message":"SSO key not configured","success":false}
       Feature is disabled
 
    HTTP 403 {"message":"Timestamp out of range","success":false}
       Timestamp param was stale

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

 
    # New as of SSP 2.5.0
    HTTP 500 {"message":"End user lookup error","success":false}
       System-level failure trying to resolve username or schoolId parameter to a Platform account

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...