White label Single Sign-On with JWT
Instructions
Single Sign-On (SSO), allows your users to log in to your website using their existing account on your white label domain and also allows your users to login to your white label domain from your website without asking for credentials. Below you will find more details on how to set up SSO.
You need to enable the SSO JWT from the custom addons under your white label settings. Once enabled the SSO JWT addon, you can generate the private key and change the redirect URL in the addon settings.
Scenario 1 (White label domain to your website)
Example: your white label domain is https://your-white-label-domain, your website is https://crm.yourwebsite.com
1. Copy your SSO Private Key
Copy your private key to a safe place as it will be used to decode and verify the secure JWT token on your server.
Example: A8F3KWlNKezFuKqk2aGfrRLBKRUfTblA
2. Change the redirect URL
The redirect URL will be used to send the JWT token when the user clicks the SSO URL (Example: https://your-white-label-domain/sso/redirect).
Example of Redirect URL: https://crm.yourwebsite.com/portal/login/
3. Add the SSO URL as custom menu
The SSO URL will be your white label domain append with /sso/redirect, you can add this URL as custom menu to be clickable in the side menu.
SSO URL (Example: https://your-white-label-domain/sso/redirect).
When the user login to your white label domain and clicks the SSO URL from side menu, UChat will generate the JWT token with payload and redirect the user to the provided redirect URL with the JWT token as parameter in the URL.
Example of URL with token: https://crm.yourwebsite.com/portal/login/?token={JWT_TOKEN}
4. Install a JWT library on your website
We use JSON Web Tokens (JWT) to authenticate users, the token will be encrypted and signed from UChat. Use the private key to decode the JWT token, you should get the payload after verifying the token expiry and signed signature.
Example Payload:
{
"email": "john@example.com",
"name": "john smith",
"user_id": 123,
"workspace_id": 456,
"sso_id": 789,
"iat": 1706327067,
"exp": 1706327367
}5. Verify the JWT Token and login the user to your website
If the JWT token is valid, you can use the email address from the payload to login the user to your website. If the user login is successful, you can redirect the user to the page from your website.
Scenario 2 (Your website to White label domain)
Example: your white label domain is https://your-white-label-domain, your website is https://crm.yourwebsite.com
1. Copy your SSO Private Key
Copy your private key to a safe place as it will be used to generate a secure JWT token on your server.
Example: A8F3KWlNKezFuKqk2aGfrRLBKRUfTblA
2. Install a JWT library on your website
We use JSON Web Tokens (JWT) to authenticate users, the token is composed of a name and email, encrypted and signed on your server, allowing UChat to verify that the token comes from a trusted source without exposing your user information.
3. Generate the JWT Token
After the user login to your website successful, you can provide a link for the user to click and redirect back to your white label domain with the generated JWT token. You need to include email, name, workspace_id, sso_id, iat and exp in the payload to generate the JWT token using the JWT library you previously installed.
Example Payload:
{
"email": "john@example.com",
"name": "john smith",
"workspace_id": 456,
"sso_id": 789,
"iat": 1706327067,
"exp": 1706327367
}4. Redirect the user back to your white label domain
With the JWT token generated, all you need to do is redirect the user back to https://your-white-label-domain/sso/auth/?token={JWT_TOKEN} so we can log the user in.
The /sso/auth/ only work if there is no user already logged in with your white label domain. If there is already a user logged in with your white label domain, the /sso/auth/ will be ignored and redirect to the dashboard of the workspace for the current user.
Code Samples to generate the JWT token with PHP.
Install a JWT library.
We use JSON Web Tokens to securely authenticate your users. First, install the appropriate JWT library for your server.
composer require firebase/php-jwt