Enterprise SSO

Enterprise SSO lets people on your team sign in to dFlow with your company identity provider (IdP) instead of an email + password. dFlow supports both OIDC and SAML 2.0.

When SSO is configured for a domain (for example acme.com), anyone who types an acme.com email on the dFlow sign-in screen is sent to your IdP. After they authenticate there, they land back in dFlow already signed in.

Before you begin

You need:

• An admin role in dFlow (your role must include the SSO permissions).

• Admin access in your IdP (Microsoft Entra, Okta, Auth0, Google Workspace, Keycloak, or any OIDC/SAML 2.0 provider) so you can register a new application and copy a client ID and secret.

• The email domain(s) your team signs in with (for example acme.com, acme.co).

Where to manage SSO

1. Open the dashboard.

2. Click your avatar → Account → Single Sign-On (or visit /account/sso).

3. Use Add OIDC or Add SAML to register a provider.

The page lists every provider you've added, what email domain each one covers, and a Trusted origins list (rarely needs manual entries — see the bottom of this page).

How the redirect URI works

Every provider you add gets a redirect URI (sometimes called callback URL or reply URL) that your IdP must accept. dFlow's URI is always:

{your-dflow-url}/api/auth/sso/callback/<provider-id>

The <provider-id> is the value you choose in the Provider ID field. The Add OIDC / Add SAML dialog shows the full URI live as you type — copy it, then register that exact string at your IdP.

A few rules that catch people:

• Exact-match. Case, port number, and trailing slashes all have to match. The IdP will reject anything off by even a slash.

• One IdP app, multiple URIs. If you sign in to dFlow from more than one place — local development, staging, production — register each environment's redirect URI inside the same IdP app, don't replace.

• http://localhost is OK for development; every other host should be https://.

• Don't change Provider ID later. It's the URI suffix; changing it would invalidate the URI you registered at the IdP. The dialog disables this field after creation.

Walkthrough — Microsoft Entra ID (Azure AD)

A complete OIDC setup for Microsoft Entra. Same shape works for any other OIDC IdP — only the Issuer URL changes (see the table at the bottom).

1. Register an application in Microsoft Entra

1. Open the Microsoft Entra admin center.

2. Go to Microsoft Entra ID → App registrations → + New registration.

3. Fill in:

   	FieldValue
   Name	Anything (display only). For example dFlow SSO.
   Supported account types	Single tenant for your own organisation. Choose multi-tenant only if any Entra organisation should be able to sign in.
   Redirect URI	Type Web. Value: {your-dflow-url}/api/auth/sso/callback/<provider-id> — use the same <provider-id> you'll type in the dFlow form (for example acme-entra).

4. Click Register.

After registration, on the application's Overview page copy:

• Application (client) ID — goes into dFlow's Client ID.

• Directory (tenant) ID — goes into the dFlow Issuer URL (next step).

2. Create a client secret

1. In the same app, open Certificates & secrets → + New client secret.

2. Pick a description and expiry, then click Add.

3. Immediately copy the Value column for the new secret. Microsoft hashes it after the first view — if you miss it, delete and create a new one.

4. The Secret ID column is not the secret. Only the Value is.

This goes into dFlow's Client secret.

3. Confirm permissions and token settings

• API permissions — by default Microsoft adds Microsoft Graph → User.Read (delegated), which is enough for dFlow (it provides openid, profile, and email). For organisation-wide access without per-user consent, click Grant admin consent for <your tenant>.

• Authentication → Implicit grant and hybrid flows — leave both Access tokens and ID tokens unchecked. dFlow uses the modern authorisation-code flow with PKCE.

4. Add the provider in dFlow

In Account → Single Sign-On → Add OIDC:

Save.

5. Test it

1. Sign out of dFlow.

2. On the sign-in page, type an email on one of the domains you registered.

3. Click Continue (or Sign in with SSO). You should be sent to Microsoft's sign-in page.

4. After completing Microsoft sign-in you'll land back in dFlow, signed in.

If the IdP returns an error, see Troubleshooting below.

Quick reference for other IdPs

The shape is the same for every OIDC provider — only the Issuer URL changes.

For SAML providers, use Add SAML instead. The dialog asks for the Entry point / SSO URL, the IdP certificate (PEM), and optional metadata XML — all values your IdP gives you on the SAML application page.

Trusted origins

The Trusted origins card on the SSO page lists hostnames dFlow allows OIDC discovery and callback traffic from. The origin of every saved provider's Issuer URL is added automatically. You only need to add an entry here if your IdP serves authentication and discovery from different hosts — for example, an Okta custom authorisation server hosted on a separate domain.

Troubleshooting

"No SSO provider for that domain"

The email you typed doesn't match any Email domains entry on a saved provider. Open the provider in Account → Single Sign-On → Edit and add the missing domain.

IdP rejects the redirect URI

Microsoft Entra and most IdPs show the URI they received and the URI they have on file in the error message. Compare them character-by-character — case, port, and trailing slash all matter. Make sure the Provider ID in dFlow matches the suffix you registered at the IdP.

Microsoft Entra: sign-in finishes but dFlow says "missing email"

Some Entra tenants return the email as preferred_username instead of email. Today the OIDC dialog uses the standard email claim. To work around this, contact your dFlow operator — they can register the provider with a custom claim mapping using the server-side admin API. (A claim-mapping field is on the roadmap for the dialog.)

Microsoft Entra: I'm using the wrong tenant

A single-tenant Entra app must use your tenant's GUID (or a verified domain) in the issuer URL. The convenience value https://login.microsoftonline.com/common/v2.0 only works for multi-tenant apps and personal Microsoft accounts.

People on *.onmicrosoft.com can't sign in

Entra users have two addresses: their work email (for example you@acme.com) and the default you@acme.onmicrosoft.com. Whatever they actually type at the dFlow sign-in screen is what gets matched. Add both domains to the Email domains field if your team uses both.

I rotated the client secret and now nothing works

Microsoft client secrets only display the Value at creation. If you can't see it, delete the secret in Certificates & secrets and create a new one. Paste the new value into the dFlow provider via Edit → Client secret → save.

Multiple environments stopped working after I changed the redirect URI

Each environment (local, staging, production) is its own redirect URI. Add them to the same IdP app — don't replace. If you removed one, re-add it from the dFlow dialog's live URI preview.

Related

• Roles and permissions — which roles can manage SSO.

• Invites and team members — for users who don't sign in through SSO.

• Tenant access model — how Organisations and identities fit together.

• Security best practices.