This integration took 6 months of work, so I hope it helps someone else… Updated 25.9.2023 as some of these things have been fixed. I hope my edits make sense!
Background-
The Zoho Desk Knowledgebase is quite full featured but has some odd quirks, some that make it unusable for us.
For example, you can set up users, groups categories etc. and allocate these permissions as you like.
Can’t Automatically Assign Permissions
However- there’s no way to automatically give these permissions to a user, and the user database is completely separate from other Zoho products like CRM, which means you have to manually assign permissions to each user if you want to give them access to articles they need for their work.
Can’t Disable Users Without Notification (This is now fixed- thank you!)
And don’t even get me started on the insane method of disabling or deleting users- there’s no way to stop a user from accessing the Knowledgebase without sending them an email saying they’ve been disabled.
That’s right folks- clean up your user database and suddenly you’ll get hundreds of ‘please explain’ emails from people you had banned or worse… and you cannot avoid this.
I believe it’s a security risk to leave old users active, but right now that’s the only way to roll without damaging your sanity.*
*This has been accepted as a feature request but we do not yet have an ETA (update- fixed!)
We wanted SSO anyway, why not start with Desk?
Zoho Desk supports several versions of Federation, but only certain providers listed in the link.
They don’t support OIDC, despite accepting this feature request 14 years ago…
SAML Setup- Zoho Desk
Zoho has adapted their KB article and added Zitadel, so I have modified this article to match their settings
So we’ll use SAML as it is our only option, here’s the settings- we’re going to assume you’ve already set up the knowledgebase like this. Your articles will be in categories, and you have set up some user Groups, then assigned those Groups to the Articles or to the Categories.
All of these settings are publicly available, so there doesn’t seem any point in obfuscating the links, we’ll use a non existent domain.
OK let’s assume your domain name is ‘ih8saml.com‘ and you have registered your Zitadel instance to ‘login.ih8saml.com‘
In Zoho Desk, go to
Settings/ Help Desk/ User Authentication
And add these items
Remote Login URL = https://login.ih8saml.com/saml/v2/SSO
Remote Logout URL = https://login.ih8saml.com/ui/console/signedout
Reset Password URL = https://login.ih8saml.com/ui/console/users/me?id=security
Zoho actually says to use this instead for PW Reset = https://login.ih8saml.com/saml/v2/SSO
Public Key = (instructions below)
How do we get the public key? go to your Zitadel instance-
https://login.ih8saml.com/saml/v2/metadata
You’ll see a bunch of XML. Find the <keyname> that says ‘https://login.ih8saml.com/saml/v2/metadata idp signing’ and copy the X.509 certificate string from underneath that into a text file. Add this to the top-
—–BEGIN CERTIFICATE—–
And this to the bottom-
—–END CERTIFICATE—–
Save it as ‘idp.txt’ and then upload to Zoho as the public key.
There’s a couple more things in that settings window, copy them down for the next step
SAML Setup- Zitadel
To get everything ready, you’ll need to create a ‘Project’ in Zitadel, add some users, roles, and allocate the users to the Project and their roles
Step 2 is to input the xml data-
I asked for the SP xml file for Zoho Desk and received this-
<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
validUntil="2023-05-26T14:48:33Z"
cacheDuration="PT604800S"
entityID="zoho.com">
<md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://accounts.zohoportal.com/accounts/csamlresponse/xxxx"
index="1" />
</md:SPSSODescriptor>
</md:EntityDescriptor>*Note- in the above XML, you’ll need to replace the csamlresponse endpoint ‘xxxx’ with yours- you copied this from your Zoho Desk settings page earlier.
Add Users
I assume you can do this, let’s move on…
Add Roles (this doesn’t work, don’t bother)
‘KEY‘ = Actual name of the Group you set up inside Zoho Desk. ‘Registered Users’ is there as a test, you’ll probably use client company names or roles etc.
‘DISPLAY NAME‘ = Name you want shown in any reference to the group
‘GROUP‘ column= ‘what is the name we pass to the SP to claim a Group membership?’
Why Did This Take So Long?
I kind of love Keycloak, but it’s had massive upgrades in the last few years and I could never find time for the project when it wasn’t going to cause issues upgrading. Also try looking at prices for ‘High Availability Keycloak’ – if you’re going to need reliability, you’re going to pay for it. A lot.
I found Zitadel and was immediately in love. While some of that love has turned to dust I still think the project is awesome and I want to buy shares in it one day.
As you can imagine, finding people who understand and can fix problems with SAML are rare- and finding someone who WANTS to fix these issues even rarer. It’s not an exaggeration to say that I spent at least 5 full days trying to understand and fix these issues, and that’s over $10k of labour on something I could have just avoided and made clients pay for Azure AD. I love open source software but some aspects can be soul destroying- remember nothing is truly free!
Or maybe ‘nothing worthwhile is easy’ might be better…
Unfortunately I joined the Zitadel army a bit too early and they were going through some things- but my early experiences absolutely blew me away.
Shout out to the team member who did a remote session with me, from Switzerland to Australia at 8am on a Friday morning. Then within a few days had a full writeup about using Zitadel with WordPress.
You can’t even get that kind of love with commercial support…
(I’m not naming this person because I don’t want every idiot like me contacting you for support, but thanks- you rock!)
Zoho were pretty good even though I was basically screaming at times to get attention, and every time something had to go ‘upstream’ to ‘the developers’ it was a 2 week delay. This meant going back and reading the spec again and again to figure out what I’d missed.
Seriously, who reads software specs? Like the old joke- it feels so good when you stop.
We did eventually find that Zitadel was sending time data with 6 significant figures, and the standard says 4.
So we had to wait while the Zitadel SAML module was updated, tested and rolled into the product. At this point a (different) Zitadel guy ghosted me and stopped answering questions. Please don’t do that. I had previously tried to offer money for help- you could have just said
‘ I did the basic stuff for free, how about we throw some money at this now?’
I would have been super happy. Or you could have told me to F off, at least that would have made my options clearer.
Update- Zoho actually fixed some of the issues I raised- thank you! But they still require us to use the built in user DB, and manually set permissions. This is spectacularly dumb, so I’m considering moving hundreds of support docs to a new platform JUST so I can make it easier for clients to access. GGRRRRR
To Zoho– you have a lot of support people. Some of them have made a career out of not answering questions. Fix your documentation. You can have better support outcomes and employ less people if they know what they are doing. Training people means watching what they do… sadly all of these things put extra strain on your experts, you can only remove that by having good documentation. To be fair- they never gave up- THANK YOU for not giving up!
To Zitadel– I think the focus on getting app integrations is absolutely the right approach for you, but I would stop making platform changes until your documentation is great. Good documentation would have saved a lot of aggravation, and me a lot of hours (many hours spent chasing dead links!).
I (generally) love your solution and hope we can expand our usage. Have an incident support price- doesn’t matter if it is expensive, allow the customer to choose if they want to pay. Your product is worthless if no one can use it- and you can create happy customers for no additional cost if your product is easy to use and well documented.
UPDATE- Zitadel have done this- have a look at the new API docs- they’re nothing short of amazing- Congratulations!
I’m not blameless here, I tend to bite off more than I can chew and chew like hell, perhaps I’ll change in my old age. Perhaps.
Resources
I found these resources really valuable-