Documentation

Single sign-on

Let your team sign in to the WattleAddr console with your own identity provider. Accounts are created on first sign-in, and you can require SSO so a password can’t be used instead.

Enterprise plans. SSO uses OpenID Connect — Okta, Microsoft Entra ID, Google Workspace, Auth0, Ping and anything else that speaks it. Setup takes about ten minutes, plus however long your DNS takes to propagate. Only the workspace owner can configure it.This covers signing in to the console. It does not change how your application authenticates to the API — that is still API keys.

Before you start

You are the owner of the workspace (not an admin — this decides who can get in).
You can create an application in your identity provider.
You can add a TXT record to the DNS of each email domain you want to use.
Your workspace is on an Enterprise plan.

1. Create the application in your provider

In the console, open Settings → Single sign-on and copy the Redirect URI. Create a new web application in your identity provider and paste it in as the sign-in redirect (some providers call this the callback URL, reply URL, or authorised redirect URI):

https://console.wattleaddr.com.au/api/auth/sso/callback

Grant the application the standard openid, email and profile scopes. Then copy out three things:

What	Where it usually lives
Issuer URL	Okta: `https://YOUR-ORG.okta.com/oauth2/default` Entra ID: `https://login.microsoftonline.com/TENANT-ID/v2.0` Google: `https://accounts.google.com`
Client ID	On the application you just created.
Client secret	Generated with the application. Copy it now — most providers show it once.

Use the issuer exactly as your provider publishes it. We read /.well-known/openid-configuration from it to find the rest, and we check that the issuer it declares matches the one you gave — which is what stops a connection quietly pointing at a different tenant.

2. Save the connection

Paste the issuer, client ID and client secret into Settings → Single sign-on, choose the role new members should get, and save. We contact your provider at that moment, so a wrong URL is caught here rather than by an employee on Monday morning.

The role for new members applies only to people signing in for the first time. Existing members keep the role they have — your identity provider can never change someone’s role here, and cannot create owners.

Your client secret is stored encrypted and is never shown again. Changing any part of the connection means entering it once more.

3. Verify your email domain

Add each email domain your staff sign in with, then publish the TXT record shown next to it:

# host
_wattleaddr-verify.acme.com.au

# value
wattleaddr-domain-verification=…

Then press Check DNS. Propagation is usually minutes but can take up to an hour; the check is safe to repeat.

Why we ask. Claiming a domain is claiming the people who use it — once verified, your provider can sign in anyone at that domain. So a domain has to be proven, it can only ever belong to one workspace, and public mailbox providers (Gmail, Outlook, Bigpond and the like) can’t be claimed at all.

4. Switch it on

With at least one verified domain, tick Allow single sign-on. Your team can now sign in two ways: the console offers “Continue with single sign-on” as soon as it recognises the domain in a typed email address, and existing passwords still work.

Test it before going further. Sign in through your provider in a private window and confirm you land in the right workspace.

5. Require it (optional)

Tick Require single sign-on and password sign-in is refused for everyone at your verified domains. Do this only once step 4 works — including for your own account.

Keep one way back in. People created by single sign-on have no password here. If this workspace later moves off Enterprise, SSO stops working — so keep at least one owner who can still sign in with a password, on a domain outside your SSO connection if you can.

What happens on sign-in

Someone typing an email at a verified domain is offered your provider.
First sign-in creates their WattleAddr account and adds them to the workspace with the default role. If they already had an account on that address, it is linked rather than duplicated.
A pending invitation for that address is accepted automatically, keeping the role you chose in it.
Your plan’s member limit still applies — if the workspace is full, sign-in is refused with a message saying so.
Signing out ends the WattleAddr session only; it does not sign the person out of your identity provider.
Removing someone in your provider stops future sign-ins. It does not end a session already running or free their seat — remove them from Team as well.

Troubleshooting

What you see	What it usually is
“Couldn’t read the identity provider’s configuration”	The issuer URL is wrong, is not reachable from the public internet, or redirects elsewhere. Use the value your provider publishes, with no trailing path.
“The IdP declares its issuer as…”	You pasted a metadata URL from a different tenant or authorisation server. Copy the issuer exactly as shown in that provider’s own metadata.
No TXT record found	DNS hasn’t propagated, or the record was added at the wrong host. It must be the full `_wattleaddr-verify.<domain>`; some DNS panels append the domain for you.
“We couldn’t find a single sign-on connection for that email address”	The domain isn’t verified, the connection is switched off, or the workspace is no longer on Enterprise.
“Your identity provider returned an email address outside the domains this workspace has verified”	The account signing in uses a domain you haven’t added and verified.
“We couldn’t verify the response from your identity provider”	Usually the client secret, or a clock badly out of sync at the provider. Re-enter the secret.
“That sign-in attempt took too long”	More than ten minutes at the provider’s login screen, or cookies blocked. Start again.
“Your workspace has no seats left”	The member limit on your plan. Free a seat in Team, or talk to us about the limit.

Every configuration change is recorded in your workspace’s activity log. Still stuck? support@wattleaddr.com.au