Version 2. Updated 2019-03-23. For support with version 1, please contact [email protected]
The following guide is for implementors who would like something lighter weight than OpenID/SAML, or would prefer SchoolPay to be the identity provider. Please do not use this if your system should be the identity provider, unless you do not have an OpenID or SAML server and would like something easier to implement.
SchoolPay SSO is designed to be as easy for external applications to implement as possible. In most implementations you don’t even need to collect any special data from users.
External applications are assigned a provider name and a provider password when they sign up with us. The provider name is a short way to identify your application to us, and your password should be string of reasonable length and complexity. Your application’s password is used as a signing key to the HMAC-SHA512 algorithm. Please take all steps necessary to protect your application’s password as it can compromise the security of SchoolPay.com accounts.
You can either forward a user to our SSO gateway or you can generate a link for a user to click on. Our SSO gateway is fully functional with HTTP GET requests for maximum compatibility. URL Specification
- Production URL: https://www.schoolpay.com/api/sso/v2
- Development URL: https://dev.schoolpayqa.com/api/sso/v2
- Development Provider: Demo
- Development Password: 5d74b4999d87394dfc9f1c1e32ceddf7e574992e63269c38985618294fe7167a
|remote_id||Yes||This is a unique identifier for the user from your system.|
|provider||Yes||This is an agreed upon name for your software. Under most circumstances (especially with on premisis software) we will use the hostname of the service as the provider name. We will use it to look up your password.|
|time||Yes||This is the Unix time integer timestamp of the time the URL was created. Requests with times older than 20 minutes or future-marked more than 1 minute are rejected.|
|nonce||Yes||This is a random value that has not been seen in 7 days. We recommend using: base64_encode(openssl_random_pseudo_bytes(16))|
This field proves that the request is legitimately from your system. To calculate:
|data||No||This is parent data used to create an account on the fly. It is a base64-encoded, JSON-encoded object.|
|Required. The e-mail address of the student/guardian.|
|student_ids||Required. An array of student ID’s to be associated with the resulting SchoolPay account. You must send this even if the account created is for a student.|
|fname||The first name of the student/guardian.|
|lname||The last name of the student/guardian.|
|name||The full name of the student/guardian.|
GET https://schoolpayqa.com/api/sso/v2?time=1553380015&provider=apidemo2&remote_id=a6597&signature=qx8XOpFya6LqBvmi0ERdfcR2r2qdx73z1xLohY86CfTf%2Fkw4UkQGm8CX9O4OR%2Fg13c0sf%2BSyWqevDWTyjLXP0Q%3D%3D&nonce=sJh/APaxqfm+Y1P4jbqUiw==&data=eyJmbmFtZSI6Ik5hbmN5IiwibG5hbWUiOiJKb25lcyIsImVtYWlsIjoibmpvbmVzQG15cGF5bmV0LmNvbSIsInN0dWRlbnRfaWRzIjpbMTIzNDcwODU5XX0= HTTP/1.1
The paramters of the above request are repeated here for clarity:
Use these sample inputs to see if the link you generate is the same.
When a user clicks on a link for the first time, they will be asked to enter their SchoolPay.com username and password before they will be allowed to use the SSO gateway from your product.
When a user clicks on a link that has a bad timestamp, they will be shown an error page that tells them that the link is expired.
When a user clicks on a link that has a bad signature, they will be told there was aproblem with the request. For your debugging purposes, stringToSign will be visible on the page in hex. You can then look at the bytes of your stringToSign to see if the inputs line up correctly.