Google sign-in

Sulu's OIDC slot supports Google out of the box. Once configured, users see a branded "Continue with Google" button on the Login and Register pages — alongside the standard email + password form. Both flows coexist; Google is an additional entry point.

This guide walks you through registering an OAuth 2.0 client with Google and pointing Sulu at it.

Prerequisites

• A Google Cloud project (free).
• Access to Sulu's environment configuration (whichever mechanism your deployment uses — .env, Helm values.yaml, Kubernetes secrets, etc.).
• The exact public URL of your Sulu installation, e.g. https://qa.acme.com. The redirect URI must be HTTPS in production.

1. Register the OAuth 2.0 client with Google

1. Open the Google Cloud Console and select or create a project.

2. Navigate to APIs & Services → OAuth consent screen. Configure the consent screen — at minimum, the app name, support email, and scopes openid, email, profile. No restricted scopes are needed.

3. Navigate to APIs & Services → Credentials → Create credentials → OAuth client ID.

4. Application type: Web application.

5. Authorised redirect URIs: add exactly:

   • https://<your-sulu-host>/api/auth/oauth2/code/sulu
   • (Optional, for local dev) http://localhost:8080/api/auth/oauth2/code/sulu

   The trailing /sulu is the OIDC client registration ID inside Sulu — it is fixed, not configurable.

6. Save. Google issues a Client ID and Client Secret. Copy both.

2. Configure Sulu

Set the following environment variables and restart the backend:

# Google sign-in (v1.6.0)
SULU_AUTH_OIDC_ENABLED=true
SULU_OIDC_ISSUER_URI=https://accounts.google.com
SULU_OIDC_CLIENT_ID=<your-client-id>.apps.googleusercontent.com
SULU_OIDC_CLIENT_SECRET=<your-client-secret>
SULU_OIDC_SCOPES=openid,email,profile
# SULU_OIDC_PROVIDER_LABEL is optional — Sulu defaults the label to "Google"
# automatically when the issuer is accounts.google.com.

Discovery doc reachability at boot

Sulu fetches https://accounts.google.com/.well-known/openid-configuration synchronously during backend startup. If your network blocks outbound to accounts.google.com (firewall, corporate proxy without explicit rules), the backend will fail to start. Verify outbound HTTPS connectivity from the Sulu host to Google before flipping the env var.

3. Verify

After restart, hit the preflight endpoint:

curl -sX POST https://<your-sulu-host>/api/auth/preflight | jq

You should see:

{
  "oidcEnabled": true,
  "oidcProviderLabel": "Google",
  "oidcProviderKind": "google",
  ...
}

Open /login in a browser. The branded "Continue with Google" button appears above the email + password form, separated by an "OR" divider.

What the flow looks like for users

1. User clicks Continue with Google.
2. Sulu redirects to accounts.google.com for authentication + consent.
3. Google redirects back to Sulu's callback. Sulu:
   • Verifies the email_verified=true claim (Google always sets this for valid accounts).
   • Looks up the user by email. If new, creates a Sulu account with name from the Google profile, no password (OIDC-only).
   • For a brand-new account, sends the user through onboarding to set up their own workspace. (Sulu does not auto-add new sign-ups to an existing workspace — workspace access is granted by invitation.)
4. Sulu issues an access token and sets the rotating sulu_refresh cookie (the same stateless JWT flow as email + password). Returning users land straight in the app; brand-new users start at onboarding.

Returning users sign in with one click — no password, no email verification.

What's not yet supported

• Hosted-domain restriction (hd=acme.com to lock the picker to a specific Google Workspace domain). Tracked as a follow-up; v1.6.0 accepts any Google account.
• Account picker for multi-account Google users. Google's default OAuth behaviour signs the user in with whichever account they used last — there's no picker without prompt=select_account. Tracked as a follow-up.
• Profile-page "Linked accounts" UI showing which provider a user signed in with.
• Multi-provider OIDC (Google + corporate SSO concurrent). Sulu supports one OIDC slot per installation.

Security model

• email_verified is the gate. Sulu auto-links a Google login to an existing email-matched Sulu account, but only when Google asserts the email is verified — which it does reliably for valid accounts.
• 2FA TOTP is bypassed on OIDC login. When a user with Sulu-side TOTP signs in via Google, Sulu trusts Google's MFA. To enforce 2FA on Google logins, enable mandatory MFA in your Google Workspace admin console.
• PKCE is enabled automatically by Spring Security for the confidential client created from Google's discovery doc.

See also

• The Stage 0 deployment runbook (internal docs/operations/stage-0-deployment-runbook.md) covers the broader env wiring for new installations.
• Authentication — overview of all auth methods, including LDAP/AD and TOTP 2FA.