SSO Integration

What is SSO or JWT Token Identity Based Login?

Single sign-on (SSO) is an authentication method that enables users to securely authenticate with multiple applications and websites by using just one set of credentials.

How does SSO or JWT Token Indentity Based Login work?

The data used for SSO is passed as an encoded token, know as a JWT (JSON Web Token) in the URL - the token is an alphanumeric string about 150 characters long. The token is signed using a special key (jwtTokenSecret) that is unique to each company and only the company administrators have access to. The data passed in the token is email or phoneNumber, profile (teacher, student), name and a validity time duration exp (upto 2 mins) - no passwords are passed, encoded or otherwise. The token is then decoded by the Wise servers and the signature is checked to verify the token was signed by the jwtTokenSecret associated with the account. If the token was not signed with the correct key the SSO login will fail.

Let's get started...

Step 1 : Get your White Label URL and jwtTokenSecret

You must already have your whitelabel application ready and with that you should be given a WISE_WHITELABEL_URL where you can login to create your institute and classes and add/invite teachers and students to it.

Once you have that, you can request your relationship manager for the jwtTokenSecretwhich can be used to sign-in teachers and students directly based on your identity management system.

WISE_WHITELABEL_URL: Wise URL provided to you (eg: xyz.onlineclass.site)

jwtTokenSecret: 32 B hex string provided to you (eg: 5fe9e02f07cxxxxxxxe7950e437ece30)

Step 2 : Implement backend function to generate the Redirect URL

For each member of your institute, teachers, students and admins, you can generate a unique JWT Token using the code mentioned below. The JWT token used to construct a unique redirect URL for your institute members, which will login the members directly into your white label website. URL: {WISE_WHITELABEL_URL}/identity-based-login?jwtToken={jwtToken}

If you would like to redirect the user to a different webpage than the homepage on the whitelabel, you can use the following format of the redirection URL

// For redirecting student to a particular classroom 1234, use this

https://{WISE_WHITELABEL_URL}/identity-based-login?jwtToken={token}&redirectionUrl=/student/classes/1234/resources&current_role=student

Step 3 : Consume this function/API from your frontend app (webapp)

For the logged in user in your app, upon user’s request to open Wise WL, your frontend will request your backend to provide this redirection URL. Then frontend will redirect to this redirection URL in the browser

An ideal flow would look like this:

1. User logs into your client app using your login mechanism (phone/email)

2. User intends to open Wise WL. Client app (web/mobile) makes an API call to log in, on user’s behalf

3. Your backend API authenticates your user, like any other authenticated API

4. Backend API generates short lived redirect URL for that user

5. This URL is returned to the client app opens this URL in browser

6. User logs into the Wise account (mapped as same phone number OR email)

Code (NodeJS)

// nodejs snippet
jwt = require('jsonwebtoken')
moment = require('moment')

jwtTokenSecret = "<JWT Token secret shared by Wise>" // This SHOULD BE secret*

// Redirect URL generation function on backend
function generateRedirectURL(userId, profile, name) {
	const payload = {
    		userId: userId, // or vendorUserId, email, phoneNumber (any of these will work)
		profile: profile, 
		name: name, 
		exp: moment().add(1, 'm').unix(),
		nonce: "<unique random string, up to 36 char>" // optional
	}
	const jwtToken = jwt.sign(payload, jwtTokenSecret)
	return `${WISE_WHITELABEL_URL}/identity-based-login?jwtToken={jwtToken}`
}

// Calling the function inside API to sign into Wise: 
const user = { userId: "xuoad12123cadsad", "name": "Abhijeet" }
// User identified, authenticated by you in your system & fetched from your DB
const redirectURL = generateRedirectURL(user.userId, user.name, "student")
// Return redirectURL generated for given user to the client app (web/Mobile)

Important Points to Note

1. You need to do this on your backend. The jwtTokenSecret SHOULD NOT be shared with anyone or SHOULD NOT be put on client (web/app) code. If compromised, your system will be compromised

2. WISE_WHITELABEL_URL is your White Label URL. You should return the redirect URL to the client (web/app) to login the student/teacher/admin to their account

3. About payload

   1. Use userId, which is the actual userId of the user in the Wise/Lens eco-system

   2. Use vendorUserId, instead of userId, if you use a unique ID in your system as identity. Pass your system's UUID in vendorUserId field

   3. Use email, instead of userId, if you use email as identity in your system. Pass primary emails from your system

   4. Use phoneNumber, instead of userId , if you use phoneNumber as identity in your system. Pass primary phoneNumber from your system

   5. Only one of these four -- userId or email or phoneNumber or vendorUserId -- should be passed. More than one cannot be passed

   6. exp This indicates the timestamp till which the token remains active. For security reasons, it should stay active for a small duration only. Keeping the redirects on slow internet connections in mind, a timestamp 5-10min in future should be an ideal expiry.

4. Profile will be one of student or teacher

Flow Diagram

User flow