Set up custom sign on for your portal
Last Update: Sep 2024 • Est. Read Time: 3 MINThe portal allows customers to log in to an authenticated page and view their conversation history. With this flow, users are redirected from the portal through your site’s login process before returning to the portal, where new users are created and returning users are automatically logged in.
This article outlines the steps you need to follow to set up custom authentication using your own login flow.
Who can access this feature? | |
User types | Content administrators can access knowledge base settings. |
In this article:
- Get secret
- Implement JWT signing with your secret
- Redirect users to Kustomer with the signed JWT token
- Turn on custom sign on for your portal
Get secret
The first step is to obtain the secret needed to implement the JWT signing.
- In the Kustomer app, go to Settings> Knowledge Base > Configuration.
- Select the brand for which you are creating the portal from the Brand drop-down menu (if applicable). If you don’t have additional brands created, this will be the default brand.
- Scroll down to the Additional Information section in the General tab and copy your Knowledge Base ID.
- Make an API GET call to
https://org-name.api.kustomerapp.com/v1/auth/kb/:id/settings
, whereorg-name
is the name of your Kustomer organization and:id
is the ID of the knowledge base that you copied.
If you do not know your organization name:- If you are located in the Americas, use
https://api.kustomerapp.com/v1/auth/kb/:id/settings
- If you are located in Europe, use
https://api.prod2.kustomerapp.com/v1/auth/kb/:id/settings
You will need a Bearer Authorization token to make this request. If you don't already have a token, you can create one by going to Settings> Security > API Keys. Select Add API Key and create a new key that does not expire using the org.admin role.Note: This API call returns a JSON payload containing a secret value inside the attributes field. Save this secret value in your server for reference later.
- If you are located in the Americas, use
Implement JWT signing with secret
A user going through this login flow will be redirected from the Kustomer app to your domain:
- The login URL we redirect to will include an unsigned
trackingToken
parameter (which can be ignored) and akustomerRedirectUri
parameter which you’ll use to return the user to the Knowledge Base Portal. - The URL we send authenticated users to will look like this:
https://{yourLoginPage}?trackingToken=UNSIGNED_JWT_TOKEN&kustomerRedirectUri={urlBackToKustomerKnowledgeBasePortal}
After a user has been successfully authenticated via email and password (or another method) against your servers:
- Sign a JWT token in your server using the secret value stored in step 4 of the Get secret procedure and the user’s email. The following is a sample of signing the token in nodeJS server code:
var jwt = require('jsonwebtoken'); var token = jwt.sign({ email: "CUSTOMER_EMAIL", iat: Math.floor(Date.now() / 1000) }, 'SECRET_KEY', { header: { alg: 'HS256', typ: 'JWT' } }),
- When redirecting the user back to your Knowledge Base portal login page, pass the signed token set as an
externalToken
query parameter.Note: iat: Math.floor(Date.now() / 1000) is the current time in UTC seconds. Signed tokens will only be valid for 15 minutes.
Redirect to Kustomer with the signed JWT token
Once authentication is finished in your site, redirect the user back to our website with the signed auth token.
- Redirect the user back to the
kustomerRedirectUri
query parameter that is passed to your login URL, which may look similar to:kustomerRedirectUri=https://yourcompanyname.kustomer.help/login?referralUrl=https://yourcompanyname.kustomer.help
- Include the signed JWT token on a new
externalToken
parameter. The URL you redirect to should be formatted as{kustomerRedirectUri}&externalToken={SIGNED_JWT_TOKEN}
and look similar to:https://orgname.kustomer.help/login?referralUrl=https%3A%2F%2Forgname.kustomer.help[...]&externalToken=eyJh[...]kQ
Turn on custom sign on for your portal
The final step is to turn on custom sign on and enter the URL of your portal log in page. This is the URL customers are redirected to once they click the Login in button on your portal.
To turn on custom sign on:
- Go to Settings> Knowledge Base > Configuration.
- Select the Portal tab and then select Portal Authentication.
- Turn on the Custom Sign On toggle.
- Enter your unique log in page URL in the Redirect URI box.
- Select Done.
Your customers can now sign in to your secure portal using your own login flow.