docs: Update Google Sign-In setup and configuration documentation

docs/06-concepts/11-authentication/04-providers/03-google/02-configuration.md → docs/06-concepts/11-authentication/04-providers/03-google/02-customizations.md

@@ -1,14 +1,25 @@
-# Configuration
+# Customizations
 
-This page covers configuration options for the Google identity provider beyond the basic setup.
+This page covers additional configuration options for the Google identity provider beyond the basic setup.
 
 ## Configuration options
 
 Below is a non-exhaustive list of some of the most common configuration options. For more details on all options, check the `GoogleIdpConfig` in-code documentation.
 
-### Loading Google Client Secret
+The Google identity provider can be configured using one of two classes:
 
-You can load the Google client secret in several ways:
+- **`GoogleIdpConfigFromPasswords`**: Automatically loads the client secret from the `googleClientSecret` key in `passwords.yaml` (or the `SERVERPOD_PASSWORD_googleClientSecret` environment variable). This is the class used in the [setup guide](./setup) and is recommended for most projects.
+- **`GoogleIdpConfig`**: Requires you to pass a `GoogleClientSecret` object directly. Use this when you need to load credentials from a custom source, such as a JSON file, a secrets manager, or a programmatically constructed map.
+
+`GoogleIdpConfigFromPasswords` is a convenience wrapper around `GoogleIdpConfig` that handles credential loading for you.
+
+Both classes accept the same optional callbacks shown in the sections below. The examples on this page use `GoogleIdpConfigFromPasswords` unless the section specifically demonstrates manual client secret loading.
+
+### Load the client secret using GoogleIdpConfig
+
+When using `GoogleIdpConfig`, you must provide the client secret explicitly. 
+
+You can load the secret in several ways:
 
 **From JSON string (recommended for production):**
 
@@ -39,7 +50,7 @@ final googleIdpConfig = GoogleIdpConfig(
       'client_id': 'your-client-id.apps.googleusercontent.com',
       'client_secret': 'your-client-secret',
       'redirect_uris': [
-        'http://localhost:8080/auth/google/callback',
+        'http://localhost:8082',
       ],
     },
   }),
@@ -70,7 +81,7 @@ The default setup allows access to basic user information, such as email, profil
 - Add the required scopes to the [Data Access](./setup#configure-google-auth-platform) page in the Google Auth Platform.
 - Request access to the scopes when signing in. Do this by setting the `scopes` parameter of the `GoogleSignInWidget` or `GoogleAuthController`.
 
-A full list of available scopes can be found [here](https://developers.google.com/identity/protocols/oauth2/scopes).
+For a full list of available scopes, see the [Google OAuth 2.0 Scopes reference](https://developers.google.com/identity/protocols/oauth2/scopes).
 
 :::info
 Adding additional scopes may require approval by Google. On the OAuth consent screen, you can see which of your scopes are considered sensitive.
@@ -101,33 +112,43 @@ final googleIdpConfig = GoogleIdpConfigFromPasswords(
 );
 ```
 
-### Reacting to account creation
+### Reacting to auth user creation
 
-You can use the `onAfterGoogleAccountCreated` callback to run logic after a new Google account has been created and linked to an auth user. This callback is only invoked for new accounts, not for returning users.
+The `onBeforeAuthUserCreated` and `onAfterAuthUserCreated` hooks are global callbacks configured on `AuthUsersConfig` in `initializeAuthServices`. They are not specific to Google -- they fire for every identity provider. See the [working with users](../../working-with-users#reacting-to-the-user-created-event) page for full details.
 
-This callback is complimentary to the [core `onAfterAuthUserCreated` callback](../../working-with-users#reacting-to-the-user-created-event) to perform side-effects that are specific to a login on this provider - like storing analytics, sending a welcome email, or storing additional data.
+`onBeforeAuthUserCreated` receives the default scopes and blocked status for the new user and must return the final values. Use it to assign custom scopes at creation time:
 
 ```dart
-final googleIdpConfig = GoogleIdpConfigFromPasswords(
-  onAfterGoogleAccountCreated: (
-    session,
-    authUser,
-    googleAccount, {
-    required transaction,
-  }) async {
-    // e.g. store additional data, send a welcome email, or log for analytics
-  },
+pod.initializeAuthServices(
+  tokenManagerBuilders: [
+    JwtConfigFromPasswords(),
+  ],
+  identityProviderBuilders: [
+    GoogleIdpConfigFromPasswords(),
+  ],
+  authUsersConfig: AuthUsersConfig(
+    onBeforeAuthUserCreated: (
+      session,
+      scopes,
+      blocked, {
+      required transaction,
+    }) {
+      return (
+        scopes: {...scopes, Scope('user')},
+        blocked: blocked,
+      );
+    },
+    onAfterAuthUserCreated: (
+      session,
+      authUser, {
+      required transaction,
+    }) async {
+      // e.g. send a welcome email, log for analytics
+    },
+  ),
 );
 ```
 
-:::info
-This callback runs inside the same database transaction as the account creation. Throwing an exception inside this callback will abort the process. If you perform external side-effects, make sure to safeguard them with a try/catch to prevent unwanted failures.
-:::
-
-:::caution
-If you need to assign Serverpod scopes based on provider account data, note that updating the database alone (via `AuthServices.instance.authUsers.update()`) is **not enough** for the current login session. The token issuance uses the in-memory `authUser.scopes`, which is already set before this callback runs. You would need to update `authUser.scopes` as well for the scopes to be reflected in the issued tokens. For assigning scopes at creation time, consider using `onBeforeAuthUserCreated` in combination with `getExtraGoogleInfoCallback` to fetch and store the data you need before the auth user is created.
-:::
-
 ### Lightweight Sign-In on the Flutter app
 
 Lightweight sign-in is a feature that attempts to authenticate users previously logged in with Google automatically with minimal or no user interaction. When enabled, the Google authentication controller will try to sign in users seamlessly using platform-specific lightweight authentication methods. This feature is disabled by default, but can be enabled from the `GoogleSignInWidget` or `GoogleAuthController`.
@@ -194,3 +215,11 @@ This approach is useful when you need to:
 :::tip
 You can also set these environment variables in your IDE's run configuration or CI/CD pipeline to avoid passing them manually each time.
 :::
+
+## GoogleIdpConfig parameter reference
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `clientSecret` | `GoogleClientSecret` | Yes | The Google OAuth client secret loaded from JSON. Can be loaded via `fromJsonString`, `fromJsonFile`, or `fromJson`. |
+| `googleAccountDetailsValidation` | `GoogleAccountDetailsValidation?` | No | Custom validation callback for Google account details before allowing sign-in. Throws an exception to reject the account. |
+| `getExtraGoogleInfoCallback` | `GetExtraGoogleInfoCallback?` | No | Callback that receives the access token after sign-in, allowing you to call additional Google APIs and store extra user data. |

docs/06-concepts/11-authentication/04-providers/03-google/03-customizing-the-ui.md

@@ -15,6 +15,7 @@ SignInWidget(
   ),
 )
 ```
+
 :::
 
 ## Using the `GoogleSignInWidget`