Integrating Single Sign-On (SSO)

This is an advanced plan feature that should only be implemented by those who are familiar with software development.

Single Sign-On is a feature that allows a learner to sign into an external platform and Graphy in a single login.

Learners will sign into your external platform. Once they successfully log in, your application will construct a token (JWT) and redirect to Graphy Platform URL with JWT token as a parameter. From this token, we find the learner and signs them in, or if they haven't registered, we create an account and signs them in.

Graphy SSO Url Format

https://{your-domain}/{any-url}?ssoToken=

your-domain is the domain linked to the Graphy platform.

any-url is the URL where you want your learners to land from the external platform.

JSON Web Tokens () consist of three parts separated by dots (.), which are:

• Header
• Payload
• Signature

Therefore, a JWT typically looks like the following.

xxxxx.yyyyy.zzzzz

Header

The header consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, such as HMAC SHA256. For example :

{

"alg": "HS256",

"typ": "JWT"

}

Then, this JSON is Base64Url encoded to form the first part of the JWT. In our case, the first part of the token is - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Payload

The payload is the Base64Url encoded form of payload data.

Payload Data format :

{

"name": "",

"email": "",

"password": "",
"exp": 1616239022 ,

"course-ids":["5e8824410cf2b0be8cb0b208","5d6f9bfde4b014833bferec3"]

}

name (optional) - the name of the authenticated user. It will be used while creating account of user.

email (required) - the email of the authenticated user. If not matched with any email, we create an account and signs them in.

password (optional) - the password of the authenticated user. It will be used while creating account of user.

exp (required) - must be the number of seconds since UNIX epoch.

course-ids (optional) - these are course-ids, if present will be assigned to the learners with default validity.

Signature

To create the signature part you have to take the encoded header, the encoded payload, api-token, the algorithm specified in the header, and sign that.

You will find your unique API Token from the admin panel under integrations.

For example, the signature will be created in the following way:

HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), api-token)

Then, signature is Base64Url encoded to form the third part of the jwt-token.

A typical jwt-token look like :

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6IjxFTUFJLD4iLCJleHAiOjE2MTYyMzkwMjJ9.zxKbL5EmSd8iDXfeHMOjZlfexAPi2r7m-T-mzUinrCU

Adding support for Login, Logout and Sign-up URL's

Often when using SSO, you will want your learners to use login, logout, and sign-up on your existing website. On Graphy, you can enter the existing URLs of your login and sign-up page. You can find these options under Integrations Third Party Single Sign On. 

You also have an option to enter logout URL, if you want to end the login session on your existing platform. Logout Url is optional.

Support for returnurl parameter

If you are using your external login, logout URLs for Single sign-on, we would suggest you implement the returnurl parameter support.

The returnurl parameter is appended to the login/Signup Url of your external platform. This parameter contains the URL to which you need to redirect after successful login/signup.

For example, the Login Url you have entered is https://xyz.yourplatform.com/login. We would hit this Url with the returnurl parameter in the following way: https://xyz.yourplatform.com/login&returnurl=https://abc.yourplatfrom.com/mycourses. After successful login on your platform, you should redirect to the following url: https://abc.yourplatfrom.com/mycourses?ssoToken=

Please note the returnurl parameter is an encoded url, you need to use the decode url function before redirecting.