Single sign-on
Let your people sign in to Flitch with your own identity provider.
Single sign-on sends anyone with an email address at your domain to your own identity provider to sign in. You control who has access, from the same place you control everything else.
Available on the Business plan. See Billing.
Before you start
You will need:
| A business on Flitch | Single sign-on belongs to the business, not to a single team. It covers every team the business owns. |
| The owner or admin role | On the business itself. A team admin who is only a business member cannot configure it. |
| Control of your DNS | You prove you own the email domain with a TXT record before anything goes live. |
Two things worth knowing up front. Flitch supports one identity provider per business, matched on one email domain. And nothing routes through your provider until the domain is verified, so this is safe to set up in advance and finish later.
Open Settings → Business → Single sign-on.
Pick a protocol
Flitch supports both. Choose OIDC unless something forces your hand: it is fewer moving parts, and there are no certificates to rotate. Microsoft Entra, Okta and Google all speak it.
Choose SAML if your identity provider offers nothing else, or your security team requires it.
Copy your service provider details
Your identity provider needs to know where to send people. Flitch shows these on the single sign-on page before you fill anything in, because you need them to create the application at your provider, which happens first.
Which values you need depends on the protocol you picked. The page follows your choice.
OIDC needs one:
Redirect URI
https://app.flitch.io/api/auth/sso/callback/business_<your-business-id>SAML needs two:
Single sign-on URL (ACS)
https://app.flitch.io/api/auth/sso/saml2/sp/acs/business_<your-business-id>
Audience URI (entity ID)
https://app.flitch.io/api/auth/sso/saml2/sp/business_<your-business-id>Copy the ones you need now. Every step below asks for them.
Create the application
New registration
In the Microsoft Entra admin centre, go to Applications → App registrations → New registration.
Name it whatever your people will recognise on a consent screen. Flitch is a reasonable choice.
Supported account types
Choose Accounts in this organizational directory only. Your people sign in, nobody else.
Redirect URI
Set the platform to Web and paste the redirect URI you copied.
Click Register.
Copy the IDs
On the Overview page, copy the Application (client) ID and the Directory (tenant) ID.
Create a client secret
Go to Certificates & secrets → Client secrets → New client secret. Set an expiry you will remember.
Copy the Value column, not the Secret ID. The value is shown once and never again; the Secret ID is not a secret and will not work.
Build the issuer URL
Take the tenant ID and put it here:
https://login.microsoftonline.com/<tenant-id>/v2.0Your people may see an unverified publisher warning
This is Microsoft's, and it refers to your own app registration rather than to Flitch. Granting tenant-wide admin consent on the application stops it appearing. It does not block sign-in.
New app integration
In the Okta Admin Console, go to Applications → Applications → Create App Integration.
Choose OIDC - OpenID Connect, then Web Application.
Redirect URI
Paste the redirect URI you copied into Sign-in redirect URIs.
Assignments
Choose who gets the app. Anyone not assigned here cannot sign in to Flitch through single sign-on.
Save.
Copy the credentials
From the application's General tab, copy the Client ID and the Client secret.
Find your issuer
Under Security → API, open the authorization server you want to use and copy its Issuer URI. For the org authorization server this is your Okta domain; for a custom one it ends in /oauth2/<id>.
Take it from the Issuer URI column, not from your browser's address bar. The Admin Console runs on a different hostname, with -admin in it, and that hostname is never the issuer.
Check the access policy
If you chose a custom authorization server, including the one named default, it will refuse the request unless a policy matches your app.
Open the authorization server's Access Policies tab. If there is no policy, add one assigned to All clients, then add a rule allowing the Authorization Code grant for any user assigned the app.
Policy evaluation failed for this request
This is the most common Okta setup error, and it comes from Okta rather than Flitch. It means the custom authorization server has no access policy matching the app. Add one as above. The org authorization server has no policies and never produces this.
New app integration
Applications → Applications → Create App Integration, then SAML 2.0. Give it a name and continue.
Configure SAML
| Okta field | Value |
|---|---|
| Single sign-on URL | Your ACS URL |
| Audience URI (SP Entity ID) | Your audience URI |
| Name ID format | EmailAddress |
| Application username | Email |
Leave Attribute Statements empty. Flitch reads the email from the Name ID, so with the format set to EmailAddress there is nothing more to map. Adding an attribute is not wrong, just unnecessary.
Copy the identity provider details
On the app's Sign On tab, open View SAML setup instructions. That page carries the three values Flitch asks for: the Identity Provider Single Sign-On URL, the Identity Provider Issuer, and the X.509 Certificate.
Assign people
Open the Assignments tab and assign yourself, a group, or everyone.
Unlike the OIDC wizard, the SAML one never offers this during setup, so a brand new SAML app has nobody assigned and every sign-in is refused.
User is not assigned to this application
Okta's, not ours, and it means exactly what it says. Each app integration has its own assignment list, so assigning people to an OIDC app does nothing for a SAML one. Add them on the Assignments tab.
Add it to Flitch
Back on Settings → Business → Single sign-on, fill in:
Two fields are common to both protocols:
| Field | What goes in it |
|---|---|
| Protocol | Whichever you picked |
| Email domain | The domain your people's email addresses end in, like acme.com. Not a full address. |
| Issuer | The issuer from your provider. For SAML this is the Identity Provider Issuer. |
Then, for OIDC:
| Field | What goes in it |
|---|---|
| Client ID | From your provider. |
| Client secret | The secret value, not its ID. Stored encrypted. |
| Discovery URL | Optional. Leave it blank and Flitch derives it from the issuer, which is right for both Entra and Okta. |
Or for SAML:
| Field | What goes in it |
|---|---|
| Sign-on URL | The Identity Provider Single Sign-On URL. |
| Signing certificate | The X.509 certificate, PEM including its header and footer. Stored encrypted. |
Click Register. Nothing is live yet.
Verify your domain
Registering a provider is a claim that you own the domain. Until that claim is proven, no one is routed through it. This stops anyone registering a provider for a domain that is not theirs and capturing its sign-ins.
Flitch shows you a record name and a value. Add them to your DNS as a TXT record:
| Type | TXT |
| Name | _flitch-sso-business_<your-business-id> |
| Value | The token shown on the page |
Then click Check DNS. Propagation is usually minutes and occasionally longer. If it fails, wait and try again before changing anything: the most common cause is checking too early.
Once it passes, single sign-on is live.
How your people sign in
Two routes, and you can use both.
From the sign-in page. Under the provider buttons there is a Use SSO link. It asks for a work email address, matches the domain to your provider, and hands off. Nobody has to know which provider you bought.
From a link you give them. Once your domain is verified, the single sign-on page shows a direct link:
https://app.flitch.io/sign-in?sso=acme.comThat goes straight to your provider with nothing to type and no buttons to choose between. Put it on your intranet, or behind the Flitch tile in your identity provider, and your people never see the sign-in page at all.
People need a Flitch account first
Single sign-on authenticates people; it does not create them. Someone at your domain who has never been added to a team will be turned away with a message telling them to ask an admin for an invitation. Add people from Settings → Business or from the team they belong in.
Rotating the credential
Client secrets expire and signing certificates roll. When either lapses, single sign-on stops for everyone at once, so replace them before the old one dies rather than after.
On the single sign-on page, the live provider has a Client secret or Signing certificate card. Choose Replace, paste the new value, and save. Your domain stays verified, so there is no DNS record to touch.
OIDC is a straight swap. Nobody notices.
SAML is not, and the page will tell you so. The signing certificate is what decides which assertions Flitch trusts, so changing it changes the trust itself, and existing sign-ins have to be re-established. You will be asked to confirm, with a count.
Re-establishing is not a reset. Nobody loses their account, their teams, their dashboards or their session, and nobody has to be re-invited. The link between each person and your provider is rebuilt automatically the next time they sign in, because your domain is verified and their email matches it. In practice they notice nothing.
Rotating to a certificate identical to the current one changes no trust, so it skips the confirmation entirely. That makes it a safe way to check the flow.
Multi-factor authentication
Flitch does not run its own second factor, and does not store passwords at all. Authentication is delegated to your identity provider, so your MFA policy, conditional access rules, device compliance requirements and session lifetimes apply to Flitch exactly as they apply to everything else you have behind that provider.
There is nothing to configure here. If your provider requires a second factor, your people will be asked for one on the way through.
Troubleshooting
| What you see | What it means |
|---|---|
| Domain verification keeps failing | Usually DNS that has not propagated. Confirm the record resolves with dig TXT _flitch-sso-business_<id>.acme.com before raising it. |
| You need an invitation first | The account does not exist in Flitch yet. Authentication worked; there is nobody to sign in as. Invite them first. |
| Sign-in interrupted | The provider configuration changed while someone was mid-login. Try again. |
| Couldn't read your profile | Your provider signed the person in but returned no email address. Check the email claim is included in the token. |
| Okta: Policy evaluation failed for this request | The custom authorization server has no access policy matching the app. Add one on its Access Policies tab, assigned to all clients, with a rule allowing the Authorization Code grant. |
| Okta: the sign-in never reaches Flitch | Check the issuer does not contain -admin. That is the Admin Console hostname, not your org's issuer. |
| Okta: User is not assigned to this application | Each app integration has its own assignment list. Assigning people to one does nothing for another. Add them on the app's Assignments tab. |
| SAML: sign-in worked, then stopped for everyone | The identity provider rotated its signing certificate. Replace it under Signing certificate. |
| SAML: Unable to extract user ID or email | The assertion carried no email. Set the Name ID format to EmailAddress, or map an email attribute. |
| An error mentioning an untrusted origin | Your provider's discovery document points at a host Flitch does not yet allow. Tell us the issuer URL and we will add it. |
| Sign-in worked yesterday, fails today | Check whether the client secret expired. Entra secrets have a fixed lifetime and are not renewed automatically. |
Turn it off
On the single sign-on page, choose Remove provider. Your people stop being routed to your identity provider immediately and can sign in with Google or Microsoft again.
No accounts, teams, dashboards or data are affected. Removing the provider removes a route in, not anything it led to.