Sign in Providers

Sign-in Providers

From v0.3.0, every organization has a break-glass account and, next to it, at most one sign-in provider:

Provider	What the server needs
Microsoft (Entra ID)	ENTRA_SSO_CLIENT_ID / ENTRA_SSO_CLIENT_SECRET
Google Workspace	GOOGLE_SSO_CLIENT_ID / GOOGLE_SSO_CLIENT_SECRET
Any OpenID Connect provider (Authentik, Keycloak, Zitadel, Authelia, Okta, Auth0, ...)	Nothing

The break-glass account

• The platform admin creates every organization with its break-glass account: a local account (email, password and authenticator) that is org admin. The platform admin shares its one-time setup link.
• Only the break-glass account chooses, switches or removes the organization's provider, in Settings → Sign-in. It always signs in with its own password and authenticator, so the organization can't lock itself out by choosing a provider that doesn't work.
• Without a provider, an organization can add more local accounts (Team). Once it has a provider, the break-glass account is its only local account: other local accounts are disabled and people join by signing in through the provider.
• People who sign in through the provider for the first time are members; the break-glass account (or another org admin) promotes them in Team.
• Org admins can reset the break-glass account's password or authenticator. If it's locked out anyway, the platform admin can reset it, make another local account the break-glass account, or set the provider directly.

Choosing or switching the provider

Signed in as the break-glass account, Settings → Sign-in: choose the provider and click Test sign-in. A window opens where you sign in with a work account of your organization at that provider. Save only works after the test passed:

• the account's email must be on one of the organization's verified domains;
• for Microsoft and Google, the tenant or Workspace is taken from the provider's signed answer (nobody types it in), and one tenant or Workspace belongs to one organization.

Saving signs out everyone who was signed in through a provider (they sign in again with the new one) and disables other local accounts. A Microsoft 365 report mailbox keeps working when the organization's sign-in moves away from Microsoft.

People keep their account when the provider changes (from v0.3.0-beta19): their first sign-in through the new provider takes over their account from the previous one, with its role, when the email address is the same and on one of the organization's verified domains. A disabled account stays disabled.

Removing accounts: Team shows each account's provider and marks accounts of a provider the organization no longer uses as previous provider. Org admins (and the platform admin, under Admin → Organizations) can remove those, and disabled local accounts. Accounts of the current provider can't be removed, only disabled: removing one would let its owner back in as a new account. Sign-in activity keeps the history and logs the removal.

The login page

• Sign in with Microsoft / Sign in with Google show when the server has those apps set.
• Company account: the person enters their work email address. The domain is looked up among verified domains, and the browser goes straight to that organization's provider with the address filled in. Public mailbox domains (gmail.com, outlook.com, ...) never match, and the login page never names an organization: an unknown domain gets "There's no company sign-in for this email address".
• Direct link: every organization has https://<your server>/login/<name>, which skips the email step. The name is random (so links can't be guessed from organization names); the platform admin can choose a readable one. Org admins find the link in Settings → Sign-in. Lookups are rate-limited.

Google Workspace

1. In the Google Cloud console: APIs & Services → Credentials → Create credentials → OAuth client ID, type Web application, authorized redirect URI https://<your server>/api/auth/google/callback. The consent screen can be "External"; the app only asks for openid email profile.
2. Set GOOGLE_SSO_CLIENT_ID and GOOGLE_SSO_CLIENT_SECRET (env file, Portainer stack variables, or the Azure template's Sign-in step) and restart.
3. The organization's break-glass account chooses Google Workspace in Settings → Sign-in and runs the test sign-in. (The platform admin can also enter the Workspace's primary domain directly.)

Only Google Workspace accounts of that Workspace get in: Google marks them with the Workspace domain (hd), which personal Gmail accounts don't have. One Workspace belongs to one organization.

Your own OpenID Connect provider

In your provider, create an application (OAuth2/OIDC, confidential, with a client secret):

• Redirect URI: shown in Settings → Sign-in, for example https://dmarc.example.com/api/auth/oidc/callback
• Scopes: openid email profile
• The provider must send the user's email address, and mark it verified (or not send email_verified at all).

Then in YADT, signed in as the break-glass account, Settings → Sign-in: choose Other OpenID Connect provider, enter the issuer URL, client ID and client secret, and click Test sign-in. The test checks everything a real sign-in checks; Save only works after a test passed with exactly those settings.

Examples of the issuer URL:

Provider	Issuer URL
Authentik	https://auth.example.com/application/o/<application slug>
Keycloak	https://sso.example.com/realms/<realm>
Zitadel	https://<instance>.zitadel.cloud

What is checked on every sign-in

• The token is signed by the provider's keys and meant for this app (issuer, client ID, expiry, and a one-time value tied to this browser).
• It is checked against the organization the sign-in was started for, never against something the provider's answer says, so one organization's provider can't sign anyone into another.
• The email address must be on one of the organization's verified domains (or a subdomain of one).

Providers on your own network

The server refuses to contact a provider on a private address (10.x, 192.168.x, 172.16–31.x, ...), so an organization admin can't use the issuer URL to reach internal systems. If every organization on your server is trusted, OIDC_ALLOW_PRIVATE_ISSUERS=true allows it (and plain http:// issuers too).

Troubleshooting

Failed sign-ins show in Settings → Sign-in activity (and for the platform admin, in Sign-ins) with a reason:

Reason	Meaning
email_domain_not_verified	The email isn't on one of the organization's verified domains.
email_not_verified	The provider says the email address isn't verified.
hd_mismatch	A personal Google account instead of a Workspace account.
organization_not_provisioned	No organization uses this Microsoft tenant / Google Workspace, or the direct link's name is unknown.
token_invalid	The provider's answer didn't check out (wrong client secret, clock far off, expired).
provider_unavailable	The provider couldn't be reached, or its address isn't allowed (see above).