Configure Google OAuth2 login

Before you begin

Decide the public, HTTPS URL that users use to reach SoloDB. Google requires an exact redirect URI. For an installation at https://solodb.example, the URI is:

Do not use a local, HTTP, or trailing-slash variant in production. The URL in Google Cloud and the SoloDB OAuth2 service must match character for character.

Create the Google credentials

1. In Google Cloud Console, select or create the project that will own the integration.

2. Configure the OAuth consent screen (via All Products > Management > Google Auth Platform, or use the search function). Choose Internal for a Google Workspace-only application, or External when users outside that Workspace must be able to sign in. Add test users while an External app is still in testing.

3. Create an OAuth client ID of type Web application.

4. Add the SoloDB callback URL under Authorized redirect URIs. Do not add it only as an authorized JavaScript origin.

5. Copy the generated Client ID and Client secret. Store the secret in the SoloDB admin UI only; do not commit it to host configuration or source control.

Google’s standard openid, email, and profile scopes are sufficient. They request the stable Google subject, verified email address, and the user’s display name.

Configure SoloDB

Complete these steps as a SoloDB administrator:

1. Open Admin → OAuth2 → Scopes and create a scope whose value is exactly:

   openid email profile

2. Open Admin → OAuth2 → Services and create a new Google service. Enter its name, Client ID, Client secret, redirect URL, and the scope created in the previous step. SoloDB supplies Google’s authorization, token, and UserInfo endpoints; do not enter them manually.

3. Open Admin → Authentication and create an authentication method of type OAuth2. Select the Google service, choose a clear button label such as Sign in with Google, and set the allowed domains.

4. Set Whitelisted domains to * to allow any verified Google email address, or enter a comma- or line-separated list such as example.com, subsidiary.example to restrict access. The check is enforced after Google has returned the account profile.

5. Activate the authentication method and use the new button on /login.html to test the complete flow.

On a first successful Google login, SoloDB creates a user from the returned profile and stores the account's stable Google subject identifier. Later logins use that identifier, so an email-address change does not create a second user. An existing SoloDB user with the same verified email address is linked on the first Google login. Configure roles and any application-specific permissions in SoloDB as usual.

Troubleshooting and maintenance

• redirect_uri_mismatch means the redirect URI is not identical in Google Cloud and SoloDB. Verify the scheme, host, path (/oauth2/callback.html), port, and trailing slash.

• An error that the domain is not allowed means the Google email address does not match the Authentication record’s whitelisted domains. Add the domain or use the intended Google account.

• Google must return a verified email address. Ensure the service scope remains openid email profile.

• For an External consent screen in testing, add every test account under Google Cloud’s test users. Publish the consent screen when the intended audience is ready.

• Rotate a compromised or expiring client secret in Google Cloud, then use the OAuth2 service’s Update client secret action in SoloDB. Test sign-in before removing the previous secret where Google allows overlap.

For Google Workspace, selecting Internal on the consent screen limits authorization to accounts in that Workspace. Keep SoloDB’s whitelisted-domain check as a separate, application-side safeguard; it filters the returned email domain, not Workspace organization membership.