[google_sign_in] Redesign API for current identity SDKs #9267
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| # Migrating from `google_sign_in` 6.x to 7.x | ||
|
|
||
| The API of `google_sign_in` 6.x and earlier was designed for the Google Sign-In | ||
| SDK, which has been deprecated on both Android and Web, and replaced with new | ||
| SDKs that have significantly different structures. As a result, the | ||
| `google_sign_in` API surface has changed significantly. Notable differences | ||
| include: | ||
| * `GoogleSignIn` is now a singleton, which is obtained via | ||
| `GoogleSignIn.instance`. In practice, creating multiple `GoogleSignIn` | ||
| instances in 6.x would not work correctly, so this just enforces an existing | ||
| restriction. | ||
| * There is now an explicit `initialize` step that must be called exactly once, | ||
| before any other methods. On some platforms the future will complete almost | ||
| immediately, but on others (for example, web) it may take some time. | ||
| * The plugin no longer tracks a single "current" signed in user. Instead, | ||
| applications that assume a single signed in user should track this at the | ||
| application level using the `authenticationEvents` stream. | ||
| * Authentication (signing in) and authorization (allowing access to user data | ||
| in the form of scopes) are now separate steps. Recommended practice is to | ||
| authenticate as soon as it makes sense for a user to potentially be signed in, | ||
| but to delay authorization until the point where the data will actually be | ||
| used. | ||
| * In applications where these steps should happen at the same time, you can | ||
| pass a `scopeHint` during the authentication step. On platforms that support | ||
| it this allows for a combined authentication and authorization UI flow. | ||
| Not all platforms allow combining these flows, so your application should be | ||
| prepared to trigger a separate authorization prompt if necessary. | ||
| * Authorization is further separated into client and server authorization. | ||
| Applications that need a `serverAuthCode` must now call a separate method, | ||
| `authorizeServer`, to obtain that code. | ||
| * Client authorization is handled via two new methods: | ||
| * `authorizationForScopes`, which returns an access token if the requested | ||
| scopes are already authorized, or null if not, and | ||
| * `authorizeScopes`, which requests that the user authorize the scopes, and | ||
| is expected to show UI. | ||
|
|
||
| Clients should generally attempt to get tokens via `authorizationForScopes`, | ||
| and if they are unable to do so, show some UI to request authoriaztion that | ||
| calls `authorizeScopes`. This is similar to the previously web-only flow | ||
| of calling `canAccessScopes` and then calling `addScopes` if necessary. | ||
| * `signInSilently` has been replaced with `attemptLightweightAuthentication`. | ||
| The intended usage is essentially the same, but the change reflects that it | ||
| is no longer guaranteed to be silent. For example, as of the publishing of | ||
| 7.0, on web this may show a floating sign-in card, and on Android it may show | ||
| an account selection sheet. | ||
| * This new method is no longer guaranteed to return a future. This allows | ||
| clients to distinguish, at runtime: | ||
| * platforms where a definitive "signed in" or "not signed in" response | ||
| can be returned quickly, and thus `await`-ing completion is reasonable, | ||
| in which case a `Future` is returned, and | ||
| * platforms (such as web) where it could take an arbitrary amount of time, | ||
| in which case no `Future` is returned, and clients should assume a | ||
| non-signed-in state until/unless a sign-in event is eventually posted to | ||
| the `authenticationEvents` stream. | ||
| * `authenticate` replaces the authentication portion of `signIn` on platforms | ||
| that support it (see below). | ||
| * The new `supportsAuthenticate` method allows clients to determine at runtime | ||
| whether the `authenticate` method is supported, as some platforms do not allow | ||
| custom UI to trigger explicit authentication. These platforms instead provide | ||
| some other platform-specific way of triggering authentication. As of | ||
| publishing, the only platform that does not support `authenticate` is web, | ||
| where `google_sign_in_web`'s `renderButton` is used to create a sign-in | ||
| button. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,182 +6,145 @@ A Flutter plugin for [Google Sign In](https://developers.google.com/identity/). | |
| |-------------|---------|-------|--------|-----| | ||
| | **Support** | SDK 21+ | 12.0+ | 10.15+ | Any | | ||
|
|
||
| ## Setup | ||
|
|
||
| ### Import the package | ||
|
|
||
| To use this plugin, follow the | ||
| [plugin installation instructions](https://pub.dev/packages/google_sign_in/install), | ||
| then follow the platform integration steps below for all platforms you support. | ||
|
|
||
| ### Platform integration | ||
|
|
||
| * **Android**: Please see [the `google_sign_in_android` README](https://pub.dev/packages/google_sign_in_android#integration). | ||
| * **iOS**: Please see [the `google_sign_in_ios` README](https://pub.dev/packages/google_sign_in_ios#ios-integration). | ||
| * **macOS**: Please see [the `google_sign_in_ios` README](https://pub.dev/packages/google_sign_in_ios#macos-integration) (which also supports macOS). | ||
| * **Web**: Please see [the `google_sign_in_web` README](https://pub.dev/packages/google_sign_in_web#integration). | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Initialization and authentication | ||
|
|
||
| Initialize the `GoogleSignIn` instance, and (optionally) start the lightweight | ||
| authentication process: | ||
|
|
||
| <?code-excerpt "example/lib/main.dart (Setup)"?> | ||
| ```dart | ||
| final GoogleSignIn signIn = GoogleSignIn.instance; | ||
| unawaited(signIn | ||
| .initialize(clientId: clientId, serverClientId: serverClientId) | ||
| .then((_) { | ||
| signIn.authenticationEvents.listen(_handleAuthenticationEvent); | ||
|
|
||
| /// This example always uses the stream-based approach to determining | ||
| /// which UI state to show, rather than using the future returned here, | ||
| /// if any, to conditionally skip directly to the signed-in state. | ||
| signIn.attemptLightweightAuthentication(); | ||
| })); | ||
| ``` | ||
|
|
||
| If the user isn't signed in by the lightweight method, you can show UI to | ||
| start a sign-in flow. This uses `authenticate` on platforms that return true | ||
| for `supportsAuthenticate`, otherwise applications should fall back to a | ||
| platform-specific approach. For instance, user-initiated sign in on web must | ||
| use a button rendered by the sign in SDK, rather than application-provided | ||
| UI: | ||
|
|
||
| <?code-excerpt "example/lib/main.dart (ExplicitSignIn)"?> | ||
| ```dart | ||
| if (GoogleSignIn.instance.supportsAuthenticate()) | ||
| ElevatedButton( | ||
| onPressed: () async { | ||
| try { | ||
| await GoogleSignIn.instance.authenticate(); | ||
| } catch (e) { | ||
| // ··· | ||
| } | ||
| }, | ||
| child: const Text('SIGN IN'), | ||
| ) | ||
| else ...<Widget>[ | ||
| if (kIsWeb) | ||
| web.renderButton() | ||
| // ··· | ||
| ] | ||
| ``` | ||
|
|
||
| ## Authorization | ||
|
|
||
| ### Checking if scopes have been granted | ||
|
|
||
| If the user has previously authorized the scopes required by your application, | ||
| you can silently request an access token for those scopes: | ||
|
|
||
| <?code-excerpt "example/lib/main.dart (CheckAuthorization)"?> | ||
| ```dart | ||
| const List<String> scopes = <String>[ | ||
| 'email', | ||
| 'https://www.googleapis.com/auth/contacts.readonly', | ||
| ]; | ||
| // ··· | ||
| GoogleSignInAccount? user; | ||
| // ··· | ||
| GoogleSignInClientAuthorization? authorization; | ||
| if (user != null) { | ||
| authorization = | ||
| await user.authorizationClient.authorizationForScopes(scopes); | ||
| } | ||
| ``` | ||
|
|
||
| [Full list of available scopes](https://developers.google.com/identity/protocols/googlescopes). | ||
|
|
||
| ### Requesting more scopes when needed | ||
|
|
||
| If an app determines that the user hasn't granted the scopes it requires, it | ||
| should initiate an Authorization request. On some platforms, such as web, | ||
| this request **must be initiated from an user interaction** like a button press. | ||
|
|
||
| <?code-excerpt "example/lib/main.dart (RequestScopes)"?> | ||
| ```dart | ||
| final GoogleSignInClientAuthorization authorization = | ||
| await user.authorizationClient.authorizeScopes(scopes); | ||
| ``` | ||
|
|
||
| ### Authorization expiration | ||
|
|
||
| In the web, **the `accessToken` is no longer refreshed**. It expires after 3600 | ||
|
There was a problem hiding this comment. 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? There was a problem hiding this comment. 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. There was a problem hiding this comment. Added a similar note in the authentication section, but pointing out that for authentication generally you should only need to use |
||
| seconds (one hour), so your app needs to be able to handle failed REST requests, | ||
| and update its UI to prompt the user for a new Authorization round. | ||
|
|
||
| This can be done by combining the error responses from your REST requests with | ||
| the authorization methods described above. | ||
|
|
||
| For more details, take a look at the | ||
| [`google_sign_in_web` package](https://pub.dev/packages/google_sign_in_web). | ||
|
|
||
| ### Requesting a server auth code | ||
|
|
||
| If your application needs to access user data from a backend server, you can | ||
| request a server auth code to send to the server: | ||
|
|
||
| <?code-excerpt "example/lib/main.dart (RequestServerAuth)"?> | ||
| ```dart | ||
| final GoogleSignInServerAuthorization? serverAuth = | ||
| await user.authorizationClient.authorizeServer(scopes); | ||
| ``` | ||
|
|
||
| Server auth codes are not always available on all platforms. For instance, on | ||
| some platforms they may only be returned when a user initially signs in, and | ||
| not for subsequent authentications via the lightweight process. If you | ||
| need a server auth code you should request it as soon as possible after initial | ||
| sign-in, and manage server tokens for that user entirely on the server side | ||
| unless the signed in user changes. | ||
|
|
||
| ## Example | ||
|
|
||
| The | ||
| [Google Sign-In example application](https://github.com/flutter/packages/blob/main/packages/google_sign_in/google_sign_in/example/lib/main.dart) demonstrates one approach to using this | ||
| package to sign a user in and authorize access to specific user data. | ||
|
|
||
| ## Migration from pre-7.0 versions | ||
|
|
||
| If you used version 6.x or earlier of `google_sign_in`, see | ||
| [the migration guide](https://github.com/flutter/packages/blob/main/packages/google_sign_in/google_sign_in/MIGRATION.md) | ||
| for more information about the changes. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'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'?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.