With SSO, your users on your external site (hosted outside of New Zenler) can log in to your New Zenler Site without needing to set up additional login details on your New Zenler Site. The feature is super useful when you want the same credentials for your external site and also for your New Zenler Site.

This is available only on the Premium plan and should only be implemented by those who have access to software development resources. If you do not understand how SSO works, we would not suggest using this advanced feature.

How it works

When a user signs in to your external site, your application will construct a token (JWT) and redirect to New Zenler’s SSO URL with this token as a query string parameter. New Zenler decodes this payload and signs them in. If they don’t already have an account on your New Zenler site, it will be created and signs them in. Your application should construct the JWT payload per user. For this you will have to use any JWT package/plugin/library in your application to generate JWT payload dynamically. Various JWT libraries can be found here.

The JWT Payload

First, create a JWT payload containing the first name and email of the user and sign the JWT payload using your New Zenler site API developer key.

You can try generating the JWT payload from the JWT website. For this, get the following website: https://jwt.io and select the algorithm HS256

The JWT payload is typically constructed as a hash. The following attributes are supported:

{

"first_name": "USER FIRST NAME",

"last_name": "USER LAST NAME",

"email": "user@newzenler.com"

}

first_name (required)- the first name of the authenticated user.
last_name (optional)- the last name of the authenticated user.
email (required) - the email of the authenticated user.

Then verify your signature using your New Zenler school API key. For this login to your New Zenler school and go to Site->Developers->API Key.

If the API key is not already generated, generate the same and copy the key from there.

Go to https://jwt.io and paste the key here [Your-256-bit-secret]

Note: The option 'secret base64 encoded' should be left as UNCHECKED. Our application expects the API key as-is while verifying your JWT token.

Then copy the encoded token from here.

Then paste the same to the SSO URL.

https://YOUR_SITE/api/sso/v1?token=COPIED_TOKEN_HERE

YOUR_SITE: Replace the part in the URL with your New Zenler site URL.
COPIED_TOKEN_HERE: Replace this part in the URL with the token you copied

The created JWT payload is redirected to New Zenler’s SSO URL with this token as a query string parameter.

eg: https://yourschool.newzenler.com/api/sso/v1?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

https://yourcustomdomain.com/api/sso/v1?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Note: Above method is just an example shown on creating a token directly from JWT website for a static user. You have to use any JWT library in your application to dynamically generate JWT payload per user.

What is New Zenler SSO URL

The New Zenler SSO URL is the URL on your New Zenler school that you redirect after a user has successfully authenticated on your system. It has the following structure:

https://YOUR_SITE/api/sso/v1?token=JWT_PAYLOAD&return_to=URL_TO_RETURN_TO&error_url=URL_TO_REDIRECT_TO_IN_THE_CASE_OF_AN_ERROR

The parameters in the above URL is as follows:

token: The JWT payload that you construct and is REQUIRED.
return_to: The URL that you want the user to be redirected to after signing in to your NewZenler school. It is OPTIONAL.
If the return_to URL is not supplied, the user will be redirected to their default page within your New Zenler school.
error_url: The URL that you want the user to be redirected to in the case of an error. This is OPTIONAL.
If the error_url is not supplied, the user will be redirected to the New Zenler school error page. Otherwise, the user will be redirected to the error_url supplied with the error as a query string.