Set up single sign-on

Let your team sign in with their existing work accounts. Connect any OpenID Connect (OIDC) identity provider, such as Okta, Microsoft Entra ID, Auth0, or Keycloak, verify your email domains, and optionally require SSO so company emails can only sign in through your provider.

Note: This article covers team SSO: sign-in for team members. To give portal users (customers) a custom OIDC sign-in button, see Control portal access and sign-in. On Quackback Cloud, SSO is available on the Enterprise plan.

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 are routed to SSO.
• Require SSO: bind a verified domain so its users can only sign in through your provider.
• Recovery codes: break-glass sign-in for when your provider is unreachable.
• Account options: create accounts on first sign-in, choose the role new accounts get, or map roles from a claim on the provider's token.
• Sign-in button: show a "Sign in with" button for the provider, with your own name and logo.

Everything lives under Admin > Settings > Access & Security, on the Sign-in tab, in the Single sign-on (OIDC) card. Each provider you add gets its own page.

Step 1: Register Quackback with your provider

Create an OIDC application in your identity provider.

The redirect URI has this shape:

https://YOUR_DOMAIN/api/auth/callback/<registration-id>

New providers get a registration id that looks like oidc_.... A provider created earlier may use sso or custom-oidc. Because the id is part of the URI, copy the value from the provider's page rather than typing a path from this article.

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

Warning: The redirect URI must match exactly, including https, no trailing slash, and the registration id. A mismatch is the most common cause of a failed test sign-in.

Note: Providers set up before version 0.14 keep their original redirect URI, /api/auth/oauth2/callback/<registration-id>, so sign-in keeps working without changes at your identity provider. New providers use /api/auth/callback/<registration-id>. The provider's page shows the URI it currently uses. To move an older provider to the new URI, register the new URI with your identity provider first, click Switch to new URI on the provider's connection and confirm, then run Test sign-in again.

Step 2: Add the connection

1. Go to Admin > Settings > Access & Security and open the Sign-in tab.
2. In the Single sign-on (OIDC) card, add a provider.
3. Enter the Discovery URL, Client ID, and Client Secret, and give it a display name.
4. Click Save and test.

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

Step 3: Run a test sign-in

Before you can turn SSO on or require it for a domain, Quackback asks you to prove the connection works.

1. Click Test sign-in on the provider's page.
2. A window opens your identity provider. Sign in.
3. Quackback runs the full OIDC handshake (discovery, token exchange, signature check, claim checks) and tells you exactly which step failed, if any.

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

Step 4: Turn SSO on

Enable the provider. The SSO option now appears on the sign-in page. At this point SSO is available alongside your other sign-in methods. It doesn't replace them yet.

Verify your domains

A verified domain tells Quackback that you own an email domain, so people with emails on that domain are sent to SSO by default.

1. On the provider's page, under Domains, add a domain (for example acme.com).
2. Quackback shows a DNS TXT record to publish (see the example below).
3. Add the record at your DNS provider, wait for it to propagate, then click Verify.

Example TXT record:

You can verify up to 10 domains. Once a domain is verified, people at that domain see "Continue with SSO" as the default sign-in option.

Note: Verifying a domain only changes the default sign-in route. Other methods keep working until you turn on Require SSO.

Require SSO for a domain

Turn on Require SSO next to a verified domain. Emails on that domain can then only sign in through your identity provider. Password, magic link, and social sign-in are refused for those addresses.

Before you can require SSO:

• The connection must have passed a test sign-in since its last change.
• You must have generated recovery codes. They are the only way back in if SSO breaks.

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

Warning: If your identity provider goes down, people at an enforced domain can't sign in normally. Recover with a recovery code, or with an admin whose email is on a domain that isn't enforced.

Enforcement fails open: if SSO stops working at runtime (for example, the client secret is removed or the connection is disabled), Quackback suspends enforcement so your team isn't locked out. Turn it back on once SSO is healthy again.

When someone at a verified domain tries to sign in while SSO isn't available (the connection is off, the secret is missing, or SSO isn't on your plan), they see: "Single sign-on is configured for your domain but is not currently available. Contact your administrator." This replaces a broken redirect, so the person knows to reach out rather than keep retrying.

Recovery codes

Recovery codes are single-use passcodes that get an admin in when SSO is unavailable. You'll find them in the Single sign-on (OIDC) card on the Sign-in tab.

1. Click Generate new codes.
2. Quackback shows 10 codes once. Copy, download, or print them and store them somewhere safe.
3. Generating a new batch invalidates the previous one.

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

Tip: Generate recovery codes before you turn on Require SSO. Discovering you have none during an SSO outage is the worst possible time.

Create accounts on first sign-in

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).

On the provider's page, in the Sign-in & access card, you can:

• Turn Create accounts on first sign-in off, so a person must already exist in Quackback before they can sign in through SSO.
• Choose the New account role that automatically created accounts receive: Admin, Member, or User (portal only). The default is User (portal only), so new people get customer access until you give them a team role. Pick Member if everyone signing in through this provider should join your team.
• Turn Show sign-in button on or off, and set the button's display name and logo. People at a verified domain are still sent to the provider from the email step even when the button is hidden.

Note: The very first SSO sign-in to 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 your provider's claims

Instead of giving every new account the same role, you can set each person's role from a claim on the provider's ID token.

1. Turn on role mapping on the provider's page.
2. Set the claim path: a dotted path (such as realm_access.roles) or a URL-shaped claim (such as https://acme.com/roles). Your provider's documentation lists the claim.
3. Add rules. The first matching rule wins. Each rule maps a value the claim contains to a role, for example platform-admins to Admin.
4. Set a default role for people that no rule matches.
5. Optionally re-apply the mapping on every sign-in. This can demote a team member if their group at the provider changes.

Role changes made by mapping are recorded in the audit log.

Provider examples

For every provider, the redirect URI is the one shown on the provider's page in Quackback, in the form https://YOUR_DOMAIN/api/auth/callback/<registration-id>.

How it works

1. A person clicks Continue with SSO, or is sent there automatically because their email is at a verified domain.
2. Quackback redirects them to your identity provider.
3. They sign in with their work credentials.
4. The provider redirects back to Quackback with an authorization code.
5. Quackback exchanges the code, checks the ID token signature, and reads the email claim.
6. If the account exists, it's linked. Otherwise it's created according to your account options.

Quackback expects an email claim from your provider. If your provider doesn't release it by default, add it to the application's claims. If your provider can't supply an email at all, turn on Let users sign in without an email address on the provider's page.

Troubleshooting

Test sign-in fails at "token exchange"

Usually a wrong client secret or a redirect URI mismatch. The test report names the failing step. Compare each value with your provider's application.

Test sign-in fails at "claim check"

The ID token is missing email or sub. Configure your provider to release the email claim (for example, client scopes in Okta or Keycloak, or API permissions in Entra ID).

"Verified domain requires SSO"

The email is at an enforced domain and tried a different sign-in method. Sign in through your identity provider, or use a recovery code.

Domain verification won't pass

DNS changes can take time to propagate. Check the TXT record with dig +short TXT _quackback-verify.YOUR_DOMAIN before clicking Verify again.

Related articles

• Configure team security
• How sign-in works
• Control portal access and sign-in
• Declarative configuration