SSO Integration
Last updated
Last updated
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.
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.
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 jwtTokenSecret
which 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)
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 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
User logs into your client app using your login mechanism (phone/email)
User intends to open Wise WL. Client app (web/mobile) makes an API call to log in, on user’s behalf
Your backend API authenticates your user, like any other authenticated API
Backend API generates short lived redirect URL for that user
This URL is returned to the client app opens this URL in browser
User logs into the Wise account (mapped as same phone number OR email)
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
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
About payload
Use userId
, which is the actual userId of the user in the Wise/Lens eco-system
Use vendorUserId
, instead of userId
, if you use a unique ID in your system as identity. Pass your system's UUID in vendorUserId
field
Use email
, instead of userId
, if you use email as identity in your system. Pass primary emails from your system
Use phoneNumber
, instead of userId
, if you use phoneNumber as identity in your system. Pass primary phoneNumber from your system
Only one of these four -- userId
or email
or phoneNumber
or vendorUserId
-- should be passed. More than one cannot be passed
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.
Profile will be one of student
or teacher