Skip to main content

Social Login

App Auth supports Google and GitHub as social sign-in providers. When configured, buttons for each provider appear on the hosted login page alongside the magic-link option. End-user identities from social sign-in land in your _mdb_auth schema alongside magic-link users: same schema, same session model, same erasure semantics.

You supply your own OAuth app credentials from each provider. The platform stores the client_secret in the platform secret store and never returns it in any API response.

Register an OAuth app at the provider​

Before configuring a provider, create an OAuth application at the provider's developer console.

Google: Go to Google Cloud Console and create an OAuth 2.0 client. Set the application type to "Web application". Add the following to Authorized redirect URIs:

https://<your-issuer-host>/callback/google

GitHub: Go to GitHub Developer Settings and create a new OAuth App. Set the Authorization callback URL to:

https://<your-issuer-host>/callback/github

Replace <your-issuer-host> with your app's issuer host, for example auth-1a2b3c4d.foundrydb.com. You can find the issuer host in the fallback_domain field of GET /app-services/$APP_ID/auth.

Add a provider​

# Add Google
curl -u "$USER:$PASS" -X PUT \
  https://api.foundrydb.com/app-services/$APP_ID/auth/providers/google \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "1234567890-abcdef.apps.googleusercontent.com",
    "client_secret": "GOCSPX-...",
    "display_name": "Sign in with Google"
  }'

# Add GitHub
curl -u "$USER:$PASS" -X PUT \
  https://api.foundrydb.com/app-services/$APP_ID/auth/providers/github \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "Ov23li...",
    "client_secret": "...",
    "display_name": "Sign in with GitHub"
  }'

The display_name field is optional. When omitted, the login button label defaults to the provider name ("Google" or "GitHub").

The response returns the full list of configured providers after the operation. Secrets are never included:

{
  "providers": [
    {
      "provider": "google",
      "client_id": "1234567890-abcdef.apps.googleusercontent.com",
      "display_name": "Sign in with Google"
    }
  ]
}

When the auth configuration is Active, the issuer redeploys automatically to pick up the new credentials. If the configuration is not yet Active, the change is applied on the next deploy.

Update a provider​

Sending a PUT to a provider that is already configured replaces the credentials:

curl -u "$USER:$PASS" -X PUT \
  https://api.foundrydb.com/app-services/$APP_ID/auth/providers/google \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "new-client-id.apps.googleusercontent.com",
    "client_secret": "new-secret"
  }'

This is the same endpoint and same semantics as adding a provider. Rotate provider credentials here when you cycle secrets at the OAuth provider.

List configured providers​

curl -u "$USER:$PASS" \
  https://api.foundrydb.com/app-services/$APP_ID/auth/providers

Returns the configured provider list with client IDs and display names. Secrets are never returned.

Remove a provider​

curl -u "$USER:$PASS" -X DELETE \
  https://api.foundrydb.com/app-services/$APP_ID/auth/providers/google

The response returns the remaining configured providers. When the auth configuration is Active, the issuer redeploys automatically to remove the provider's button from the login page.

How social identities are stored​

When a user signs in with Google or GitHub for the first time, the platform creates:

  • A row in _mdb_auth.users with a UUID subject identifier
  • A row in _mdb_auth.identities linking the user to the provider and the provider's user ID

A single user row can fan out to several identities rows, one per sign-in method. The users row is the canonical identity; the identities rows are the credentials that point at it.

Account linking​

If a user signs in with a social provider using the same email address as an existing user, the platform links the new identity to the existing user record rather than creating a second account. Someone who first signed up by magic link and later clicks "Sign in with Google" on the same email keeps one account with two identities, and your application sees the same sub both times.

This linking is keyed on a verified email. Google and GitHub both assert whether the email on the account is verified, and the platform only links on an email the provider has verified. An unverified provider email is not treated as proof of ownership, which is what closes the account-takeover gap described below.

Account-takeover safety​

Naive email-based linking is a known account-takeover vector: an attacker registers an OAuth account at a provider using a victim's email address but never proves they own that mailbox, then uses social sign-in to land inside the victim's existing account. App Auth avoids this by linking only on a provider-verified email. If the provider reports the email as unverified, the platform does not merge into the existing user; the sign-in does not silently inherit the victim's account and data.

Because the same protection applies in reverse, encourage your users to enroll MFA on the account itself rather than relying on a single provider's security posture. MFA secrets live in _mdb_auth.mfa_totp and apply to the user, not to one identity, so they protect every sign-in method at once.

The sub claim in the JWT is always the _mdb_auth.users.id UUID, regardless of the sign-in method. Your application should use this UUID as the stable identifier for your users. Never key application records on the email address or on a provider's user ID, since a user can change their email or add and remove providers while the sub stays fixed.

Next steps​