HubSpot knowledge base setup SSO JWT authentication

Develop, Build & Integrate APIs & Integrations
1

Trying to implement SSO access to our Knowledge Base on HubSpot, following this guide.

It’s not clear what exact response Hubspot expects from the Remote Login endpoint.

Can anyone share a sample code for JWT Hubspot SSO implementation?

Or provide more details on the expected values for the ‘redirect_url’ and the rest of the response?

2

Hi, @IEliaz :waving_hand: Thanks for your question. I’d like to invite some of our community experts to the conversation — hey @Humashankar @Phil_Vallender do you have any tips you can share with @IEliaz to help them get moving forward? I know setting this up can be a complicated process so any help is greatly appreciated.

Thank you! — Jaycee

3

Hi @IEliaz

When implementing HubSpot SSO, your Remote Login endpoint should return a JSON response containing two key fields: redirectURL and token -optional.

The redirectURL is the most important portion, as it specifies the URL to which HubSpot will redirect the user after successful authentication, typically including the JWT token as a query parameter.

This URL usually points back to your Knowledge Base or another part of your application, and its domain must match the one configured in your HubSpot SSO settings.

The expected format is a fully qualified URL,

such as https://your-knowledge-base-domain.com?auth_token=your_generated_jwt_token,

which will be validated by HubSpot to ensure correct formatting

Hope this helps - Happy to help further!!
Thank you very much and have a great one!
Warm regards

4

Thank you for your response.

So in the response the two important parameters are the ones you listed. Are these the only two mandatory parameters in response?

Is the token applied by HubSpot in any way?

Regarding the request sent by HubSpot to Remote Login - I see that the payload includes the following parameters:

{
“domain”: “”,
“loginUrl”:,
“algorithm”: “HS256”,
“key”: “”,
“issuer”: “”,
“subject”: “”,
“audience”: “”
}

I understand the last 3 are optional, but I’m missing in the request some kind of user identification…

Is there any access to the “original” knowledge base URL the user was trying to access?

If user was trying to access page X in the knowledge base I would need to know the value of X in order to build the redirectURL, correct?

Also, its not clear which domain to select for setting up SSO to our HubSpot Knowlege base. The actual Knowlege base URL is based on our HubSpot custoer id, e.g. https://[cid].hs-sites.com, which is not listed in the “Choose a domain to edit” list.

Thanks,

IEliaz

5

Hi @IEliaz

Here is a quick summary of several key points which you are trying to clarify.

  • The redirectURL is the primary mandatory parameter that HubSpot expects in the response. The token is optional and typically embedded within the redirectURL as a query parameter. This token is used to authenticate the user when they are redirected back to your application or Knowledge Base
  • The JWT token is not processed or modified by HubSpot. Instead, HubSpot simply redirects the user to the redirectURL provided, which should include the token as part of the query string. Your application will then decode and verify the JWT token to authenticate the user
  • On Missing User Identification front, You’re correct that the payload doesn’t include specific user identification information by default. The SSO process generally expects that your system will authenticate the user based on your internal credentials or session data. You’ll then generate the JWT token containing the necessary claims such as- user ID, email to return in the response.
  • Regarding the domain selection for SSO, it’s important to note that HubSpot typically requires the domain of your SSO endpoint to match one of your verified domains
  • The URL you mentioned, https://[cid].hs-sites.com, is based on your HubSpot customer ID and is not the domain used for SSO. You should select the domain where your SSO login endpoint is hosted (yourcompany.com). This domain must be configured and verified within HubSpot’s domain settings.
  • The original URL you’re trying to access isn’t included in the standard payload. To address this, implement a session or state management mechanism in your application to track the user’s intended destination before starting the SSO process. If maintaining the original destination is essential, consider customizing the login page redirect by appending the original destination as a query parameter. This allows you to capture and utilize it to construct the redirectURL.

Regards

6

Thank you. much appritiated.

One last (I hope :)) question regarding your last point:

“consider customizing the login page redirect by appending the original destination as a query parameter”

--> the Remote Login URL is setup in HubSpot SSO setup dialog - How can it be customized to append the original destination? does it support some kind of macro to pass the original destination in the setup box ?

e.g. https://my.domain.com/hubSpotSSOendpoint?original_dest={referer}

IEliaz_0-1723468798010.png
IEliaz_0-1723468798010.png736×441 52.4 KB

In this other communicty thread it seems the request processor is extracting the original destination from a request parameter called ‘redirect_url’

https://community.hubspot.com/t5/APIs-Integrations/TOKEN-VERIFICATION-FAILED-Unable-to-verify-JWT-token-with-SSO-to/m-p/707838#M57986

Would that work for extracting the original URL?

7

Hi @IEliaz

Happy to clarify your data points.

To clarify the process of capturing the original destination URL, there are two primary methods to consider.

Firstly, you can leverage the redirect_url parameter by checking if your Remote Login endpoint receives it and extracting the original URL from it but be sure to verify with HubSpot, if this parameter is consistently populated in your setup.

On the other hand, you can implement a custom login flow by capturing the original URL before redirecting to the HubSpot login page, storing it in a session or hidden form field, and retrieving it after SSO to construct the redirectURL.

The best approach depends on your specific needs and preferences, with the redirect_url parameter suitable for those comfortable with potential variations in HubSpot’s behavior, and a custom login flow recommended for those prioritizing control and consistency.

Best Regards