Helpdock 0.6.0: SSO and Zendesk, Freshdesk, Zoho Imports

Executive Summary

Helpdock 0.6.0 is out: the release of my open-source, self-hosted help desk focuses on the two things that stop teams from switching: sign-in and migration.
Staff single sign-on: any SAML 2.0 or OpenID Connect provider. The SSO guide walks through Okta, Microsoft Entra ID, Google Workspace and Keycloak.
Accounts from IdP groups: the first sign-in creates the account and its brand roles. A group removed in the IdP removes the matching role at the next sign-in. Roles an admin assigned by hand are never touched.
Importers: Zendesk, Freshdesk and Zoho Desk connectors, plus a CSV/bundle mapper for any other tool. Tickets with full threads, private notes, original authors and dates, contacts, companies, CSAT, files and help-center articles.
Nothing is sent: an import sends no emails and starts no rules, SLA timers, notifications, webhooks or AI calls. It writes history; it doesn't replay it. A dry run comes first.
Be honest with yourself about the risk: the importers are tested against stand-ins that follow each vendor's documented API, not against real vendor accounts yet. Try them on a test brand first.

I made a short video of this on X. Everything in it is the real app running locally with demo data, a local demo identity provider and the vendor stand-ins.

Helpdock 0.6.0: switch help desks, keep every ticket

Single sign-on for staff

SSO in Helpdock is for staff. Customers using the chat widget and help center keep their own sign-in. An install admin adds connections under Settings › Single sign-on:

OIDC: authorization code flow with PKCE (S256), a confidential client secret, signed ID tokens and single-use state.
SAML 2.0: signed assertions only, with replay protection, and stable NameIDs.
Email domains: each connection lists exact domains, and one domain belongs to at most one enabled connection. That is what makes email-first sign-in work: a person types [email protected] and Helpdock sends them to Acme's provider.
Certificate rotation: a metadata refresh can drop a certificate the provider no longer lists, but never adds one. A new signing certificate is trusted only after an admin saves it.
Sessions: SSO sessions are capped at 12 hours, even if your normal session limit is longer.

The real sign-in screen with SSO required: the email domain finds the identity provider

Groups become roles

Each connection maps IdP groups to brand roles. The first matching row for each brand wins, and Agents get an explicit list of departments:

acme-admins → Acme Cloud · Admin
acme-support → Acme Cloud · Agent, in Billing, Sales and Technical Support

With Create accounts on first sign-in, an unknown person in an allowed domain gets an account the first time they sign in, with the roles their groups grant. On every sign-in, Helpdock adds, updates and removes only the roles that connection owns. If someone leaves souq-admins in the IdP, their Souq admin role is gone at their next sign-in. A role an admin gave by hand stays, and SSO never grants install-admin access.

One thing I learned while filming: our demo agent Omar already had a hand-assigned Agent role in Acme from older demo data, so his new acme-admins group did not make him an admin. That is the rule working as designed. Remove the manual grant once, and the next sign-in hands the role to SSO.

Illustration: IdP groups become brand roles, a removed group drops its role, a manual role stays

Enforce SSO, keep a way in

Enforce SSO turns off password, magic-link and Google/GitHub sign-in at the next sign-in for everyone except one to three break-glass install admins. Those admins need a password and TOTP, and recovery codes or trusted browsers can't bypass it. Before you enforce:

Save and enable the connection, then use Test connection. It previews the claims, the matched or new account and the roles without creating anything.
Sign in once with a real test person and check their roles.
Check that each break-glass admin can still sign in with password and a fresh TOTP code.

The real Single sign-on settings: group-to-role mappings and a passing Test connection

Two limits worth knowing: there is no SCIM provisioning and no single logout yet. Removing someone in the IdP blocks their next sign-in but does not end an open Helpdock session, so deactivate the person in Helpdock when you need it to be immediate.

Importers: bring your history with you

Helpdock 0.6.0 reads Zendesk, Freshdesk and Zoho Desk through their APIs. Any other tool works through CSV/TSV files or a Helpdock bundle (zip) with a manual column mapper. Help Scout, Intercom, Gorgias, Zammad and Front are already listed in the wizard as coming next.

Illustration: tickets move in while emails, rules, SLA timers, notifications, webhooks and AI calls stay at zero

What comes across: tickets with full threads, public replies and private notes with their original authors and dates, contacts, companies, staff, groups as departments, tags, custom fields, CSAT, attachments, and help-center articles in both languages.

What doesn't happen: no emails, no automation rules, no SLA timers, no notifications, no webhooks, no AI calls. SLA clocks on imported open tickets start only when an admin turns them on.

The wizard, step by step

Source and connection. For Zendesk I used an OAuth access token with read access. Credentials are encrypted on the server and deleted when the run ends. Attachment download hosts are an explicit allow-list of exact hostnames.
Scope. Pick the records to bring. Tick Rebuild reports for all imported history if your history is older than the default report window.
Extract. Helpdock reads the source. Nothing is written to your desk yet.
Map. Statuses, priorities, channels, groups to departments, agents, fields and tags. An agent can map to an existing person, an invited person (no email is sent) or a name only. CSV column mappings can be saved as presets.
Dry run. Real counts and previews of tickets, contacts and files. Blocking errors must be fixed, and warnings must be acknowledged. One of those warnings lists the closed tickets your retention policy would delete. Start stays disabled until the report is clean.
Import. Counts climb, and you can pause, resume or cancel. Runs survive worker restarts without losing or duplicating records.

The real dry run: the retention warning must be acknowledged before Start unlocks

In my demo run against the Zendesk stand-in: 500 tickets, 2,000 messages and notes, 50 contacts, 10 organizations, 500 attachments, 500 satisfaction ratings and 40 articles.

The real import run: 500 tickets, 2,000 messages, every file

Faithful history

Tickets get new Helpdock numbers. The original number is shown on the ticket ("Imported from Zendesk · #580") and is searchable. Search from All tickets, since every view keeps its own filters.
Original dates are kept, so Reports show imported volume, first response, resolution and CSAT on the days they happened.
A new Source filter selects imported or native tickets, and you can save it in a view.
Attachments are copied into your own S3-compatible storage, so nothing depends on the old vendor's expiring links.

The real imported ticket: new ACME number, original #580, original authors and dates

How I'd plan a cutover

cutover-checklist.txt

1. Back up the Helpdock database, the object bucket and your config. Verify a restore.
2. Create the import in a TEST brand first. Use read-only vendor credentials.
3. Map departments, staff, statuses, priorities, fields and tags.
4. Dry run. Read every warning, especially retention. Compare counts with the source.
5. Run the import. Spot-check threads, private notes, authors, dates and files.
6. Repeat in the real brand. Running the same import again changes nothing.
7. Final cutover: keep the old desk quiet, run a delta sync for what changed.
8. Switch email, Telegram and Meta channels to Helpdock. Rebuild macros, rules and SLAs by hand.
9. Start SLA timers on imported open tickets only when you're ready.

Vendor limits to plan around:

Freshdesk: accounts with more than 30,000 tickets need a ticket ID export (the "complete inventory" mode), because Freshdesk's list stops at 300 pages per window.
Zoho Desk: each delta reads every ticket, so plan it within your daily API credit allowance.

Upgrading to 0.6.0

Back up first. This release adds database migrations, and on large installs the first boot can take a few minutes while they run.
Importers vs. real vendors: tested against documented-API stand-ins, not real vendor accounts yet. Please try it on a test brand and report anything unexpected.
Fixed: the ticket's SLA card no longer loses its policy when a reply or note arrives live.

Next up: connectors for Help Scout, Intercom, Gorgias, Zammad and Front, then 1.0. Helpdock is open source under AGPL-3.0; if it's useful to you, a star on GitHub helps.

Helpdock 0.6.0: Single Sign-On and Ticket Imports from Zendesk, Freshdesk and Zoho Desk

Executive Summary