SSO & domains

Verify your company's domain, add your team automatically, require SSO, and connect Okta, Entra ID or any other OIDC provider.

Org admins set up single sign-on under Settings > SSO & domains. Only admins see the tab. It works the same on Pug Cloud and on a self-hosted server. Cloud and self-hosted lists the few differences.

Setting	What it does	Default
Domains	Prove your org owns a domain, such as `acme.com`, with a DNS record. The other settings need one.	-
Auto-join	People who sign in through SSO with an `@acme.com` account join your org.	Off
Let members create their own organizations	When off, `@acme.com` people can’t create orgs of their own.	On
Require SSO	`@acme.com` accounts can sign in only through SSO. Passwords and email links stop working for them.	Off
SSO connections	Sign people in through your company’s identity provider, such as Okta, Microsoft Entra ID or Keycloak.	None

What counts as SSO

On this page, “SSO” means a sign-in through a provider that speaks for your domain. Only these sign-ins prove a domain:

Sign-in	Proves `acme.com`?
Continue with Google, with a Google Workspace account on `acme.com`	Yes
Continue with Google, with a personal Google account, even one with an `@acme.com` address	No
The SSO connection that signs in `acme.com`	Yes
A provider the operator set up for `acme.com` on a self-hosted server	Yes
An email link or a password	No

Google Workspace needs no setup. Google marks Workspace accounts with their domain, but only once the company has proved to Google that it owns the domain. A personal Google account has no such mark, so it proves nothing.

Verify a domain

Add the domain

Under Domains, choose Add domain and enter it, for example acme.com.

Add the TXT record at your DNS provider

The domain’s row shows a record for your org. Copy both values from there:

Type	Name	Value
`TXT`	`_pug-verification.acme.com`	`pug-verification=...`

Choose Verify now

The domain turns Verified. DNS changes can take a few minutes to show up, so try again if the record isn’t found yet. A pending domain stays in the list until you verify or remove it.

Keep the record. Pug checks it again whenever your org turns on something that acts on other people, such as auto-join, Require SSO or a new SSO connection. If the record is gone, the change is refused. Turning a setting back off always works.

Each org gets its own value. Several orgs can verify the same domain, such as two orgs of one company. DNS allows several TXT records with the same name.
Subdomains are separate. eng.acme.com needs its own verification.
An org can add up to 10 domains.
The settings apply to every domain the org verified, including ones verified later.

Can’t add a DNS record? The operator can verify the domain for you, and it then shows as Verified by your administrator. On Pug Cloud, contact us. On a self-hosted server, the operator runs pug domains verify.

Auto-join

Auto-join is off by default. Turn it on and pick the Role for new people: Viewer (the default) or Member. Auto-join never makes anyone an admin.

While it’s on, people who sign in through SSO with an account on one of your verified domains join your org:

Who	When they join
A new person	At their first SSO sign-in. They don’t get an org of their own.
An existing Pug user	At their next SSO sign-in. They keep the orgs they already have.
Someone already signed in through SSO	The next time their session refreshes, about once a day while they use Pug.
Someone signed in with an email link or a password	Not through auto-join. Invite them, or they join at their next SSO sign-in.

They see “You joined Acme.” in the dashboard, and the Members page marks them via acme.com.

A pending invite wins. Someone with a pending invite that hasn’t expired isn’t auto-joined, and the invite’s role applies when they accept it.
Auto-join never changes the role of someone already in the org.
Turning auto-join off stops new joins. People who already joined stay.

Org creation

Let members create their own organizations is on by default. When you turn it off, people with an email on your verified domains:

can’t create new orgs. The dashboard hides the option, and the server refuses with “your company doesn’t allow creating new orgs”.
get no org when they sign up. Auto-join or an invite adds them to yours. Until then they see “You’re not in an org yet”.

Admins of your org can still create orgs. People on other domains, such as a contractor on gmail.com, aren’t affected. Orgs that already exist are not touched.

Require SSO

Each verified domain has a Require SSO switch. When it’s on, accounts on that domain must sign in through SSO:

Passwords and email links stop working for them. Pug keeps the passwords, so they work again if you turn Require SSO off.
People signed in another way are signed out within a day, at their next session refresh. So are SSO sessions started before Require SSO was available.
It applies to every account on the domain, in every org, admins included.
An invited person on the domain is asked to sign in through SSO, and the invite is accepted after that.
API keys keep working. They belong to projects, not people, so SDKs, the API and the MCP server are not affected.

On the sign-in page, an @acme.com email goes straight to the domain’s SSO buttons, with no email link option.

The switch stays disabled until someone has signed in once through SSO with an account on the domain. This stops an admin from locking out a company that doesn’t use that provider.

SSO connections

A connection signs people in through your company’s own identity provider over OIDC. Okta, Microsoft Entra ID, Keycloak, Auth0, OneLogin and most others work. You need a verified domain first. Google Workspace needs no connection.

Create an app at your identity provider

Create an OIDC web application that uses the Authorization Code flow and has a client secret. Assign the people or groups who should use Pug. Note the issuer URL, client ID and client secret.

If the provider asks for a redirect URL now, leave it blank or enter a placeholder. You get the real one in step 3.

Add the connection in Pug

Under SSO connections, choose Add connection, fill in the fields below, and choose Save. Pug reads the issuer’s OpenID configuration on save, so a wrong issuer URL fails right away.

The saved connection shows its Redirect URL. Add it to the app at your identity provider. On Pug Cloud it looks like this:

https://app.pug.sh/oauth/callback/<connection id>

Test it

In a private window, open the sign-in page. Enter an email on one of the connection’s domains, choose Continue, then choose the connection’s button.

Field	What to enter
Button label	What people see on the sign-in button, such as “Acme SSO”.
Issuer URL	The provider’s issuer, exactly as its OpenID configuration names it, including any trailing slash. It must use HTTPS.
Client ID	From the app you created.
Client secret	From the app you created. Pug stores it encrypted and never shows it again. When you edit a connection, leave it blank to keep it. A new issuer or client ID needs it again.
Domains	The verified domains this connection signs in.

Pug asks for the openid, profile and email scopes. Your provider must send the email claim in the ID token. It doesn’t need to send email_verified.

Provider	Issuer URL
Okta	`https://<your Okta domain>`, or `https://<your Okta domain>/oauth2/default` for a custom authorization server
Microsoft Entra ID	`https://login.microsoftonline.com/<tenant id>/v2.0`. Use your tenant ID, not `common`.
Keycloak	`https://<host>/realms/<realm>`
Auth0	`https://<your Auth0 domain>/`, with the trailing slash

When in doubt, open <issuer>/.well-known/openid-configuration and copy its issuer field.

A connection doesn’t add a button to the sign-in page. People enter their work email and choose Continue. For a domain with a connection, the page then shows Continue with Acme SSO. It also offers Email me a link instead, unless the domain requires SSO.

A connection signs in only emails on the domains it lists. People on other domains, such as contractors, sign in another way and join by invite.

Connection rules

One connection per domain, across every org that verified it. The form shows which connection already signs in a domain, and that domain can’t be picked.
An org can have up to 10 connections, each for its own domains. A company that buys another can keep both identity providers while it merges them.
A new issuer unlinks the people who signed in through the connection. They link again by email at their next sign-in. Deleting a connection unlinks them too.
A connection can’t be deleted or lose a domain while any org requires SSO for that domain. Turn Require SSO off first.
A connection can’t use Google’s issuer. Google Workspace accounts already prove their domain through Continue with Google.

Several orgs, one domain

Each org that verified a domain gets every setting. When their choices differ, the strictest wins:

Setting	With two orgs
Auto-join	Each org decides for itself. A person can join both, with each org’s role.
Let members create their own organizations	Off if either org turns it off. Admins of either org can still create orgs.
Require SSO	On if either org turns it on.
SSO connection	One per domain. It signs the domain in for every org that verified it.

The tab says when another org is stricter, for example “Also required by another organization that verified acme.com.” To lift a limit, every org that set it must turn it off.

Cloud and self-hosted

Everything above works on both. These things differ:

	Pug Cloud	Self-hosted
Google Workspace	Works with no setup, through Continue with Google.	The operator adds a Google client to `PUG_CONFIG_FILE` once. See Authentication.
SSO connections	On. Your issuer must be reachable from the internet.	On once the operator sets `PUG_SSO_SECRET_KEY`. See Org SSO connections.
Redirect URL	`https://app.pug.sh/oauth/callback/<connection id>`	`https://<your dashboard>/oauth/callback/<connection id>`
A provider for the whole server	-	The operator can list your identity provider in `PUG_CONFIG_FILE` with `emailDomains`. It shows as a button for everyone.
Verifying a domain without DNS	Contact us.	The operator runs `pug domains verify`.
Getting back in after a Require SSO lockout	Contact us.	The operator runs `pug domains unenforce`.

On Pug Cloud, contact us at hello@pug.sh and include the domain. To have a domain verified, also include your Organization ID, from Settings > Organization.

Not supported yet

SAML. Use OIDC. Okta, Entra ID, OneLogin and other SAML providers speak it too.
SCIM. Suspending someone at your identity provider stops their new sign-ins, but a session they already have keeps working. Remove people who leave on the Members page, and mind the auto-join caution.
Group-to-role mapping. Roles come from auto-join or invites.
Single logout. Signing out of Pug doesn’t sign you out of your identity provider.
Wildcard subdomains. Verify each subdomain on its own.

Troubleshooting

Message	Cause	Fix
“no TXT record for acme.com holds this org’s verification value”	The record isn’t there, or doesn’t show up yet.	Check the name and value, and wait a few minutes.
“we couldn’t reach DNS to check the record”	The DNS lookup failed.	Try again in a minute.
“verify a domain before turning this on”	The org has no verified domain.	Verify one first.
Require SSO stays disabled	Nobody has signed in through SSO with an account on the domain yet.	Sign in once through SSO with an account on it.
“enter the issuer exactly as its OpenID configuration names it”	The issuer URL differs from the `issuer` field, often by a trailing slash.	Copy the `issuer` field.
“we couldn’t read the issuer’s OpenID configuration”	Pug couldn’t fetch `<issuer>/.well-known/openid-configuration`.	Check the URL. Pug Cloud needs an issuer on the internet.
“the issuer is on a private network address”	The issuer’s address is private, and the server doesn’t reach those.	Self-hosted: the operator sets `PUG_SSO_ALLOW_PRIVATE_ISSUERS=true`.
“enter the client secret again”	The issuer or client ID changed, or the server’s key did.	Enter the client secret.
“another SSO connection already signs in this domain”	One connection per domain.	Use that connection, or ask its admins to take the domain off it.
“Acme SSO sign-in could not be started”	The browser couldn’t read the provider’s OpenID configuration.	The provider must allow cross-origin requests to it. Okta, Entra ID, Auth0 and Google do.
“Acme SSO can’t sign in that account to Pug”	The email, or the Pug account it belongs to, isn’t on a domain the connection lists.	Add the domain to the connection, or sign in another way.
“Acme SSO couldn’t sign you in”	Usually the connection’s setup, such as its client secret or a missing `email` claim.	Check both at your identity provider, then edit the connection.