Skip to content
DashboardWebsite

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.

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:

LabelMeaning
LiveIts button is on the login page
ReadyFully configured, but hidden while the master switch is off
IncompleteSwitched on, but its client ID or secret is missing, so no button is shown
OffSwitched 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:

Terminal window
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_enabled is on.
  • The provider’s own *_enabled switch 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.

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.

ResultUsual cause
Sign-in worksEverything 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_clientWrong 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_failedFor Microsoft, Accounts admitted isn’t common, organizations, consumers or a real tenant ID
provider_errorThe 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.

  1. In Google Cloud, open APIs & Services → Credentials → Create credentials → OAuth client ID, with application type Web application.

  2. Under Authorized redirect URIs, add exactly:

    {Public API URL}/auth/oauth/google/callback

    where {Public API URL} is the server.public_base_url setting, the API’s own public address, not the dashboard’s. The provider redirects the browser back to the API.

  3. The OAuth consent screen needs the openid, email and profile scopes only.

  4. Copy the client ID and client secret into the settings above.

  1. In Microsoft Entra, open App registrations → New registration. Choose the supported account types to match social_login_microsoft_tenant below: any organizational directory and personal Microsoft accounts for common.

  2. Add a Web redirect URI, exactly:

    {Public API URL}/auth/oauth/microsoft/callback
  3. Under Token configuration → Add optional claim → ID, add email and xms_edov.

  4. 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:

ValueAdmits
common (default)Work or school accounts from any tenant, and personal Microsoft accounts
organizationsWork or school accounts from any tenant
consumersPersonal 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:

  1. 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.
  2. 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.
  3. 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_link on, the provider is attached to that account automatically.
  4. No account at all? The server creates one without an organization. The user continues on the onboarding page. registration.allow_public_org_creation still decides whether they can create an org. To stop new accounts from being created this way, turn off social_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.

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.

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_errorMeaning
account_existsAn account with this email exists and auto-linking is off. Sign in with the password, then link
signup_disabledNo matching account, and social_login_allow_signup is off
email_unverifiedThe provider didn’t verify the email (for Microsoft, usually a missing xms_edov optional claim)
email_missingThe provider shared no email address
identity_in_useThat provider account is already linked to a different OpenTremor account
provider_already_linkedThis account already has a different account from that provider linked
domain_managed_by_ssoLink refused: the email’s domain belongs to an org’s SSO connection
deactivatedThe account is deactivated
provider_disabledThe provider was switched off mid-sign-in
cancelledThe user backed out at the provider
expiredThe sign-in took longer than 10 minutes, or cookies are blocked
rate_limitedToo many accounts created from one network
failedAny 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.