Setting up social login (Google & GitHub)

Social login lets users sign in with "Continue with Google" or "Continue with GitHub". Each provider is enabled independently by registering an OAuth app with them and giving Zynth Auth the resulting client ID and client secret. This is a one-time operator task.

A provider is enabled only when both its client ID and secret are set. A half-configured provider fails startup by design (so a typo can't silently disable it), and a provider with no credentials simply doesn't appear on the login page — no dead buttons.

The redirect URIs you'll need

Both providers must be told exactly where to send users back. Substitute your own host for auth.zynthmedia.com:

Provider	Authorized redirect URI
Google	https://auth.zynthmedia.com/api/v1/auth/social/google/callback
GitHub	https://auth.zynthmedia.com/api/v1/auth/social/github/callback

These must match character-for-character — a trailing slash or http vs https mismatch will cause the provider to reject every sign-in.

Google

1. In the Google Cloud Console, create or select a project.
2. Open Google Auth Platform (the OAuth consent configuration) and set the Audience to External — Internal restricts sign-in to your own Google Workspace organization, which is not what you want for end users.
3. Fill in Branding (app name, support email). You do not need to add openid or email under Data Access — they are default scopes the app requests automatically.
4. While the app is in Testing status, only accounts listed under Audience → Test users can sign in. Either add your testers there, or publish the app to production (instant, with no Google verification review, because only basic scopes are requested).
5. Under Clients → Create client → Web application, add the Google redirect URI from the table above, then copy the Client ID and Client secret.

Watch for a stray prefix. A Google client ID looks like 1234567890-abcdef.apps.googleusercontent.com — it must not begin with http://. Paste only the ID itself.

GitHub

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
2. Set Homepage URL to your app's URL and Authorization callback URL to the GitHub redirect URI from the table above.
3. Register the app, then generate a client secret. Copy the Client ID and the Client secret.

Configure Zynth Auth

Set these four values in your server environment (/opt/zynth/secrets/.env on a standard self-hosted deployment), then restart the API:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Restart, don't just reload. These are read at startup. On Docker Compose, a plain restart reuses the old environment — recreate the container so the new values load (e.g. docker compose ... up -d --force-recreate backend).

The redirect URIs Zynth Auth uses are derived from PUBLIC_BASE_URL, so make sure that is set to your public origin.

Verify it works

1. Check which providers are live (no auth required):

   GET /api/v1/auth/social/providers   →   {"providers": ["google", "github"]}
   

2. On the login page, the "Continue with Google/GitHub" buttons now appear (they render only for configured providers).
3. Complete a real sign-in with each. A brand-new user is provisioned as a customer only if the organization has customer self-sign-up enabled; otherwise sign-in requires an existing account whose email the provider has verified.

If a sign-in fails after the Google/GitHub consent screen, the usual cause is a mistyped client secret (the one value that can't be validated until an actual exchange). Double-check it was pasted without extra characters. See also Troubleshooting.