How to setup Freshdesk JWT SSO with Laravel

I struggled for many hours getting this setup and figured I would share what I found work setting up Freshdesk SSO setup in a Larvavel environment took.

composer require firebase/php-jwt
//I also am using just a single name attribute, so I will use a name parser to get the first_name and last_name that freshdesk requires.
composer require theiconic/name-parser

The next thing we need to do is set up the route that Freshdesk will be redirected to and make sure it is behind the auth middleware.

Route::middleware(['auth', 'verified'])->group(function () {
    Route::any('/fd/authorize',[App\Http\Controllers\Controller::class,'freshDeskAuthorize']);
});

public function freshDeskAuthorize(Request $request)
    {
        $user = $request->user();
        $name_parser = new \TheIconic\NameParser\Parser();
        $name = $name_parser->parse($user->name);
        $privateKey = <<<EOD
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
EOD;
        $jwt = JWT::encode([
            'sub' => (string) $user->id,
            'email' => $user->email,
            'iat' => now()->timestamp,
            'nonce' => $request->input('nonce'),
            'givenname' => $name->getFirstname(),
            'surname' => $name->getLastname()
        ],$privateKey,'RS256');

        $url_params = [
            'id_token' => $jwt,
            'state' => $request->input('state'),
        ];
        return redirect()->away($request->input('redirect_uri').'?'.http_build_query($url_params));
    }

The big gotcha that spent me reeling for hours was that I needed to cast the user id to a string. If we leave it an integer, SSO will fail every time with “Invalid credentials” on Freshdesk.

I am parsing the user’s name, so we have first_name and last_name. Then we will create a JWT token from some of the request data Freshdesk sends in their request coupled with our user data. NOTE: Freshdesk API says that given_name and family_name are the params, but givenname and surname are what actually set the correct user attributes, so be on the lookout in the future if they end up matching these values.

Next, we need the public and private keys to use in our controller and add in Freshdesk.

#generate RSA key
ssh-keygen -t rsa -b 1024 -m PEM -f jwtRS256.key
# use empty passphrase 
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Take the private key and update the corresponding section of the controller.

Now, we can take everything we have and update Freshdesk to make the connection.

Navigate to the ‘Security’ icon located in the sidebar. Within the ‘Security’ section, under ‘Agents & Employees,’

Note: The configuration of SSO is exclusively accessible to Organization Admins. For contacts, any security policies can be defined under the ‘Security > Contacts’ section. https://yourcompany.myfreshworks.com/security/contacts

Keep in mind: The Neo Admin Center, which houses these settings, can be reached via the Freshworks Switcher. Simply click on your organization’s link to access it.

Create a new Contacts Custom Policy that is SSO with JWT

• Authorization URL: This is the route we created above https://yousite.com/fd/authorize
• RSA Public Key: The public portion of your RS256 Key we created above
• Logout URL: Though optional, you can provide a designated logout URL. Users will be directed to this URL upon logging out.

Now that Freshdesk is set up, the last thing we need to do is create a link in our app that sends users to our Helpdesk Portal.

At the end of setting up the Custom Policy in Freshdesk, you will be presented with a URL we can use.

<a class="mr-6 rounded bg-orange-500 px-2 py-1 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600" href="https://yourcompany.myfreshworks.com/login/auth/1661368862922?redirect_uri=https%3A%2F%2Fyourcompnay.freshdesk.com%2Ffreshid%2Fcustomer_authorize_callback%3Fhd%3Dyourcompnay.freshdesk.com&client_id=YOUR_CLIENT_ID">Help</a>

There is probably a better place to find the CLIENT_ID, but I went to the contact login at Freshdesk for the SSO we set up and grabbed it from the request after pressing the login button.

Hopefully, this saved you some time because I couldn’t find any good documentation on setting up Freshdesk SSO with Laravel when I was setting this up.