Token Exchange Single Sign-On

Overview

Token Exchange is a custom Single Sign-On method. University systems send GradesFirst a security token and user id. GradesFirst responds with an authentication token which can be used to authenticate a user to the system.

Authentication Process

1. A user logs into a university system, such as a web portal which displays a dashboard of online services including email, course information, and a link to GradesFirst.
2. The user clicks the link to access GradesFirst. This references a script on the university server that has access to the user's authentication information, namely their user id.
3. The university server sends the user id along with a security token to GradesFirst.
   1. Template Request
      https://<School Sub-domain>.gradesfirst.com/cas/schools/<School ID>/reverse_session/new?<Security Token Parameter Name>=<Security Token>&<User ID Parameter Name>=<User ID>
   2. Example Request
      https://myschool.gradesfirst.com/cas/schools/1234-my_school/reverse_session/new?security_token=qwepor3940adsfkla6723jdflk24&user_id=my-username
4. If the security token is verified and the specified user id is found, GradesFirst returns a HTTP 200 response with one of two values: the authentication token or the full return URL including the token as a parameter. This setting can be configured by GradesFirst Support.
   Examples:
   
   • Authentication Token: df8fdbd5900d3fca7c5c76a1fcb881d5
     
   • Full Return URL: https://myschool.gradesfirst.com/cas/schools/1234-my_school/reverse_session?token=df8fdbd5900d3fca7c5c76a1fcb881d5
   Notes on Error Handling
   
   1. If the security token is not verified or the specified user id is not found, GradesFirst returns a HTTP 404 (not found) response.
   2. If a parameter is missing, GradesFirst returns a HTTP 500 response.
5. The university server receives the authentication token.
6. The university server redirects the user's browser back to GradesFirst, including the authentication token in the URL.
   1. Template Request
      https://<School Sub-domain>.gradesfirst.com/cas/schools/<School ID>/reverse_session?<Token Parameter Name>=<Auth Token>
   2. Example Request
      https://myschool.gradesfirst.com/cas/schools/1234-my_school/reverse_session?token=df8fdbd5900d3fca7c5c76a1fcb881d5
7. GradesFirst validates the authentication token, logs the user into the appropriate user account, and displays their GradesFirst home page.

Options

Parameter Names

The following parameter names can be configured by GradesFirst support to assist you in your implementation of Token Exchange authentication. We recommend that you use the default values if possible.

Authentication Response

When a user is authenticated, GradesFirst returns a response in one of two formats. GradesFirst support can configure this setting for you based on your needs.

1. Authentication Token
   Example: df8fdbd5900d3fca7c5c76a1fcb881d5
   
   
2. Full Return URL: 
   Example: https://myschool.gradesfirst.com/cas/schools/1234-my_school/reverse_session?token=df8fdbd5900d3fca7c5c76a1fcb881d5