Quick Start: Sign in with Google or Microsoft
A platform superadmin can put Continue with Google and Continue with Microsoft buttons on the login and registration pages. They work before any organization is known. A new user gets an account without a password. An existing user signs in with the provider account they linked.
Sign-in providers are off by default. If no provider is configured, the login page does not change.
Turning it on
Section titled “Turning it on”In the dashboard: Platform Admin → Security → Sign-in Providers. The page has a tab for each part:
- General holds the master switch and the account policy: whether a sign-in may create an account, and whether it may link to an existing account by email.
- Google and Microsoft each hold that provider’s own switch, client ID and client secret. Each also shows the exact redirect URI to register with the provider, built from the Public API URL, with a copy button, and a Try it button.
Each tab label shows what that provider will be once you save. It follows your edits as you make them:
| Label | Meaning |
|---|---|
| Live | Its button is on the login page |
| Ready | Fully configured, but hidden while the master switch is off |
| Incomplete | Switched on, but its client ID or secret is missing, so no button is shown |
| Off | Switched off |
Edits on every tab go out together in the one Save settings. Switching tabs doesn’t drop an edit, and a tab with unsaved edits is marked with a dot. Until you save, the label describes the form, not what’s live.
Each setting’s switch means “override the default”. Turning it on for a yes/no setting also picks the non-default value, so switching on Offer Google sign-in selects Enabled.
Or use the API, with any superadmin credential:
curl -X PATCH http://localhost:8000/v1/admin/settings \ -H "X-API-Key: change-me-to-a-strong-secret" \ -H "Content-Type: application/json" \ -d '{ "social_login_enabled": true, "social_login_google_enabled": true, "social_login_google_client_id": "1234567890-abc.apps.googleusercontent.com", "social_login_google_client_secret": "GOCSPX-..." }'A provider’s button appears when all three conditions are true:
- The master switch
social_login_enabledis on. - The provider’s own
*_enabledswitch is on. - The provider’s client ID and client secret are both set.
Turning the master switch off hides every button and refuses every provider sign-in. The client IDs and secrets stay stored, so you do not need to re-enter them when you turn it back on.
The client secrets are write-only. GET /v1/admin/settings does not return them. It returns only
secrets_set.social_login_google_client_secret: true. As with every field on the Settings page,
you cannot set these values in the configuration file or an environment variable. See
Configuration Reference.
Every setting takes effect on the next request. No restart is required.
Checking a configuration with Try it
Section titled “Checking a configuration with Try it”Try it runs a real sign-in with the saved settings. It uses the same redirect, token exchange, and ID-token checks as a user’s sign-in. Sign in at the provider with any account. Nothing is created or linked, and your own session does not change. The result appears on the same tab.
Try it works before the provider or the master switch is turned on. Use it to test a configuration before users see the button. It requires a saved client ID and secret. It is disabled while the tab has unsaved edits.
| Result | Usual cause |
|---|---|
| Sign-in works | Everything agrees. The result also says if the button isn’t live yet, or if the email’s domain belongs to an organization’s SSO connection |
token_exchange_failed with invalid_client | Wrong client ID or client secret. For Microsoft, pasting the secret’s ID instead of its value, or an expired secret |
email_unverified (Microsoft) | The app registration lacks the optional ID-token claim xms_edov |
email_missing (Microsoft) | The app registration lacks the optional ID-token claim email |
id_token_invalid (Microsoft) | The account you used isn’t admitted by Accounts admitted |
discovery_failed | For Microsoft, Accounts admitted isn’t common, organizations, consumers or a real tenant ID |
provider_error | The provider refused the request. Its own error is shown alongside |
If the redirect URI is not registered exactly, the provider shows redirect_uri_mismatch on its
own page. The provider does not redirect the browser to an unregistered address.
Registering the Google client
Section titled “Registering the Google client”-
In Google Cloud, open APIs & Services → Credentials → Create credentials → OAuth client ID, with application type Web application.
-
Under Authorized redirect URIs, add exactly:
{Public API URL}/auth/oauth/google/callbackwhere
{Public API URL}is theserver.public_base_urlsetting, the API’s own public address, not the dashboard’s. The provider redirects the browser back to the API. -
The OAuth consent screen needs the
openid,emailandprofilescopes only. -
Copy the client ID and client secret into the settings above.
Registering the Microsoft app
Section titled “Registering the Microsoft app”-
In Microsoft Entra, open App registrations → New registration. Choose the supported account types to match
social_login_microsoft_tenantbelow: any organizational directory and personal Microsoft accounts forcommon. -
Add a Web redirect URI, exactly:
{Public API URL}/auth/oauth/microsoft/callback -
Under Token configuration → Add optional claim → ID, add
emailandxms_edov. -
Under Certificates & secrets, create a client secret. Copy its value (not its ID) and the app’s Application (client) ID into
social_login_microsoft_client_secret/social_login_microsoft_client_id.
social_login_microsoft_tenant decides whose accounts are admitted:
| Value | Admits |
|---|---|
common (default) | Work or school accounts from any tenant, and personal Microsoft accounts |
organizations | Work or school accounts from any tenant |
consumers | Personal Microsoft accounts only |
| a tenant ID (GUID) | Users of that one tenant only |
What happens when someone clicks the button
Section titled “What happens when someone clicks the button”The browser goes to the provider. The provider sends it back to
GET /auth/oauth/{provider}/callback. The server then resolves the account in this order:
- Is the email’s domain verified by an organization’s SSO connection? Then the browser is sent into that org’s SSO sign-in instead. See SSO takes precedence.
- Is this provider account already linked to an OpenTremor account? Then that account is
signed in. The match uses the provider’s stable user ID (Google’s
sub, or Microsoft’s tenant ID + object ID), never the email. An email change at the provider does not unlink the account. - Does an account already exist with this email? By default the sign-in is refused, and the
user is told to sign in with their password and link the provider from their Account page. With
social_login_allow_auto_linkon, the provider is attached to that account automatically. - No account at all? The server creates one without an organization. The user continues on
the onboarding page.
registration.allow_public_org_creationstill decides whether they can create an org. To stop new accounts from being created this way, turn offsocial_login_allow_signup. Existing accounts and invitation links still work.
A deactivated account is refused, the same as a password sign-in. An email the provider didn’t
verify is refused too: Google’s email_verified, Microsoft’s xms_edov.
Invitation links work with the buttons. Open an invitation link and choose Continue with Google. The invitation is kept through the provider redirect, and the account joins the inviting org with the invitation’s role. An invitation for a specific email is accepted only if the provider account has that email.
An account with its own two-factor authentication still needs it. If a user turned on TOTP for their account, signing in with a provider takes them to the same code prompt a password sign-in would. A compromised Google account is not a way around a factor they chose.
SSO takes precedence
Section titled “SSO takes precedence”If an organization’s enabled SSO connection has verified an email domain, a provider sign-in with an address at that domain is always sent to that org’s SSO connection. This holds even for an account that used the provider button before the org connected SSO.
This rule prevents users from bypassing an org’s identity provider. Without it, [email protected]
could choose Continue with Google with a Google account on the same address. She would skip
Acme’s Entra tenant: its conditional-access policies, its offboarding, and its default_role.
For the same reason, the server refuses to link a provider account in an SSO-verified domain.
Linking and unlinking from the Account page
Section titled “Linking and unlinking from the Account page”A signed-in user can link a provider from Account → Sign-in tab → Sign-in providers → Link Google. They sign in at the provider. The provider account is attached to their OpenTremor account, even if the email is different, because they have proved they control both. They can then sign in either way.
Unlink removes the link. The server refuses to unlink the account’s only sign-in method, when the account has no password, no org SSO connection, and no other linked provider.
An account created through a provider has no password. Its Account page doesn’t offer password or two-factor settings, because the provider owns both.
Organizations that require two-factor authentication
Section titled “Organizations that require two-factor authentication”A Google or Microsoft session does not meet an organization’s require 2FA policy on its own. OpenTremor can’t tell whether the provider account uses MFA, and it may have none. The session meets the policy only when the OpenTremor account has its own TOTP, which the sign-in then asks for. An account created through a provider has no password and can’t enroll TOTP, so in such an organization it can only sign in through SSO.
To enforce MFA through an identity provider, an organization connects its own SSO, where its conditional-access rules apply. An SSO session meets the policy. An organization can also refuse Google and Microsoft sign-in altogether: see Choosing how members sign in.
Error messages
Section titled “Error messages”A failed sign-in returns to the login page with a message. A failed link returns to the Account
page. The oauth_error query parameter contains the error key:
oauth_error | Meaning |
|---|---|
account_exists | An account with this email exists and auto-linking is off. Sign in with the password, then link |
signup_disabled | No matching account, and social_login_allow_signup is off |
email_unverified | The provider didn’t verify the email (for Microsoft, usually a missing xms_edov optional claim) |
email_missing | The provider shared no email address |
identity_in_use | That provider account is already linked to a different OpenTremor account |
provider_already_linked | This account already has a different account from that provider linked |
domain_managed_by_sso | Link refused: the email’s domain belongs to an org’s SSO connection |
deactivated | The account is deactivated |
provider_disabled | The provider was switched off mid-sign-in |
cancelled | The user backed out at the provider |
expired | The sign-in took longer than 10 minutes, or cookies are blocked |
rate_limited | Too many accounts created from one network |
failed | Any other error. The API log has the cause, most often a redirect URI mismatch or a wrong client secret |
See API Endpoints — Social login for the endpoint reference.