What you need before you start
You need to be an admin of the Flatdesk team, to manage DNS for your company email domain, and to be able to create an app in your identity provider. Everything is under Settings, Single sign-on.
Use OIDC if your provider offers it. It has fewer fields and fewer ways to go wrong. Use SAML when the provider only speaks SAML or your security team asks for it.
Step 1: verify your email domain
Add your company domain, for example acme.com. Flatdesk shows a TXT record to publish at _flatdesk-verify.acme.com. Once DNS has updated, press Check record.
Only addresses on a verified domain can sign in through your provider, and a domain can be verified by one team at a time. Public mail services such as gmail.com can't be added.
Step 2: connect your provider with OIDC
In your provider, create a web application, give it the redirect URI shown in Flatdesk, and copy the client ID and client secret back. The issuer URL differs by provider:
- Okta: Applications, Create App Integration, OIDC, Web Application. Sign-in redirect URI is the one Flatdesk shows. Issuer is your Okta address, like https://acme.okta.com. Assign the people or groups who should have access.
- Google Workspace: in Google Cloud Console, APIs and Services, create an OAuth client of type Web application, with Flatdesk's redirect URI. Set the consent screen to Internal so only your organisation can use it. Issuer is https://accounts.google.com.
- Microsoft Entra ID (Azure AD): App registrations, New registration, platform Web with Flatdesk's redirect URI. Under Certificates and secrets create a client secret and copy its Value, not its ID. Under Token configuration add the optional email claim to the ID token. Issuer is https://login.microsoftonline.com/<your tenant ID>/v2.0.
Or connect with SAML
Create a SAML application in your provider and give it the ACS URL and entity ID (audience) that Flatdesk shows after you save the SAML tab. Set the Name ID to the user's email address, or send an attribute called email. firstName and lastName attributes fill in the name.
- Copy three things back into Flatdesk: the provider's entity ID (issuer), its sign-on URL and its signing certificate.
- Flatdesk requires a signed assertion. Sign-in always starts from Flatdesk, so turn off any IdP-initiated sign-in option or leave it unused.
- Certificates expire. When yours is renewed, paste the new one and test again.
Step 3: test, then turn it on
Press Test sign-in. You go to your provider with your own email and come back to Settings. Nothing changes for anyone else yet. After a successful test, tick Single sign-on is on.
From then on, people enter their work email at /sso, or choose Sign in with SSO on the sign-in page, and are sent to your provider. The first time someone from a verified domain signs in, Flatdesk adds them as an agent if Add new people automatically is on. Each agent is a seat, so turn it off if you would rather invite people yourself.
Step 4: require it (optional)
Requiring single sign-on sends everyone on your verified domains to your provider, whatever other way they signed in. It can only be switched on after you have signed in through the provider yourself.
Keep one admin whose email is not on your verified domains, for example a company mailbox on another domain, so you can still open Flatdesk and switch the setting off if your provider has an outage. Signing in through the provider lasts 12 hours before people are sent back to it.
Step 5: add and remove people from your provider (optional)
Without SCIM, people are added when they first sign in and removed by you in Settings. With SCIM, your provider does both. In Settings, Single sign-on, section 5, make a SCIM token and copy it; it is shown once. Making a new one replaces the old.
In Okta, open the app's Provisioning tab, choose SCIM, and enter the base URL shown in Settings, with unique identifier field userName and HTTP header authentication using the token. Turn on Create Users, Update User Attributes and Deactivate Users. In Entra ID, open Provisioning, set it to Automatic, and enter the base URL as the tenant URL and the token as the secret token.
People assigned to the app are added as agents on their work email, and each is a seat. Unassigning or deactivating someone removes them from the team; their name stays on old tickets. Only addresses on a verified domain are added. The provider never removes an admin, and groups and roles are not synced, so everyone it adds is an agent.
If something goes wrong
Most problems show as a message on the sign-in page. These are the common ones.
- “Isn't on a domain this team has verified”: the provider sent an address on a domain you haven't verified. Verify it, or fix the email the provider sends.
- “Didn't send an email address”: allow the email scope (OIDC) or map the user's email to Name ID or an email attribute (SAML).
- “Response didn't check out” (SAML): the certificate, entity ID or audience doesn't match. Compare each with what your provider shows.
- “Expired or opened in a different browser”: start again from Flatdesk in a single browser window. Cookies must be allowed.
- To remove someone, remove them from your provider's app and from Settings, Team. Removing them from the provider stops new single sign-on logins, but a Flatdesk session they already have stays open until it expires, so remove them in Settings too.