SSO

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

Query Param Required Description
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))
signature Yes

This field proves that the request is legitimately from your system. To calculate:

$string = $remote_id . $time;
$sig = hash_hmac('sha512', $string, $password, true);
$sig = base64_encode($sig);
data No This is parent data used to create an account on the fly. It is a base64-encoded, JSON-encoded object.

Parent Data

Param Value
email 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.
Example Request 
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:

Param Value
time 1553380015
provider apidemo2
signature qx8XOpFya6LqBvmi0ERdfcR2r2qdx73z1xLohY86CfTf%2Fkw4UkQGm8CX9O4OR%2Fg13c0sf%2BSyWqevDWTyjLXP0Q%3D%3D&nonce=sJh/APaxqfm+Y1P4jbqUiw==
data {"fname":"Nancy","lname":"Jones","email":"[email protected]","student_ids":[123470859]}

Use these sample inputs to see if the link you generate is the same.

DO NOT compute your signature with client-side javascript. It is strongly encouraged that you take all steps required to protect your password. Error Handling and Exception Scenarios

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.

Go Live