❖ Heads up! This article is intended for Site Managers.
You can use our Single Sign-on (SSO) feature to sign into your site from your business, school, or other website. SSO confirms that a user is authenticated in your system before letting them access Get Connected. In other words, users are allowed access to your Get Connected site without using independent login credentials.
ⓘ So you know: We recommend that this feature be implemented only by individuals in an IT Support role.
What's supported?
We support JSON Web Tokens (JWTs), but we also support Security Assertion Markup Langauge (SAML). SAML may require additional charges depending on the setup. This article focuses on JWT.
How JWT SSO works
1. A user signs into your site—not your Get Connected site, but your school, work, business site, etc.
2. Once the user is authenticated on your site, a code written in your system must construct a JWT payload and redirect to the Get Connected SSO URL.
- This passes the payload as a query string parameter.
- You can also pass a properly encoded return URL as a query string parameter.
3. Get Connected deconstructs the JWT payload and either finds or creates the user.
- The user is then signed into your Get Connected site.
The JWT payload
Your application or site must construct the JWT payload and sign it using your Get Connected JWT secret key that we provide. The JWT payload is typically constructed as a hash. The following attributes are supported:
- email—the email of the authenticated user. This is required.
- firstName—the first name of the authenticated user. This is required.
- lastName—the last name of the authenticated user. This is required.
- referenceId—an identifier for the authenticated user. This can be the user ID of the authenticated user in your system. This is optional.
- iat—must be the number of seconds since UNIX epoch, or the time that the JWT payload was issued. This is required.
- jti—JWT ID. This is used to defend against replay attacks and is typically constructed using a combination of the iat and a random value. This is required.
✏️ Quick tip: A list of JWT libraries can be found here.
ⓘ So you know:
- The JWT payload is encoded and signed, not encrypted—i.e., don't put any sensitive data in the hash table.
- JWT works by serializing the JSON being transmitted to a string and then base 64 encodes that string, and makes a Hash-Based Message Authentication Code (HMAC) of the base 64 string that depends on the shared secret.
- This produces a signature that the recipient side can use to validate the user.
The return URL
Once a user is authenticated in your system, they should be redirected to your Get Connected site's SSO URL. You can append a "return" query string parameter as an encoded URL the user is returned to after the sign-in to your Get Connected school is complete as part of the redirect URL—e.g., http://{your-getconnected-url}/sso/jwta/?payload={payload}&return=http%3A%2F%2Fyoursite.com.
Your Get Connected SSO URL
The Get Connected SSO URL is the URL on your site that a user is redirected to following successful authentication in your system. It has the following structure: http://{your-getconnected-site}/sso/jwta/?payload={payload}&return=http:%3A%2F%2Fwww.yoursite.com%2Flogin%2F.
- The JWT parameter is the JWT payload that you construct. This is required.
- The return is the URL you want to redirect the user to after signing into your Get Connected school. This is optional.
- Users won't be redirected to their default page within your Get Connected system if the return URL is not supplied.
Error handling
If an error occurs, the user won't be signed into your Get Connected site. This can happen in several cases, including:
- Your code doesn't provide the JWT payload.
- Your JWT payload is not correctly signed.
- A validation error occurs when creating a new user on your Get Connected site—e.g., if one of the required parameters is missing.
- Some other unforeseen exception occurs.
If an error occurs and you have provided a return parameter, Get Connected's SSO won't sign the user in and redirects them to the supplied return URL with two parameters:
- kind—the type of error (currently one of three possibilities: jwt, validation, and unspecified).
- message—the error message.
If an error occurs and you have not provided a return parameter, Get Connected's SSO won't sign the user in and displays an error message on the default page of your site: 