Page Comparison

...

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 that will generate a temporarily authorized URL pointing to a pre-populated SSP Early Alert form. (URLs are artificially wrapped for readability)

...

...

:

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

...

1. .  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=a62e92eec800a52cf6d4c7a6288f4209e1325557c1d8f2c78acb21715acdb42e
 
# termCodeEnd supporteduser addedidentifier in 2.5.0
httpvia 'schoolId'
https://localhost:8080ssp.domain.edu/ssp-platform/sso?view=ea.new&username=foo&formattedCourse=ENC1101_1502
 &termCode=0455&studentSchoolId=00024328123&schoolId=00011145692&timeStamp=2013-08-26T16%3A44%3A03Z
 &token=a62e92eec800a52cf6d4c7a6288f4209
 
# sectionCode supported added in &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
httphttps://localhost:8080/ssp.domain.edu/ssp-platform/sso?view=ea.new&username=foo&sectionCodeformattedCourse=ENC1101_1502_0455
 &studentSchoolId=00024328123&timeStamp=2013-08-26T16%3A44%3A03Z&token=a62e92eec800a52cf6d4c7a6288f4209

...

 
# studentUserName supported added in 2.5.0

...

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 sections/rosters (which is no longer recommended).
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.
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).

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

...

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_roster.school_id
   studentUserName - Will be effectively resolved to a studentSchoolId using formatted_course and 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.

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

And here is breakdown of the 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.

...

1. _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/roster enrollment being targeted.If username is present, this field is

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 the a partial or complete identifier of a section for 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 section identifier 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.

...

This is the identifier of the academic term in which the targeted section is 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 an a wholly 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  

This field is usually only sent in combination with formattedCourse, in which case v_external_faculty_course and v 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 must uniquely identify rosters/sections using formatted_course and term_code pairs, which is still required even as of 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 legacy roster selection behavior in the Early Alert portlet 's native roster selection UI.)

...

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/roster. This value must match the school_id column in the v_external_faculty_course_roster view for the targeted roster/section/roster, 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.

...

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

...

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:

...

...

.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
       final MessageDigest md oIn.CharSet = MessageDigest.getInstance("MD5");"WIndows-1252"
        md.update(usernameOrSchoolId.getBytes());oIn.WriteText sIn
        if(timeStamp != null){oIn.Position = 0
        oIn.CharSet   	md.update(timestamp.getBytes(= "UTF-8"));
        ConvertFromUTF8 }= oIn.ReadText
        md.update(sharedSecret.getBytes());oIn.Close
     End Function

final byte[] hash = md.digest(); dim token
     token final String md5 = new String(Hex.encode(hash));= hex_md5(ConvertFromUTF8("foo") & ConvertFromUTF8("2013-08-26T16:44:03Z") & ConvertFromUTF8("monkey"))

     'if  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)
  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}
     Dim oIn: Set oIn = CreateObject("ADODB.Stream")
        oIn.Open org.jasig.portal.security.sso.mvc.SsoController.requireSecure was turned  on, but the request was HTTP.

    HTTP   oIn.CharSet = "WIndows-1252"
        oIn.WriteText sIn400 {"message":"One or more required inputs was not  specified","success":false}
       Missing oIninput(s).Position
= 
0    # New as of SSP oIn2.5.CharSet0
= "UTF-8"   HTTP 400 {"message":"Timestamp    ConvertFromUTF8 = oIn.ReadTextparse failure","success":false}
       Timestamp oIn.Closeparam not in correct format
 
End Function   # New as of dim tokenSSP 2.5.0
    HTTP 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%3DMTH101400 {"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":true}

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

false}
       Token was invalid.
 
    HTTP 403 {"message":"The SSO handshakekey requires a secure connection  (SSL)not configured","success":false}
       org.jasig.portal.security.sso.mvc.SsoController.requireSecure was turned  on, but the request was HTTP.
Feature is disabled
 
    HTTP 400403 {"message":"OneTimestamp orout more required inputs was not  specifiedof range","success":false}
       Timestamp param Missing input(s).was stale

    HTTP 403500 {"message":"NotAuthorization check authorizederror","success":false}
       TokenSystem-level wasfailure invalid.while  handling request, usually during  HTTP 403 {"message":"SSO key not configured","success":false}
token or timestamp validation.

 
    # New Featureas isof disabledSSP 2.5.0
    HTTP 500 {"message":"AuthorizationEnd user checklookup error","success":false}
       System-level failure trying whileto handlingresolve request,username usuallyor duringschoolId tokenparameter orto timestampa validation.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...

...