SAML single sign-on

Connect your identity provider over SAML so your organization signs in to Dashies with the accounts it already has.

Dashies supports SAML 2.0 against any standard identity provider, including Okta, Microsoft Entra ID, and Google Workspace. Both service-provider-initiated and identity-provider-initiated sign-in work.

Prerequisites: you are an admin of the workspace, the workspace is on Enterprise, and its email domain is already verified.

Verify the domain first, not afterwards

Dashies will let you connect SAML on an unverified domain and will report success. Every sign-in attempt then fails with "No SSO is configured for that domain", and nothing in the admin screen indicates why.

There is also no self-serve way to disconnect SSO afterwards, and connecting it permanently blocks releasing the domain and deleting the workspace. Get the domain verified before you do anything on this page.

1. Create the application in your identity provider

Create a SAML 2.0 application in your IdP as you would for any other service.

Dashies does not show you the ACS URL or entity ID

Your IdP needs Dashies' assertion consumer service URL and entity ID (also called audience) to create the application, and the Dashies app does not display them today. There is no metadata download and no copyable SP details panel.

Ask support for the exact values for your workspace before you start, rather than guessing them. A guessed ACS URL produces a SAML response that never reaches us, which looks identical to a misconfigured IdP.

Configure the application to assert the user's email address, and make sure it is asserted as verified. Dashies rejects an assertion whose email_verified claim is explicitly false.

Every email your IdP asserts must end with the workspace's verified domain. Assertions for any other domain are rejected, by design: see the domain bind.

2. Connect it in Dashies

Open Settings, switch into the workspace, open its Security section, and choose Configure SSO.

There is exactly one field:

Field	Value
IdP metadata URL	The HTTPS URL of your IdP's SAML metadata XML. Most providers give you this directly.

The hint under the field is the product's own summary: "HTTPS URL of your IdP's SAML metadata XML. Most IdPs (Okta, Azure AD, Google Workspace) provide this directly."

The URL must start with https://. An http:// URL is refused with metadataUrl must be https://.

Click Connect SSO. On success you get a green confirmation naming the tenant, which is your workspace slug:

Connected. Polis tenant: acme-analytics.

If your metadata URL is unreachable, the failure comes back with your IdP's own wording quoted after "Polis rejected the connection", most commonly:

Couldn't fetch XML data

That is a URL problem, not a Dashies problem. Open the metadata URL in a browser to confirm it returns XML without a login.

If you are told to retry, retry

One failure mode is explicitly recoverable, and the app says so:

The IdP connection was registered, but the workspace record was not updated. Click "Connect SSO" again to finish - safe to retry.

Clicking again is the correct response. It will not create a duplicate.

What your users do

They go to the Dashies sign-in page and click Sign in with SSO, having typed their work email into the email field above it. There is no workspace slug to remember and no separate SSO URL to bookmark: the domain of the email address is what selects the workspace.

If your IdP has an app launcher or dashboard, that works too, with no extra configuration in Dashies.

Three behaviours worth telling your users about:

The first SSO sign-in joins them to the workspace automatically, as a member. Someone who is already an admin keeps admin: signing in never demotes anyone.
They land on the Dashies home page, not on whatever link they clicked. A deep link into a specific dashboard is not preserved through the SSO round trip today, so tell people to sign in first and then follow the link.
Google sign-in and password sign-in keep working. Connecting SAML adds a route in; it does not close the others.

Troubleshooting

"No SSO is configured for that domain - use Google or a password." The domain of the email address has no verified SSO workspace. Either the domain is not verified, or the user typed a personal address. This is the message the verification trap produces, so check domain verification first.

"Could not start the SSO sign-in. Try again or use another method." or "Network error reaching the SSO bridge." The request to start sign-in did not complete. Retry.

The user is bounced back to a clean sign-in page with no message at all. This is the signature of a failure after your IdP responded, and it is the one that looks like nothing happened. The reason is in the URL bar as an error parameter. Ask the user to copy the whole URL. The useful values:

`error=`	Cause
`email_domain_mismatch`	The IdP asserted an address outside the workspace's verified domain.
`email_not_verified`	The assertion said the address is explicitly unverified.
`no_email_claim`	The IdP did not assert an email address at all. Fix the attribute mapping.
`unknown_workspace`	The workspace could not be resolved, most often because the domain is no longer verified.
`id_token_invalid`	The assertion did not verify. Re-check the metadata URL, and reconnect if your IdP has rotated its signing certificate.

Check it worked

The section shows it as configured. Reload the workspace's Security section. The heading area should show a "Configured" pill naming your workspace slug.
A real user signs in. Ask a colleague on the verified domain, who is not already a Dashies user, to sign out, enter their work email, and click Sign in with SSO. They should reach your IdP and come back signed in. Your own account proves less, because you already have a session and a membership.
They landed in the workspace. Open the workspace's Members section. The person who just signed in should be listed as a member. If they signed in but are not listed, the sign-in worked and the auto-join did not.
The identity provider launcher works. From your IdP's app launcher, click the Dashies app. It should sign you in without going through the Dashies sign-in page at all.