[google_sign_in] Redesign API for current identity SDKs #9267

stuartmorgan-g · 2025-05-16T17:54:14Z

This is a full overhaul of the google_sign_in API, with breaking changes for all component packages—including the platform interface. The usual model of adding the new approach while keeping the old one is not viable here, as the underlying SDKs have changed significantly since the original API was designed. Web already had some only-partially-compatible shims for this reason, and Android would have had to do something similar; see flutter/flutter#119300 and flutter/flutter#154205, and the design doc for more background.

Fixes [google_sign_in] Rework google_sign_in to reflect changes in underlying SDKs flutter#119300
Fixes [google_sign_in] Switch Android to Credential Manager flutter#154205
Fixes [google_sign_in_web] Enable incremental authorization for Code Model. flutter#139406
Fixes [google_sign_in_android] Remove deprecated API usages in most recent version of play-services-auth flutter#150365
Fixes [google_sign_in_web] Remove deprecated signIn method. flutter#137727
Fixes [google_sign_in] Implement canAccessScopes on mobile flutter#124206
Fixes google_sign_in plugin links to obsolete documentation for web flutter#117794
Fixes [google_sign_in] Android documentation is wrong flutter#107532
Fixes [google_sign_in] Support passing a nonce flutter#85439
Fixes [google_sign_in] java.lang.NullPointerException: Attempt to read from field [...] on a null object reference flutter#74308
Fixes [google_sign_in] Add future that completes when the plugin is (really) ready. flutter#71607
Fixes [google_sign_in_web] googleSignIn.signIn() hangs forever if can't connect to apis.google.com flutter#70427
Fixes [google_sign_in] better error handling flutter#32441 (there may be more to do here over time, since we may find exceptions that are not caught, but we now have a structured system to convert errors to as we find specific unhandled cases)

Pre-Review Checklist

Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩² ↩³

Also reworks app-facing package example app for testing.

ditman

I don't think I have anything blocking. I took a look at google_sign_in, google_sign_in_platform_interface and google_sign_in_web.

ditman · 2025-05-22T01:31:43Z

packages/google_sign_in/google_sign_in/README.md

-  isAuthorized = await _googleSignIn.canAccessScopes(scopes);
-}
+const List<String> scopes = <String>[
+  'email',


'email' seems to me like an "old school" scope docs, maybe don't show it in this example, or replace by 'https://www.googleapis.com/auth/userinfo.email'?

Ah, I missed that this was an old/new API distinction. That helps explain https://github.com/flutter/packages/pull/9267/files#diff-30357d9348f31b88b886dbd8d3d1e036c8eb13adcbe360b5c997983520eeed9cR175-R176

Removed since we don't seem to need it. The auth UI still says it'll share name, email, and profile photo without it, so it was probably just redundant.

ditman · 2025-05-22T01:42:59Z

packages/google_sign_in/google_sign_in/README.md

-
-Once your app determines that the current user `isAuthorized` to access the
-services for which you need `scopes`, it can proceed normally.
-
 ### Authorization expiration

 In the web, **the `accessToken` is no longer refreshed**. It expires after 3600


Upon re-reading this... is this paragraph is a little bit incomplete? IIRC The authentication token (idToken) is also not refreshed, so both authorization and authentication end up expiring, right?

Looks that way. I can adjust the README accordingly, but maybe you just didn't mention it because normally (IIUC) clients don't need to keep using ID tokens they way they do access tokens.

Added a similar note in the authentication section, but pointing out that for authentication generally you should only need to use idToken when it's first received.

ditman · 2025-05-22T01:56:56Z

packages/google_sign_in/google_sign_in/example/lib/main.dart

+        user = event.user;
+      case GoogleSignInAuthenticationEventSignOut():
+        user = null;
+      case GoogleSignInAuthenticationEventException():


This is not specifically related to this example, but... why are we adding something that looks like an "error" event through the onData callback, instead of adding them as an error to the stream so they can be dealt with by a separate onError handler?

Adding an error to the stream also makes the case where the user is doing await stream.first throwy.

I think I just got carried away with structured error returns on iOS and Android. I'll revisit this for both layers of streams.

IMO I would only change the user-facing stream. In the implementation of the plugin we're already looking at the continuous stream of events coming from the platform code, so maybe the platform -> plugin stream can continue be a single one, with error events ("it never crashes") but the plugin -> app stream can emit errors normally? But yeah, if there's a benefit to making the platform -> plugin also emit errors, I won't oppose it changing :)

I changed the app-facing stream, but did end up leaving the platform interface version as-is, adding a comment to the stream method saying to always use the event instead of addError to enforce that they are supposed to always use structured errors instead of random PlatformExceptions and the like.

ditman · 2025-05-22T02:02:59Z

packages/google_sign_in/google_sign_in/example/lib/main.dart


 /// The scopes required by this application.
-// #docregion Initialize
+// #docregion CheckAuthorization
 const List<String> scopes = <String>[
  'email',


(Mentioned this in the readme above, but again, this 'email' scope might not be needed.)

ditman · 2025-05-22T02:03:42Z

packages/google_sign_in/google_sign_in/example/lib/main.dart

+        await user.authorizationClient.authorizationHeaders(scopes);
+    if (headers == null) {
+      setState(() {
+        _contactText = 'Failed to construct authorization headers.';


This should be _errorMessage, probably?

ditman · 2025-05-22T02:51:27Z

.../google_sign_in/google_sign_in_platform_interface/lib/google_sign_in_platform_interface.dart

@@ -27,134 +24,129 @@ abstract class GoogleSignInPlatform extends PlatformInterface {

  static final Object _token = Object();


Can we use this opportunity to clean up this _token and the set instance setter tricks and make the abstract class GoogleSignInPlatform an abstract base class? Should this be a separate technical debt cleanup issue? (Are there any downsides to this that I'm not seeing? :S)

I did seriously consider doing this, since it can only be done during a breaking change to the platform interface.

I may still tackle it here for that reason, but the downside is that I would have to replace the Mockito-generated mocks with manual mocks, and rewrite the tests accordingly.

the downside is that I would have to replace the Mockito-generated mocks with manual mocks, and rewrite the tests accordingly.

Ah yes...

Why is this change considered breaking, though? Is it just in case people are using "implements" for their own federated versions of the plugin, or mocks? If you're using the class "as intended" (with extends), your code shouldn't need to change by us moving it to base class. Would it?

One upside of the extra work, should you want to tackle it, is that the mocks that you create here can be distributed as a testing library from the package, so those users who were creating their own mocks can use officially maintained mock classes that we vend. Similar to: https://pub.dev/documentation/http/1.4.0/testing

Why is this change considered breaking, though? Is it just in case people are using "implements" for their own federated versions of the plugin, or mocks? If you're using the class "as intended" (with extends), your code shouldn't need to change by us moving it to base class. Would it?

True, it should only break tests in practice. We could probably consider it non-breaking for that reason, although forcing anyone currently doing mocking to completely rewrite their tests in a non-breaking change seems like more of a grey area than our usual policy for federated plugins that breaking test mocks isn't a breaking change.

the mocks that you create here can be distributed as a testing library from the package

I'm still on the fence about that approach for our plugins; it means we essentially have to maintain an extra implementation, taking feature requests for mocking scenarios that we don't care about ourselves.

packages/google_sign_in/google_sign_in_web/README.md

ditman · 2025-05-22T03:05:24Z

...ages/google_sign_in/google_sign_in_web/example/integration_test/google_sign_in_web_test.dart

-            .thenAnswer((_) => Future<GoogleSignInUserData>.value(someUser));
+    group('clientAuthorizationTokensForScopes', () {
+      const String someAccessToken = '50m3_4cc35_70k3n';
+      const List<String> scopes = <String>['scope1', 'scope2'];


Would it make sense to retain the 'asserts no scopes have any spaces' functionality and test here?

I was confused by the fact that the web implementation was asserting this in the first place. Is there some web-specific extra requirement on scopes? Is having spaces that shouldn't be there different from just typoing the scope?

This code comes from the first version of the plugin, and this is why I added this, when asked about "why not put this in the app-facing package":

flutter/plugins#2280 (comment)

[Spaces are] a problem here because we use the space as a "join" character to pass the scopes to JS. In the mobile versions, the List is preserved all the way through.

I just checked the API docs again, here: https://developers.google.com/identity/protocols/oauth2/javascript-implicit-flow#redirecting and scope is still "A space-delimited list of scopes that identify the resources that your application could access on the user's behalf."

IMO we should still assert (and test the assert) that scopes don't contain spaces, but it doesn't look like a super big source of problems.

Interesting; I'll put it back with a comment explaining it. I wonder if the mobile SDKs fail under the hood, or if they escape the spaces.

ditman · 2025-05-22T03:07:49Z

packages/google_sign_in/google_sign_in_web/example/integration_test/people_test.dart

@@ -52,7 +52,6 @@ void main() {
      expect(user.id, expectedPersonId);
      expect(user.displayName, expectedPersonName);
      expect(user.photoUrl, expectedPersonPhoto);
-      expect(user.idToken, isNull);


I thought we no longer did the People API fallback on the web? Maybe this whole test can be removed as well?

I think I did indeed just forget to delete these files.

ditman · 2025-05-22T03:16:43Z

packages/google_sign_in/google_sign_in_web/lib/src/gis_client.dart

@@ -12,7 +12,6 @@ import 'package:web/web.dart' as web;

 import 'button_configuration.dart'
    show GSIButtonConfiguration, convertButtonConfiguration;
-import 'people.dart' as people;


I think this people.dart file is now dead code, you can maybe delete it and its tests?

camsim99

Reviewed the Android implementation!

camsim99 · 2025-05-23T16:57:23Z

packages/google_sign_in/google_sign_in_android/lib/google_sign_in_android.dart

+  Future<PlatformGoogleIdTokenCredential?> _authenticate({
+    required bool filterToAuthorized,
+    required bool autoSelectEnabled,
+    required bool useButtonFlow,


So if useButtonFlow is true, then basically the other options are ignored? Would it be helpful to warn users here about that?

I've added a wrapper class at this layer and the Pigeon layer that encapsulate the options that are specific to the non-button flow, and also added some docs, to make things clearer.

I've reworked the API here and at the Pigeon layer to put the options specific to non-button-flow in a class, and added comments, to make it clearer what doesn't apply. (When I first wrote this code I didn't use the button flow, so the flat arguments made sense.)

Ok cool this is much clearer, thank you!

...ign_in_android/android/src/main/java/io/flutter/plugins/googlesignin/GoogleSignInPlugin.java

packages/google_sign_in/google_sign_in_android/lib/google_sign_in_android.dart

..._sign_in_android/android/src/test/java/io/flutter/plugins/googlesignin/GoogleSignInTest.java

camsim99 · 2025-05-23T21:25:51Z

..._sign_in_android/android/src/test/java/io/flutter/plugins/googlesignin/GoogleSignInTest.java

+        ResultCompat.asCompatCallback(
+            reply -> {
+              // This is never called, since this test doesn't trigger the getCredentialsAsync callback.
+              return null;


Nit: could throw an exception to ensure it's not called.

Added fail() to all of these, and adjusted the comment slightly to explain why.

..._sign_in_android/android/src/test/java/io/flutter/plugins/googlesignin/GoogleSignInTest.java

camsim99 · 2025-05-23T22:10:15Z

packages/google_sign_in/google_sign_in_android/README.md

@@ -13,3 +13,28 @@ should add it to your `pubspec.yaml` as usual.

 [1]: https://pub.dev/packages/google_sign_in
 [2]: https://flutter.dev/to/endorsed-federated-plugin
+
+## Integration


Can we consider linking to the credentials docs on this? https://developer.android.com/identity/sign-in/credential-manager-siwg#set-google for the non-firebase option? If it's more confusing than helpful because some steps don't apply, maybe not though.

By the time I was updating the READMEs I was so used to skipping down to the code on that page I forgot it had setup instructions! I've adjusted to link to that as the non-Firebase option, and removed some of the details since they are covered more thoroughly there.

Hahaha totally understandable! LGTM!

camsim99

The Android implementation LGTM!

camsim99 · 2025-06-02T16:14:00Z

packages/google_sign_in/google_sign_in_android/lib/google_sign_in_android.dart

+  Future<PlatformGoogleIdTokenCredential?> _authenticate({
+    required bool filterToAuthorized,
+    required bool autoSelectEnabled,
+    required bool useButtonFlow,


Ok cool this is much clearer, thank you!

camsim99 · 2025-06-02T16:27:54Z

packages/google_sign_in/google_sign_in_android/README.md

@@ -13,3 +13,28 @@ should add it to your `pubspec.yaml` as usual.

 [1]: https://pub.dev/packages/google_sign_in
 [2]: https://flutter.dev/to/endorsed-federated-plugin
+
+## Integration


Hahaha totally understandable! LGTM!

stuartmorgan-g added 20 commits May 15, 2025 11:11

Initial PoC using CredentialManager

432a627

Pathify everything for local development

df1cf87

Remove method channel implementation

6a1ec7c

First pass rework of interface, impls, and app-facing API

49342c5

Also reworks app-facing package example app for testing.

Add nonce support

eba7a8b

Initial README updates and migration guide

f3d472f

Rework Android calls to match recommended practice

728a4f9

Synthesize sign-out event for disconnect

c165834

platform interface tests

dba0f3e

Simplify Android Pigeon API

83c7b1d

Android Dart unit tests

82c0530

iOS Dart unit tests

4123b18

Web Dart 'unit' tests, and fix lightweight auth return

165fb78

Update example apps

eda66bb

Update native unit tests, fix an Obj-C selector name

21635a0

Update to recent 1.5 release

39b7505

Android native unit tests

07fe543

README, CHANGELOG, and version updates

e6c9f62

App-facing Dart tests

90a63aa

Revert unrelated Xcode project changes

816f614

stuartmorgan-g requested review from LongCatIsLooong, cbracken, camsim99 and ditman as code owners May 16, 2025 17:54

github-actions bot added p: extension_google_sign_in_as_googleapis_auth p: google_sign_in platform-android platform-ios platform-macos platform-web labels May 16, 2025

Update excerpting

e786998

stuartmorgan-g added the override: allow breaking change Override the check preventing breaking changes to platform interfaces label May 19, 2025

ditman reviewed May 22, 2025

View reviewed changes

Merge branch 'main' into google-sign-in-authn-authz-redesign

78602e8

camsim99 reviewed May 23, 2025

View reviewed changes

stuartmorgan-g added 12 commits May 27, 2025 12:30

Merge branch 'main' into google-sign-in-authn-authz-redesign

8783b72

Remove email scope

7140fd0

Web README additions

5a587b4

Update stream error handling, update main example

5f78e10

Fix lightweight auth null return, and add missing tests

a6036b8

Re-add web asserts for scope spaces

9c9923c

Remove unused People code

b44ff39

Restructure options slightly

8640443

Add TODO issue link

86a7a1d

Add activity lifecycle tests

4fb7fea

Add authorize param tests

563680c

Test safety check, better README

dab117f

stuartmorgan-g requested a review from ash2moon as a code owner May 29, 2025 02:07

stuartmorgan-g requested review from camsim99 and ditman May 29, 2025 02:07

stuartmorgan-g added 4 commits May 29, 2025 08:25

Analyzer

81f59f7

Java autoformat

6b76be0

excerpt update

9817325

Add stack traces to stream errors

20a8fc5

stuartmorgan-g added the triage-ios Should be looked at in iOS triage label May 29, 2025

stuartmorgan-g added 4 commits May 29, 2025 11:24

Handle emulators without sign-in support

d6bd8bc

Add another missing stack

6766860

Rework the stream tests to make wasm happy

8ad0051

Merge branch 'main' into google-sign-in-authn-authz-redesign

9fe4f32

camsim99 approved these changes Jun 2, 2025

View reviewed changes

		@@ -27,134 +24,129 @@ abstract class GoogleSignInPlatform extends PlatformInterface {

		static final Object _token = Object();

[google_sign_in] Redesign API for current identity SDKs #9267

Are you sure you want to change the base?

[google_sign_in] Redesign API for current identity SDKs #9267

Conversation

stuartmorgan-g commented May 16, 2025

Pre-Review Checklist

Footnotes

Uh oh!

ditman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camsim99 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!