eSchoolPlus SSO relies on something called a dynamic link.
Dynamic Links are something included in the eSchoolPlus application.
When a school sets up a dynamic link in eSchoolPlus the parents and teachers will see that link in a section called School Links in eSchoolPlus.
When the parent/teacher clicks the link - eSchoolPlus will open a window that says "Launching PTC Wizard...."
When that happens, eSchoolPlus will send a request to PTC Wizard for something called a Login Token.
The request goes to: https://<subdomain>.ptcwizard.com/authenticate/GenerateLoginToken
(the subdomain is replaced with the actual subdomain for the school)
PTC Wizard responds with a random number.
eSchoolPlus takes the number and then creates a login token by encrypting the number with a private key that is shared by PTC Wizard and eSchoolPlus.
Then eSchoolPlus redirects the user to PTC Wizard with the login token with the parent/teacher username.
PTC Wizard verifies the login token is valid and then uses the username to lookup the user in the appropriate table (parent or teacher table).
Then PTC Wizard logs the user in and forwards them to the appropriate site.
There are 3 database records that need to be added to eSchoolPlus for the dynamic link to work.
They need to add the records to the eSchoolPlus table spi_integration_det in eSchoolPLUS
- LOGIN_VALIDATION_SERVICE
- SERVER
- SYNC_GUID
LOGIN_VALIDATION_SERVICE is the url at PTC Wizard where eSchoolPlus can request GenerateLoginToken.
The value for this field should be: https://<subdomain>.ptcwizard.com/authenticate
eSchoolPlus will automatically append "/GenerateLoginToken" to the url in the field LOGIN_VALIDATION_SERVICE
SERVER is the url at PTC Wizard where eSchoolPlus can redirect the user
The value for this field will probably be something like:
https://<subdomain>.ptcwizard.com/authenticate/sungard
SYNC_GUID is the PTC Wizard school id that gets passed to PTC Wizard with the request. The school id should match the subdomain being used.
Detailed Explanations:
The process starts off with eSchoolPlus sending a request to PTC Wizard for a login token.
This request is in the form of a url that eSchoolPlus takes from LOGIN_VALIDATION_SERVICE
The url will be https://<subdomain>.ptcwizard.com/authenticate/GenerateLoginToken
The <subdomain> is your schools subdomain for accessing PTC Wizard.
When PTC Wizard receives a request to GenerateLoginToken, it will create a token and create a hash on the token using a shared private key with the school.
PTC Wizard will then save the hashed token and return the original un-hashed token in the response.
eSchoolPlus will then create the same hashed token using the shared private key and send a request to PTC Wizard to log in a particular user.
In order to accomplish this, eSchoolPlus sends a request to the URL: https://<subdomain>.ptcwizard.com/authenticate/sungard/?loginToken=<their login token from GenerateLoginToken>&loginDestinationCode=<the parent_localid or teacher_localid>&loginDestination=<either: ‘haclogin’ or ‘teacher’>
Let's explain the parameters here:
| loginToken | This is the hashed version of the token received from PTC Wizard when requesting a token using: https://<subdomain>.ptcwizard.com/authenticate/GenerateLoginToken/ |
| loginDestinationCode | This is the username of the parent or teacher. It must match the username field you uploaded in the CSV files. This is NOT the parent_localid or teacher_localid. It is the same username that the user logs in with on HAC and TAC. |
| loginDestination | This can either be haclogin or teacher This field determines if you want sign the user into PTC Wizard as a parent or a teacher. It will determine which site we forward the user to after authentication. |