Automatically Sign in From Your Own Website

Use Get Connected's Single Sign-on (SSO) feature to sign in to your Get Connected site from your school or business website. Our SSO confirms that a user has been authenticated in your own system before allowing them to access Get Connected as an authenticated user. This means the user is allowed to access your Get Connected system without having to use independent login credentials.

Note: This feature should only be implemented by those who work with IT support. Contact support@galaxydigital.com if you have any questions about whether this solution is right for you.

This article focuses on Get Connected's default SSO feature, which uses JSON Web Tokens (JWTs). Shibboleth is also supported but may require additional charges depending on how they are set up.

SSO Overview/Setup

Described below is a basic overview of how SSO works:

  1. User signs in to your system (not your Get Connected site).
  2. Once the user is authenticated on your system, code written within your system must construct a JWT payload and redirect to Get Connected's SSO URL, passing the payload as a query string parameter. You may 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 (if the user has not already been created). The user is then signed into your Get Connected system.

The JWT Payload

Your application must construct the JWT payload and sign it using your Get Connected JWT secret key that we provide you. 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 might be the id of the user in your system. This is OPTIONAL.
  • iat - must be the number of seconds since UNIX epoch. This is essentially 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.

A list of JWT Libraries can be found here. The JWT payload is merely encoded and signed, not encrypted, so do not put any sensitive data in the hash table. JWT works by serializing the JSON that is being transmitted to a string. It then base 64 encodes that string and then makes an HMAC of the base 64 string which depends on the shared secret. This produces a signature that the recipient side can use to validate the user.

The return URL

After a user is authenticated in your system, they should be redirected to your Get Connected site's SSO URL. As part of the redirect URL, you can append a "return" query string parameter that is an encoded URL to which the user will be returned after the sign in to your Get Connected school is complete. For example:
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 Get Connected website to which a user is redirected 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 to which you want to redirect the user after sign-in to your Get Connected school. This is OPTIONAL.
  • If the return URL is not supplied, the user will be redirected to their default page within your Get Connected system.

Error Handling

If an error occurs, the user will not be signed into your Get Connected site. This may occur in several cases:

  1. Your code does not provide the JWT payload.
  2. Your JWT payload is not correctly signed.
  3. A validation error occurs when creating a new user on your Get Connected site (if one of the required parameters is missing, for example).
  4. Some other unforeseen exception occurs.

If an error does occur and you have provided a return parameter, Get Connected's SSO will not sign the user in and will redirect 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 will not sign the user in and will display the error message on the default page of your Get Connected website.

Ruby Example

payload = JWT.encode({
:email => "jdoe@example.com",
:firstName=> "John",
:lastName=> "Doe",
:referenceId=> "8675309",
:iat => Time.now.to_i, 
:jti => rand(2<<64).to_s }, "MY_SHARED_SECRET")response.headers["Location"] = "http://{your-getconnected-site}/sso/jwta/?payload=#{payload}"

PHP Example

$token = array(
"firstName" => 'John',
"lastName" => 'Doe',
"email" => 'jdoe@example.com',
"referenceId" => '8675309',
"iat" => time(),
"jti" => md5(uniqid(mt_rand())
);
$payload = JWT::encode($token, MY_SHARED_SECRET);
$url = 'http://{your-getconnected-site}/sso/jwta/?payload=$payload&return_url=' . urlencode('http://www.mysite.com/login/');
header("Location: ". $url);
exit();