Set up single sign-on

One less password for your team. Connect any OpenID Connect provider — Okta, Entra ID, Auth0, Keycloak — and let admins and members sign in with their existing work accounts. Verify your domains and you can require SSO so company emails can only sign in through your IdP.

This page covers team SSO — sign-in for admins and members managing feedback. To let portal users (customers) sign in with a custom OIDC provider, see Portal Authentication.

What you get

Connection — link your OIDC provider once.
Test sign-in — a real end-to-end handshake that proves the connection works before you turn anything on.
Verified domains — prove you own a domain so its emails route to SSO.
Require SSO — hard-bind a verified domain so its users can only sign in through your IdP.
Recovery codes — break-glass sign-in for when your IdP is unreachable.
Attribute mapping — assign Quackback roles from a claim on the IdP token.

Everything lives under Admin → Settings → Security, on the Single sign-on page.

Step 1: Register Quackback in your IdP

Create an OIDC application in your identity provider:

Field	Value
Application type	Web application
Redirect URI	`https://YOUR_DOMAIN/api/auth/oauth2/callback/sso`
Scopes	`openid email profile`

Note the Client ID and Client Secret, and your provider's discovery URL (the /.well-known/openid-configuration endpoint).

The redirect URI must match exactly — including https, no trailing slash, and the oauth2/callback/sso path. A mismatch is the most common cause of a failed test sign-in.

Step 2: Add the connection

Go to Admin → Settings → Security → Single sign-on.
Enter the Discovery URL, Client ID, and Client Secret.
Save.

The client secret is encrypted at rest. Changing the discovery URL, client ID, or secret invalidates any previous test sign-in — you'll need to test again before enabling.

Before you can enable SSO or enforce it on a domain, Quackback makes you prove the connection works.

Click Test sign-in on the SSO page.
A popup opens your IdP. Sign in.
Quackback runs the full OIDC handshake — discovery, token exchange, signature verification, claim checks — and reports exactly which step failed if any.

The test runs in an isolated session and never creates a real login. Run it as often as you need while configuring your IdP.

A passing test unlocks the Enabled toggle and the per-domain Require SSO switches.

Step 4: Enable SSO

Toggle Enabled on. The SSO sign-in option now appears on the team sign-in page. At this point SSO is available — it doesn't replace other methods yet.

Verify your domains

A verified domain tells Quackback that you own an email domain, so emails at that domain route to SSO by default.

On the SSO page, under Verified domains, add a domain (for example acme.com).
Quackback shows a DNS TXT record to publish:

Name Value
_quackback-verify.acme.com qb-domain-verify=<token>
Add the record at your DNS registrar, wait for it to propagate, then click Verify.

You can verify up to 10 domains. Once verified, *@acme.com users see "Continue with SSO" as the default option on sign-in.

Verifying a domain only changes the default sign-in route. Other methods still work until you turn on Require SSO.

Require SSO for a domain

Turn on the Require SSO switch next to a verified domain to hard-bind it: *@acme.com emails can then only sign in through your IdP. Password, magic link, and other OAuth providers are refused for those addresses.

Enabling enforcement has two preconditions:

A passing test sign-in since the last connection change.
Email delivery configured — magic link is the break-glass path for the rest of the workspace.

A confirmation dialog spells out the impact before you commit. Enforcement takes effect immediately.

If your IdP goes down, an enforced domain's users can't sign in normally. Recover with a recovery code, or with an admin whose email is at a non-enforced domain.

Enforcement fails open: if SSO stops being viable at runtime - the client secret is removed, or the connection is disabled - Quackback suspends enforcement so the team isn't locked out. Re-enable it once SSO is healthy again.

When a user at a verified domain tries to sign in but SSO isn't actually live (the connection is off, the secret is missing, or the feature isn't on your plan), they see: "Single sign-on is configured for your domain but is not currently available. Contact your administrator." This shows up instead of a broken redirect so the user knows to reach out rather than retry blindly.

Recovery codes

Recovery codes are single-use passcodes that get an admin in when SSO is unavailable.

On the SSO page, under Recovery codes, click Generate new codes.
Quackback shows 10 codes once. Copy, download, or print them and store them somewhere safe.
Generating a new batch invalidates the previous one.

To use a code, go to /auth/recovery, enter your email and a code. Each code works once. Quackback warns you when fewer than three codes remain.

Generate recovery codes before you turn on Require SSO — running out during a broken-SSO incident is the worst possible time to discover you have none.

Auto-provision users

By default, the first time someone signs in through SSO with an email at a verified domain, Quackback creates their account automatically (just-in-time provisioning) with the member role.

You can change the default role, or turn auto-provisioning off entirely, in the SSO connection settings. With it off, a user must already exist in Quackback before they can sign in through SSO.

The very first SSO sign-in into a workspace that has no admin is promoted to admin. This is a recovery path for a workspace that lost its last admin — a healthy workspace already has one, so it never triggers.

Map roles from IdP claims

Instead of giving every provisioned user the same role, you can source their role from a claim on the IdP's ID token.

Under Attribute mapping on the SSO page:

Turn on Attribute mapping.
Set the Claim path — a dotted path (realm_access.roles) or a URL-shaped claim (https://acme.com/roles). Copy it from your IdP's docs.
Add rules — first-match-wins. Each rule maps a value the claim contains to a role, for example platform-admins → admin.
Set a Default role for users no rule matches.
Optionally turn on Sync on every sign-in to re-apply the role on each login. This demotes a team member if their IdP group changes.

Role changes from mapping are written to the audit log.

Provider examples

Okta

Field	Value
Discovery URL	`https://your-org.okta.com/.well-known/openid-configuration`
Redirect URI	`https://YOUR_DOMAIN/api/auth/oauth2/callback/sso`

Microsoft Entra ID

Field	Value
Discovery URL	`https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`
Redirect URI	`https://YOUR_DOMAIN/api/auth/oauth2/callback/sso`

Auth0

Field	Value
Discovery URL	`https://your-tenant.auth0.com/.well-known/openid-configuration`
Redirect URI	`https://YOUR_DOMAIN/api/auth/oauth2/callback/sso`

Keycloak

Field	Value
Discovery URL	`https://keycloak.example.com/realms/<realm>/.well-known/openid-configuration`
Redirect URI	`https://YOUR_DOMAIN/api/auth/oauth2/callback/sso`

How it works

A user clicks Continue with SSO (or is auto-redirected if their email is at a verified domain).
Quackback redirects to your IdP's authorization endpoint.
The user authenticates with their existing work credentials.
The IdP redirects back with an authorization code.
Quackback exchanges the code, verifies the ID token signature, and reads the email claim.
If the account exists it's linked; otherwise it's provisioned per your settings.

Quackback requires an email claim from your IdP. If your provider doesn't release it by default, add it to the application's claim mapping.

Configure team security — 2FA, audit log, and sign-in methods
Authentication overview — all sign-in options
Declarative config — manage the SSO connection from a config file