Single Sign On Guide. Table of Contents

Transcription

1 Single Sign On Guide Table of Contents I. Overview II. Benefits III. How SSO Works IV. Set-up Requirements and Recommendations V. Set-up Instructions a. Required Parameters b. Optional Parameters c. Error Codes d. Integrating on Development e. Testing on Development f. Integrating on Production g. Testing on Production VI. Document Revision History

2 I. Single Sign On Overview The Single Sign On (SSO) service is an alternate login method offered by EverFi, allowing schools and organizations to provide a streamlined registration and login capability to their users accessing EverFi products. II. Single Sign On - Benefits Seamless Integration: From the student s point of view, they will simply log into their school or organization s portal and click a custom link to access their EverFi courses. Because the student is now authenticated through your portal, they will not need to remember separate access information to log into the EverFi platform. This eliminates the possibility of forgetting a username or password to access their EverFi account. Improved Accuracy: SSO eliminates the need for students to enter their name and other identifying information, depending on the parameters to be passed between EverFi and the alternative system. Because the student s information is passed through on the back- end, there is no chance the student could enter inaccurate personal information making it easier for the school or organization to keep track of their student s progress. This also eliminates the risk of a student creating multiple accounts by mistake. Ease of implementation: Our partners indicated this feature was easy to implement and did not require any advanced coding on their end. They were able to roll this service out quickly with little, if any, additional internal resources required. Increased visibility: By offering the EverFi digital curriculums via their own portal, partners reported increased awareness that EverFi had been selected as part of the school or organization s university s orientation package or learning experience. III. How SSO Works EverFi s SSO is simple and safe. The school or organization will place a link to an EverFi course in the appropriate location in the school or organization s portal or other protected web page. It s important that the link be located in a place where the student will have to log into your portal system first because your system will be passing student information to the EverFi system. After signing into the school or organization s system, the student will click on the link to the EverFi course. NOTE: The SSO request should be made at the time the student wants to access an EverFi course and not before. This prevents the unnecessary transmission of student data. This method should be used on demand - i.e. only once the student has decided to use the EverFi course. The action of clicking the link will notify the school or organization s system that the student wants to take the EverFi course. The school system will then POST the SSO request to EverFi with the correct parameters for your school or organization and the given student (described in diagram below). The information passed includes sensitive data and will be protected by SSL encryption (HTTPS). The EverFi system will validate the request and respond with either an error or a redirect URL with a user session token appended. The user session token is temporary and will expire so do not cache or store this URL as it may not work the next time the student attempts to cross over. 2

3 Diagram With the Sequence of Events in SSO with EverFi IV. Set- Up Requirements and Recommendations Information technology department: This add- on service will require a certain level of technical expertise. Introducing your information technology (IT) department to this effort early and inviting a representative to participate on your EverFi team will ensure a more successful implementation. Your web portal: Your school or organization must have a designated Web portal or authentication system live and in use. Additionally, students must know their access information (often: a username and password) to log into the portal prior to accessing their EverFi account. You must also be willing to keep the link up on the portal for the entire academic year, or designated period you are allowing access to our programs, so students can continue to access the course (please be sure to check with your IT department as space may be limited on the portal). Set- up: Once SSO has been enabled, your IT team can set up an authentication process or link to EverFi from your portal. This will be handled via a secure HTTPS POST call to the EverFi application (though testing can be done via an HTTP POST - i.e. without SSL encryption). You will be required 3

4 to pass the required parameters below. The ID will be used to identify that student within EverFi s system. Testing: Your IT department must be able to test the link against our test environment prior to advertising access to our programs. Our current partners utilizing this feature reported meeting regularly with their IT department to set up, test, and improve functionality of the SSO feature prior to and during their implementation. Help Desk: Please ensure your students have accessible information on how to contact their designated Help Desk. In addition, prepare your Help Desk by offering them a list of Frequently Asked Questions and by asking them to demo the login process. There may be rare instances in which a student has trouble with their link. We may hear from these students via our tech support line and will need to escalate these students to someone at your school or organization. Please establish a process for those students to receive support (i.e. perhaps they /contact your primary IT administrator or helpdesk for assistance). V. Single Sign On - Set- Up Instructions The EverFi platform provides a simple web interface for handing off authenticated student users to our system. All parameters should be sent as HTTP post fields with URL encoding. Upon the POST submission of the data, we will return a URI that you can redirect the student to. This URI will include a unique session ID that we will use to interact with the student. Be sure to add URL encoding if you plan to send parameters as a single concatenated post. NOTE: SSL (HTTPS) will be added in production. Testing can be done without SSL encryption. a. Required Parameters: Parameter Value Notes api_token student_id _address EverFi- provided unique authentication token granted to partner organizations. Unique ID for each student associated with the partner. Student s Address Can be up to 64 characters in length and any combination of numbers, letters, and these special characters: ( _, +, -, ~, : ). Please do not use spaces. This ID is not case- sensitive, so do not rely on case to make it unique. Should be on the school or organization s domain (example: student@school.edu) 4

5 school_id EverFi- provided unique School ID From Homeroom Admin Center curriculum_id 1 (Buttonwood) 2 (AtWork) 3 (Ignition) 4 (Vault) 5 (EverFi FinLit) 6 (AlcoholEdu for HS) 8 (Haven) 10 (AlcoholEdu for College) 11 (Transit) 12 (Radius) The id of the curriculum to send the user to. b. Optional Parameters: Parameter Value Notes last_name Student s Last Name first_name group Student s First Name Group Name This will be ignored if last name not passed. If this value is provided through SSO, students will not be asked to select their Group on the registration page as defined by the practitioner on the implementation call (i.e. Entering First- Year, Transfer, Athlete, etc.). EverFi can provide these values to you. If the parameter is unknown or not provided through SSO, then the student will self- select. This field is CASE SENSITIVE. If a group name is passed that does not match a group name in the EverFi platform, the student will be challenged to select their group from the values provided by the institution. Group can only be defined during registration. If the group is changed on subsequent crossovers, it will be ignored. dob Date of Birth Format: mmddyyyy (no dashes or slashes) This is used for de- duping student accounts. It is also used to determine if the student is over/under 18 years of age as schools have the option not to survey students under 18 for compliance reasons. 5

6 c. Error Codes: Status Code Format (JSON) Reason 401 {'errors': STRING} Invalid API token or version; or URL encoding issue 422 {'errors': ARRAY(STRING)} EverFi issues. Instructor Resource Guide Invalid fields. The strings in the errors array describe the d. Integrating On Development Instance We recommend testing on development first and especially if: 1) You are setting up in well in advance of your start date 2) You plan on having a large amount of unique testers go in, resulting in many accounts to delete Obtain your school id and api token from your partner service representative to test against EverFi s development instance. The values in bold below are examples of those values and should not be used for testing or set up. Sample Requests (POST) curl - H "Accept: application/json" \ - X POST \ - d "api_token=12345abcdefg12345 \ - d school_id= \ - d "student_id= " \ - d curriculum_id=8 \ - d "first_name=student" \ - d "last_name=one Smart Person" \ - d " _address=test@test7.dev" \ Concatenated Sample Post curl - - post301 - X POST &student_id= & _address=test@test7.de v&curriculum_id=8&first_name=student&last_name=one%20smart %20Person Non- Concatenated Sample Post curl - - post301 - X POST - d "api_token=12345abcdefg12345" - d "school_id=112233" - d "student_id= " - d " _address=test@test7.dev" - d "curriculum_id=8" - d "first_name=student" - d "last_name=one Smart Person" # Call is made using JSON # POST requests only # Your access token # Your provided school id # Your internal student ID # Curriculum ID # Student first name # Student last name # Student address # API post Requires URL encoding Does not require URL encoding On the development instance, a successful call will return the URL below that you can internally redirect your student to. The session key is generated by the EverFi platform at the time of your system s request. 6

7 Sample Successful Response From EverFi: abcde abcdef abcde = sample session key generated by the EverFi platform at the time of the request NOTES: 1. Do not load this page in frames, as it will cause errors with the course. 2. The SSO request should be made at the time the student wants to access an EverFi course and not before. 3. We recommend you call the API each time a student returns to log in to the course, rather than cache the URL. The response URL from EverFi will expire. 4. Be sure to add URL encoding if you plan to send parameters as a single concatenated POST. 5. All requests during development should be made to (BUT note the domain change on production). 6. All development requests are done in HTTP, though we enforce HTTPS on production. e. Testing on Development Student Login Test: 1. Log in to your test portal as a test student. Click the link/button you have created to enter EverFi. 2. Check the parameters on the registration page are passed correctly. 3. Agree to the "Terms of Use" and click "Let s Get Started". Expected outcome: you will launch into the course. Please note when testing AlcoholEdu, clicking Let s Get Started will launch you into Haven because the new version of AlcoholEdu is unavailable at this time on our new platform. 4. Log out (top right corner). Expected outcome: This should log you out of EverFi and take you to our logout message 5. Clear cache, 6. Re- POST the same SSO request (as you would on a second crossover attempt). Redirect browser to the URL in the response from the EverFi server. Note: the session token in the response may be different each time a POST is received. Expected outcome: you will go directly to the EverFi Student Dashboard and won't see the registration page again. 7. Log in to your portal as a different test student. Repeat steps 2-6 to be certain all information is passing correctly and is not accidentally hard- coded. 8. If setting up multiple curriculums, repeat steps 1-7 for all courses. Expected Test Results for this year s AlcoholEdu Upgrade Only Because the newest version of AlcoholEdu is under construction and moving platforms, the experience will change as we get closer to the official launch date. Timeframe 1st Crossover Experience 2nd Crossover Experience Now - June 1st Will see Haven instead of AlcoholEdu Will see the student Dashboard with AlcoholEdu, but an error upon launching the course 7

8 June 1st- General Availability date (roughly July 1) Will see an Under Construction page Student dashboard with AlcoholEdu and Under Construction upon launching the course After General Availability f. Integrating on Production Will see the new course Student dashboard with AlcoholEdu and the course upon launch Obtain your custom URL and api token from your Partner Services Director to test on production. The values in bold below are examples of those values. Sample Requests (POST) curl - H "Accept: application/json" \ - X POST \ - d "api_token=12345abcdefg12345 \ - d school_id= \ - d "student_id= " \ - d curriculum_id=8 \ - d "first_name=student" \ - d "last_name=one Smart Person" \ - d " _address=test@test7.dev" \ Concatenated Sample Post curl - - post301 - X POST 45&school_id=112233&student_id= & _ad dress=test@test7.dev&curriculum_id=8&first_name=student &last_name=one%20smart%20person Non- Concatenated Sample Post curl - - post301 - X POST - d "api_token=12345abcdefg12345" - d "school_id=112233" - d "student_id= " - d " _address=test@test7.dev" - d "curriculum_id=8" - d "first_name=student" - d "last_name=one Smart Person" # Call is made using JSON # POST requests only # Your access token # Your provided school id # Your internal student ID # Curriculum ID # Student first name # Student last name # Student address # API post Requires URL encoding Does not require URL encoding On the development instance, a successful call will return the URL below that you can internally redirect your student to. The session key is generated by the EverFi platform at the time of your system s request. Sample Successful Response From EverFi: abcde abcdef abcde = sample session key generated by the EverFi platform at the time of 8

9 the request NOTE: While development requests are done in HTTP, we enforce SSL encryption (HTTPS) on production for the security of your data. Same notes in red from the development section apply in production. Please make special note of the domain change on production. g. Testing on Production Student Login Test: Follow the same Student Login Test plan above (steps 1-8). Expected Test Results for this year s AlcoholEdu Upgrade Only Because the newest version of AlcoholEdu is under construction and moving platforms, the experience will change as we get closer to the official launch date. Timeframe First Crossover Experience Second Crossover Experience Now to June 1st Will see Haven instead of AlcoholEdu Will see the student Dashboard with AlcoholEdu, but an error upon launching the course June 1st- General Availability date (roughly July 1) After General Availability Will see an Under Construction page Will see the new course Student dashboard with AlcoholEdu and Under Construction upon launching the course Student dashboard with AlcoholEdu and the course upon launch VI. Document Revision History Date Revision Comments November 26, Set- Up Instructions to include: address as a required parameter, added error codes, added methods for development and production. July 22, Made relevant for all EverFi Higher Education programs on Homeroom (Buttonwood, Transit, Haven). Set- Up Instructions to include: school_id, curriculum_id and group. Removed vanity URL. November 18, Incorporated language from the AlcoholEdu guide and attempted to make the language more explicit. 9

10 December 31, 2013 February 27, 2014 March 11, Several edits. Added additional examples and reformatted the way the examples are presented. 5.1 DOB is now live (removed coloring and reference to being in the planning stage); added notes to the group attribute. 5.2 Clarified details regarding the Student Login Test plan and removed the second phase requesting instructors to log into the partner center. April 9, Clarified details regarding Student Login Test plan. Added expected test results table. 10