Wise App
  • Wise API Integration
    • Getting Started with Wise APIs
    • API Authentication
    • API Endpoints
    • SSO Integration
    • Webhooks Integration
      • Webhook Retry Mechanism
      • Webhook Event Samples
        • Participant Joined Meeting Event
        • Sharing Stared In Meeting Event
        • Participant Left Meeting Event
        • Sharing Ended In Meeting Event
        • Meeting Started Event
        • Meeting Ended Event
        • Recording Completed Event
        • Certificate Issued Event
        • Attendance Computed Event
        • Student Added To Classroom Event
        • Teacher Added To Classroom Event
        • Student Removed From Classroom Event
        • Teacher Removed From Classroom Event
        • Student Suspension Updated Event
        • Fee Payment Completed Event
        • Fee Invoice Charged Event
        • Sessions Created Event
        • Sessions Updated Event
        • Sessions Deleted Event
    • Rate Limits and Usage Quotas
    • Common Errors
  • Wise Data Storage Policy
  • Wise Android & IOS SDKs
    • Wise Android SDK (Kotlin)
    • Wise Android SDK (Java)
    • Wise Flutter SDK
    • Wise Flutter SDK - iOS Integration
  • Third Party Integrations
    • Custom Payment Gateway Integration
      • Razorpay Payments
      • Stripe Payments
    • AWS S3 storage
    • Custom Email
Powered by GitBook
On this page
  • What is SSO or JWT Token Identity Based Login?
  • How does SSO or JWT Token Indentity Based Login work?
  • Let's get started...
  • Step 1 : Get your White Label URL and jwtTokenSecret
  • Step 2 : Implement backend function to generate the Redirect URL
  • Step 3 : Consume this function/API from your frontend app (webapp)
  • An ideal flow would look like this:
  • Code (NodeJS)
  • Important Points to Note
  • Flow Diagram
  • User flow
  1. Wise API Integration

SSO Integration

PreviousAPI EndpointsNextWebhooks Integration

Last updated 2 months ago

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 () 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

JSON Web Token