See related

Set up custom sign on for your portal

Last Update: Sep 2024 • Est. Read Time: 3 MIN
To check plan availability, see the pricing page.

The 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 typesContent administrators can access knowledge base settings.


In this article:

Get secret

The first step is to obtain the secret needed to implement the JWT signing.

  1. In the Kustomer app, go to Settings> Knowledge Base > Configuration.
  2. 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.
  3. Scroll down to the Additional Information section in the General tab and copy your Knowledge Base ID.
  4. Make an API GET call to https://org-name.api.kustomerapp.com/v1/auth/kb/:id/settings, where org-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:
    1. If you are located in the Americas, use https://api.kustomerapp.com/v1/auth/kb/:id/settings
    2. 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.

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 a kustomerRedirectUri 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:

  1. 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'
     }
    }),
  2. When redirecting the user back to your Knowledge Base portal login page, pass the signed token set as an externalTokenquery 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.

  1. 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
  2. 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:

  1. Go to Settings> Knowledge Base > Configuration.
  2. Select the Portal tab and then select Portal Authentication.
  3. Turn on the Custom Sign On toggle.
  4. Enter your unique log in page URL in the Redirect URI box.
  5. Select Done.

Your customers can now sign in to your secure portal using your own login flow.