# Magic Social Auth documentation > Social sign-in for Magic apps: native Google (iOS, Android) and Apple (iOS), and a backend-hosted browser flow for the rest. # Installation Social sign-in for Flutter apps built on the Magic Framework, against the `magic-starter-laravel` backend: native Google and Apple sheets on mobile, a backend-hosted browser flow (PKCE) for GitHub, Microsoft and everything else, on iOS, Android and web. - [Requirements](#requirements) - [Install the Package](#install-the-package) - [Run social:install](#run-socialinstall) - [What social:install Writes](#what-socialinstall-writes) - [Run social:doctor](#run-socialdoctor) - [Backend Environment](#backend-environment) - [Provider Consoles](#provider-consoles) - [Platform Notes](#platform-notes) - [Without magic_starter](#without-magic_starter) - [Manual Setup](#manual-setup) - [Verify the Installation](#verify-the-installation) - [Related Documentation](#related-documentation) ## Requirements | Dependency | Version | |:-----------|:--------| | Dart SDK | `^3.13.0` | | Flutter | `>=3.47.0` | | `magic` | `^1.0.0` | | `dowel` | `^1.0.0` | | `google_sign_in` | `^7.2.0` | | `sign_in_with_apple` | `^8.2.0` | | `flutter_web_auth_2` | `^5.1.0` | | `crypto` | `^3.0.8` | | Backend | `magic-starter-laravel` with the `social-login` feature on | The Dart and Flutter floors are inherited from `magic`. The backend side (routes, provider keys, the error codes) is documented in magic-starter-laravel's `doc/basics/social-login.md` and `doc/basics/account-deletion.md`; this package is its client and the two must agree on every value listed under [Backend Environment](#backend-environment). ## Install the Package Add the package, then run `plugin:install`. It registers the dowel commands (`social:install`, `social:doctor`) and adds `SocialAuthServiceProvider` to the providers list in `lib/config/app.dart`: ```bash flutter pub add magic_social_auth dart run magic:dowel plugin:install magic_social_auth ``` ## Run social:install One non-interactive run leaves the app ready to sign in. Replace the values with your own: ```bash dart run magic:dowel social:install \ --providers=google,apple,github,microsoft \ --google-ios-client-id=123-abc.apps.googleusercontent.com \ --google-server-client-id=123-def.apps.googleusercontent.com \ --ios-scheme=myapp \ --android-callback=https://auth.example.com/auth/social ``` Preview without writing anything: ```bash dart run magic:dowel social:install --dry-run ``` Every flag is optional; an omitted value is written as an empty string in the config and `social:doctor` names it until you fill it. ### Flags | Flag | Default | What it does | |:-----|:--------|:-------------| | `--providers=` | `google,apple,github,microsoft` | Comma-separated providers to enable. Each becomes `enabled: true` in the config, the rest `enabled: false`. An unknown name stops the run. Google and Apple only add their native iOS edits when they are in the list. | | `--google-ios-client-id=` | empty | The Google iOS OAuth client id (`123-abc.apps.googleusercontent.com`). Written to the config as `google.ios_client_id`; with `google` in `--providers` it is also written to `Info.plist` as `GIDClientID`, and its reversed form (`com.googleusercontent.apps.123-abc`) is registered as a URL scheme. | | `--google-server-client-id=` | empty | The Google web OAuth client id, the audience the backend verifies. Written to the config as `google.server_client_id`; with `google` in `--providers` it is also written to `Info.plist` as `GIDServerClientID`. | | `--ios-scheme=` | empty | The custom URL scheme the browser flow returns to on iOS (`myapp`). Written to the config as `callback.ios` = `myapp://auth/social`. A value that is not a URL scheme stops the run. | | `--android-callback=` | empty | The https App Link the browser flow returns to on Android (`https://auth.example.com/auth/social`). Written to the config as `callback.android` and declared as the `CallbackActivity` intent filter (host and path). Must be an https URL with a host and a path, without a query or fragment; use a host your app's other App Link filters do not claim (see [Android](#android)). | | `--force` | off | Overwrite files that were changed since the last install, or that the installer did not write. Without it such a file is reported as a conflict and the run exits 1. | | `--dry-run` | off | Print every staged operation and write nothing. | | `--non-interactive` | off | Inherited from every dowel install command. `social:install` asks no questions, so it changes nothing; it is safe to pass in CI. | | `--no-bootstrap` | off | Inherited from every dowel install command. `social:install` does not read it, and the post-install message is printed either way. | The Google client ids must look like `123-abc.apps.googleusercontent.com`; anything else stops the run before a file is touched. ## What social:install Writes | Target | Written when | Content | |:-------|:-------------|:--------| | `lib/config/app.dart` | always | `SocialAuthServiceProvider` is added to the providers list. | | `lib/config/social_auth.dart` | always | The config (see [Configuration](https://anilcancakir.com/magic/docs/social_auth/getting-started/configuration.md)), and `() => socialAuthConfig` is added to `Magic.init`'s `configFactories` in `lib/main.dart`. | | `ios/Runner/Info.plist` | `google` enabled and `--google-ios-client-id` given | `GIDClientID` and the reversed client id as a `CFBundleURLTypes` scheme. | | `ios/Runner/Info.plist` | `google` enabled and `--google-server-client-id` given | `GIDServerClientID`. | | Every entitlements file the iOS app target signs with | `apple` enabled | `com.apple.developer.applesignin` = `[Default]`, merged into any array the file already has. A project that signs with no entitlements file gets `ios/Runner/Runner.entitlements` and the target is pointed at it. | | `android/app/src/main/AndroidManifest.xml` | `--android-callback` given | The `com.linusu.flutter_web_auth_2.CallbackActivity` activity: `exported="true"`, `taskAffinity=""`, one `autoVerify` intent filter (`VIEW`, `DEFAULT`, `BROWSABLE`, scheme `https`, the callback's host and path). An existing activity with different filters is never rewritten; the install warns with the block it expected. | | `web/auth.html` | the project has a `web/` directory | The page the web popup posts its result back through. | | `lib/app/providers/social_auth_starter_service_provider.dart` | `magic_starter` is in `pubspec.yaml` | The bridge that plugs this package into the starter's screens, registered in `lib/config/app.dart`. | The browser flow's iOS custom scheme is not registered in `Info.plist`: the iOS web authentication session delivers the return only to the app that started it. The Android Google sign-in needs no manifest edit. ## Run social:doctor ```bash dart run magic:dowel social:doctor ``` Every way of getting the native half wrong is silent: a sign-in sheet that closes at once, a button that does nothing, a review rejection months later. The doctor reads `lib/config/social_auth.dart`, `Info.plist`, the entitlements files the app target signs with, `AndroidManifest.xml`, `web/` and the pubspec, and names what is missing. A section is printed only when the project has that platform. It exits 0 when every check passes and 1 otherwise. | Section | Checks | |:--------|:-------| | Config | The config exists; at least one provider is enabled; `google.ios_client_id` and `google.server_client_id` are set when Google is on; `callback.ios` is set when a browser-flow provider needs it on iOS; `callback.android` is set and is an https URL with a host and a path when a browser-flow provider needs it on Android. | | iOS | `Info.plist` has `GIDClientID`, `GIDServerClientID` and the reversed client id URL scheme; Sign in with Apple is in every entitlements file the app target signs with; Apple is not disabled while another provider is enabled (App Store guideline 4.8 asks an iOS app that offers another third-party sign-in to offer Sign in with Apple too). | | Android | The `CallbackActivity` is declared with `exported="true"`, `taskAffinity=""` and an `autoVerify` https filter for the callback; no other activity's App Link filter overlaps the callback. | | Web | `web/auth.html` exists and posts the `flutter-web-auth-2` message back to the app. | | magic_starter bridge | Only when `magic_starter` is a dependency: the bridge file exists and `SocialAuthStarterServiceProvider` is registered in `lib/config/app.dart`. | Without `lib/config/social_auth.dart` the doctor reports only the Config section. It cannot prove that an Android App Link verifies (Google fetches `assetlinks.json` at install time) or that a provider console lists the callback; those stay a device and a console check. ## Backend Environment After the checks, the doctor prints the `.env` lines of `magic-starter-laravel` that mirror your config, and the callback each provider console has to list. This is the shape (values come from your config; angle brackets are yours to fill): ``` Backend env (magic-starter-laravel) MAGIC_STARTER_SOCIAL_PROVIDERS=google,apple,github,microsoft MAGIC_STARTER_SOCIAL_IOS_REDIRECT=myapp://auth/social MAGIC_STARTER_SOCIAL_ANDROID_REDIRECT=https://auth.example.com/auth/social MAGIC_STARTER_SOCIAL_WEB_REDIRECT=https:///auth.html MAGIC_STARTER_SOCIAL_GOOGLE_AUDIENCES=123-abc.apps.googleusercontent.com,123-def.apps.googleusercontent.com MAGIC_STARTER_SOCIAL_APPLE_AUDIENCES= MAGIC_STARTER_APPLE_TEAM_ID= MAGIC_STARTER_APPLE_KEY_ID= MAGIC_STARTER_APPLE_PRIVATE_KEY= MAGIC_STARTER_APPLE_BUNDLE_ID= MAGIC_STARTER_APPLE_SERVICES_ID= https:///magic-starter/social/google/callback https:///magic-starter/social/apple/callback https:///magic-starter/social/github/callback https:///magic-starter/social/microsoft/callback ``` The Apple lines appear only when Apple is enabled, the Google audiences line only when Google is, and one callback URL is printed per enabled provider. - `MAGIC_STARTER_SOCIAL_IOS_REDIRECT` and `MAGIC_STARTER_SOCIAL_ANDROID_REDIRECT` must equal `social_auth.callback.ios` and `social_auth.callback.android` exactly. The backend takes the redirect target only from its own config, so a mismatch means the browser lands somewhere the app is not listening. - `MAGIC_STARTER_SOCIAL_WEB_REDIRECT` is the app's own `auth.html`, on the origin the web build is served from. - The Google audiences are the client ids whose ID tokens the backend accepts: the iOS client id and the web (server) client id. - The browser flow starts at `/auth/social/{provider}/redirect`, so the app's `network.drivers.api.base_url` has to be the backend's API base. ## Provider Consoles Register the fixed callback URL in every provider console. It does not use the backend's route prefix: ``` https:///magic-starter/social/{provider}/callback ``` | Provider | In the console | |:---------|:---------------| | Google | A **web** OAuth client with the callback as an authorised redirect URI; its client id is `--google-server-client-id`. An **iOS** OAuth client for the app's bundle id; its client id is `--google-ios-client-id`. An **Android** OAuth client for the app's package name and signing SHA-1. | | Apple | A **Services ID** with the callback as a return URL (the browser flow runs as this client, for Android and web). A **Sign in with Apple key** (`.p8`) for the Team ID and Key ID. The iOS app's capability for Sign in with Apple (the entitlement `social:install` writes). Optionally, `https:///magic-starter/social/apple/notifications` as the server-to-server notification endpoint. | | GitHub | An **OAuth app** whose authorisation callback URL is the callback. | | Microsoft | An **Entra app registration** with the **Web** platform and the callback as a redirect URI. The backend uses the `common` tenant unless `MICROSOFT_TENANT` says otherwise. | Client secrets and Apple's key live in the backend's environment, never in the Flutter app. See magic-starter-laravel's `doc/basics/social-login.md` for the `config/services.php` keys. ## Platform Notes ### iOS - Google and Apple sign in through their native sheets. GitHub and Microsoft open a web authentication session and return through the custom scheme from `--ios-scheme`. - The callback is a custom scheme on purpose: an https callback needs iOS 17.4. The session delivers the return only to the app that started it, so a custom scheme is safe. - Confirming an identity (the step-up) opens an ephemeral session, so the provider asks for the account again instead of waving a remembered one through. - Sign in with Apple hands out the user's name on the first authorisation only. `AppleSignInResult.givenName` and `familyName` carry it; pass them on to a profile update or they are lost. ### Android - Google signs in through the native SDK; Apple, GitHub and Microsoft use the browser flow. - The callback is an https App Link on a **dedicated host** (`auth.example.com`), not the app's main domain. The app's other App Link filters must not claim that host: when one does, Android may open that activity instead of the callback activity, and `social:doctor` flags the overlap. - The host must serve a Digital Asset Links file (`/.well-known/assetlinks.json`) for the app, since the filter is `autoVerify`. - An Auth Tab whose App Link verification failed closes at once and reports a plain cancel (flutter_web_auth_2 issue 215), so a cancel is not always the user's. The cancel copy invites a retry. - A misconfigured Google client (SHA-1, package name, `server_client_id`) is also reported as a cancel by the SDK. - The package never sets `preferEphemeral` on Android. ### Web - Every provider uses the browser flow in a popup. `web/auth.html` receives the callback inside the popup and posts it back to the app. - The popup must open from the tap itself: call `SocialAuth.driver(name).signIn()` straight from the tap handler, with no `await` before it. `SocialAuthButtons` calls `onPressed` synchronously for this reason. - Serve `auth.html` without a `Cross-Origin-Opener-Policy` header. A same-origin one can sever the popup's link to the app (`window.opener`); `auth.html` then falls back to writing the result to `localStorage`, which `flutter_web_auth_2` polls. - A new click supersedes a popup that is still pending; only the newest flow spends its code. ### macOS, Windows, Linux Not supported. `SocialAuth.supports(name)` answers `false` and `SocialAuthButtons` renders nothing for the provider. ## Without magic_starter The package works on its own: the drivers answer a `SocialAuthResult` and the app decides what a session, a 2FA challenge or a cancelled deletion means (see [Flows](https://anilcancakir.com/magic/docs/social_auth/basics/flows.md)). Without `magic_starter` there is no bridge, so the app owns one more thing: **sign Google out on its own sign-out.** The Google SDK keeps its own session; if it is not signed out, the next sign-in skips the account picker. The bridge does this for starter apps on every transition to signed-out. In an app without it: ```dart import 'dart:async'; import 'package:magic/magic.dart'; import 'package:magic_social_auth/magic_social_auth.dart'; void signGoogleOutOnSignOut() { Auth.stateNotifier.addListener(() { if (!Auth.check() && SocialAuth.supports('google')) { unawaited(SocialAuth.driver('google').signOut()); } }); } ``` Call the driver by name rather than `SocialAuth.signOut()`: the manager only signs out drivers it has cached in this process, and a session restored at boot has created none. The `SocialAuth.supports('google')` guard keeps the listener from throwing: `SocialAuth.driver('google')` throws `ProviderNotConfiguredException` when Google is disabled, while `supports()` answers `false` for a disabled or unsupported provider. On the web Google runs through a `RedirectDriver`, whose `signOut()` does nothing. ## Manual Setup `social:install` is the supported path. To wire it by hand, register the provider and the config factory, ```dart // lib/config/app.dart (app) => SocialAuthServiceProvider(app), ``` ```dart // lib/main.dart await Magic.init( configFactories: [ () => appConfig, () => socialAuthConfig, ], ); ``` and make the native edits listed under [What social:install Writes](#what-socialinstall-writes). `SocialAuthManager.createUser` delegates to `Auth.manager.createUser`, which uses the app's registered user factory. ## Verify the Installation ```dart import 'package:magic_social_auth/magic_social_auth.dart'; if (SocialAuth.supports('google')) { // Google is available on this platform. } ``` Then run `social:doctor` and sign in once per provider on a device. ## Related Documentation - [Configuration](https://anilcancakir.com/magic/docs/social_auth/getting-started/configuration.md): every `social_auth` key. - [Drivers](https://anilcancakir.com/magic/docs/social_auth/basics/drivers.md): the driver contract and the platform matrix. - [Flows](https://anilcancakir.com/magic/docs/social_auth/basics/flows.md): the browser and native token flows, errors and guarantees. - [Architecture overview](https://anilcancakir.com/magic/docs/social_auth/architecture/overview.md): how the manager, drivers and flow client fit together. - [Connected accounts in magic_starter](https://anilcancakir.com/magic/docs/starter/basics/connected-accounts): the starter screens the bridge feeds. --- # Configuration The `social_auth` config decides which providers are on, which Google client ids the native SDK uses, and where the browser flow returns to on each platform; `SocialAuthButtons` renders the enabled providers. - [Full Config Structure](#full-config-structure) - [Providers](#providers) - [Callbacks](#callbacks) - [UI Overrides](#ui-overrides) - [Button Widget](#button-widget) - [Keys Owned by Other Packages](#keys-owned-by-other-packages) - [Minimal Example](#minimal-example) - [Related Documentation](#related-documentation) ## Full Config Structure `social:install` writes the config to `lib/config/social_auth.dart`; every value is read at runtime through `Config.get`. This is what `social:install --providers=google,apple,github,microsoft --google-ios-client-id=123-abc.apps.googleusercontent.com --google-server-client-id=123-def.apps.googleusercontent.com --ios-scheme=myapp --android-callback=https://auth.example.com/auth/social` writes: ```dart // What `dart run magic:dowel social:doctor` checks, and the values it prints // for the backend: the callbacks below must equal the backend's // MAGIC_STARTER_SOCIAL_IOS_REDIRECT and MAGIC_STARTER_SOCIAL_ANDROID_REDIRECT. Map get socialAuthConfig => { 'social_auth': { 'providers': { 'google': { 'enabled': true, 'ios_client_id': '123-abc.apps.googleusercontent.com', 'server_client_id': '123-def.apps.googleusercontent.com', }, 'apple': { 'enabled': true, }, 'github': { 'enabled': true, }, 'microsoft': { 'enabled': true, }, }, 'callback': { 'ios': 'myapp://auth/social', 'android': 'https://auth.example.com/auth/social', }, }, }; ``` `social:doctor` reads this file back with a textual scan, so keep provider entries and `callback` flat maps of string and bool literals. ## Providers `social_auth.providers.` for `google`, `apple`, `github` and `microsoft`. | Key | Type | Default | Description | |:----|:-----|:--------|:------------| | `enabled` | `bool` | `true` | When `false`, `SocialAuthButtons` skips the provider and `SocialAuth.driver(name)` throws `ProviderNotConfiguredException`. | ### Google | Key | Type | Default | Description | |:----|:-----|:--------|:------------| | `ios_client_id` | `String` | none | The Google iOS OAuth client id. Read on iOS only (Android reads its client from the signing key). It must also be in `Info.plist` as `GIDClientID`; `social:install` writes both. | | `server_client_id` | `String` | none | The Google web OAuth client id. It is the audience of the ID token the backend verifies, so it must be in `MAGIC_STARTER_SOCIAL_GOOGLE_AUDIENCES`. Without it Google returns no ID token: the driver throws a `SocialAuthException` coded `sdk_error` and logs a message that names this key. | ### Apple, GitHub, Microsoft No keys beyond `enabled`. Their client ids and secrets live in the backend: the app only opens the sheet (Apple on iOS) or the backend's browser flow (everything else). ## Callbacks `social_auth.callback.` is where the backend sends the browser when a browser flow ends. It must equal the backend's redirect target for the same platform. | Key | Type | Backend env | Description | |:----|:-----|:------------|:------------| | `callback.ios` | `String` | `MAGIC_STARTER_SOCIAL_IOS_REDIRECT` | A custom scheme URL: `myapp://auth/social`. The scheme is what the app listens on. An https callback would need iOS 17.4. | | `callback.android` | `String` | `MAGIC_STARTER_SOCIAL_ANDROID_REDIRECT` | An https App Link: `https://auth.example.com/auth/social`. Its host and path become the Auth Tab's `httpsHost` and `httpsPath`, and the `CallbackActivity` intent filter. Use a dedicated host that no other App Link filter in the app claims. | There is no web key: the web flow lands on the app's own `/auth.html` (the backend's `MAGIC_STARTER_SOCIAL_WEB_REDIRECT`). A flow that needs a callback which is empty throws a `SocialAuthException` that names the key (`Set social_auth.callback.ios to the URL the backend redirects ios to.`). A callback is needed by GitHub and Microsoft on iOS and Android, and by Apple on Android. Google and Apple on iOS use native sheets, Google on Android does too, and the web needs no callback key. ## UI Overrides Read by `SocialAuthButtons` from each provider's entry. When omitted, the widget falls back to the built-in defaults. | Key | Type | Description | |:----|:-----|:------------| | `label` | `String` | Name shown on the button (`Google` becomes `Sign in with Google` through `auth.sign_in_with`). | | `icon_svg` | `String` | Raw SVG string for the icon. Overrides the built-in one. | | `icon_class` | `String` | Class applied to the icon element. Google and Microsoft default to `w-5 h-5`; GitHub and Apple default to `fill-slate-900 dark:fill-white`, a fill with no size. A value you set replaces the default instead of adding to it, so repeat the classes you still want. | | `order` | `int` | Rendering order, lower first. Built-in order is Google 1, Microsoft 2, GitHub 3, Apple 4. On iOS Apple is always first, as Apple's review guidelines expect. | > [!TIP] > For a custom provider registered with `SocialAuth.manager.extend()`, call `SocialAuth.manager.registerProviderDefaults()` instead of per-config overrides, so the defaults are available regardless of config state. ## Button Widget `SocialAuthButtons` renders one button per provider that is enabled and runs on this platform, in `order`, with Apple first on iOS. It renders nothing when no provider qualifies. It is built from Wind widgets, so it needs a `WindTheme` above it (`MagicApplication` provides one). ```dart import 'package:flutter/widgets.dart'; import 'package:magic_social_auth/magic_social_auth.dart'; Widget buildButtons({ required String? signingInWith, required void Function(String provider) onPressed, }) { return SocialAuthButtons( onPressed: onPressed, loadingProvider: signingInWith, mode: SocialAuthMode.signUp, labelBuilder: (provider, mode) => 'Continue with $provider', ); } ``` | Parameter | Type | Default | Description | |:----------|:-----|:--------|:------------| | `onPressed` | `void Function(String provider)` | required | Called synchronously from the tap with the config name (`google`). Start `SocialAuth.driver(provider).signIn()` here with no `await` before it, or a web popup is blocked. | | `loadingProvider` | `String?` | `null` | The provider whose flow is running: its button shows a spinner and the others are disabled. An empty string disables every button without a spinner; `null` leaves them all enabled. | | `mode` | `SocialAuthMode` | `SocialAuthMode.signIn` | `signIn` or `signUp`. Picks the label translation, `auth.sign_in_with` or `auth.sign_up_with`. | | `labelBuilder` | `String Function(String provider, SocialAuthMode mode)?` | `null` | Builds each label instead of the translation lookup. `provider` is the display label (`Google`, or the config `label`), not the config name. | | `className` | `String?` | `flex flex-col items-stretch` | Wind classes of the column that holds the buttons. A value replaces the default. | | `buttonClassName` | `String?` | a full-width, bordered card | Wind classes of every button. A value replaces the default, including the dimmed look of a disabled button, so repeat the classes you still want. | ## Keys Owned by Other Packages | Key | Owner | Used for | |:----|:------|:---------| | `network.drivers.api.base_url` | magic | The backend base URL. The browser flow starts at `/auth/social/{provider}/redirect`, and the native and exchange calls go through the same `Http` facade, so the auth interceptor attaches the bearer a connect or confirm needs. | | `auth.sign_in_with`, `auth.sign_up_with` | your app's translations | Button labels, with a `:provider` placeholder. | ## Minimal Example Google and GitHub only, no Apple. On a project with an `ios/` folder, `social:doctor` reports Apple as disabled against App Store guideline 4.8 and exits with code 1; the example is valid config, but an iOS app that ships it should enable Apple too. ```dart Map get socialAuthConfig => { 'social_auth': { 'providers': { 'google': { 'enabled': true, 'ios_client_id': '123-abc.apps.googleusercontent.com', 'server_client_id': '123-def.apps.googleusercontent.com', }, 'github': { 'enabled': true, }, }, 'callback': { 'ios': 'myapp://auth/social', 'android': 'https://auth.example.com/auth/social', }, }, }; ``` Register it in `Magic.init`: ```dart await Magic.init( configFactories: [ () => appConfig, () => socialAuthConfig, ], ); ``` > [!NOTE] > `social:doctor` fails an empty `callback.android` on an Android project as soon as GitHub is enabled, because GitHub signs in through the browser flow there. With only Google enabled the callbacks may stay empty on mobile, since Google signs in natively. ## Related Documentation - [Installation](https://anilcancakir.com/magic/docs/social_auth/getting-started/installation.md): `social:install` flags and `social:doctor` checks. - [Drivers](https://anilcancakir.com/magic/docs/social_auth/basics/drivers.md): which driver reads which key. - [Flows](https://anilcancakir.com/magic/docs/social_auth/basics/flows.md): how the callbacks are used by the browser flow. - [Architecture overview](https://anilcancakir.com/magic/docs/social_auth/architecture/overview.md): how the manager resolves a provider from this config. --- # Drivers A driver runs one provider's flow and answers what the backend concluded: it never logs the app in itself, it returns a `SocialAuthResult`. - [SocialDriver Contract](#socialdriver-contract) - [SocialAuthResult](#socialauthresult) - [Built-in Drivers](#built-in-drivers) - [Platform Support Matrix](#platform-support-matrix) - [Registering a Custom Driver](#registering-a-custom-driver) - [Gotchas](#gotchas) - [Related Documentation](#related-documentation) ## SocialDriver Contract `SocialAuthManager` resolves drivers by name and caches them for the lifetime of the app. The caller decides what a session, a 2FA challenge or a cancelled deletion means (see [Flows](https://anilcancakir.com/magic/docs/social_auth/basics/flows.md)). ```dart import 'package:magic_social_auth/magic_social_auth.dart'; Future useDriver(String currentPassword) async { final SocialDriver driver = SocialAuth.driver('github'); // Sign in await driver.signIn(); // Connect (mobile) await driver.connect({'password': currentPassword}); // Connect (web): prepare, then open from a second tap final Future Function() open = await driver.beginConnect({ 'password': currentPassword, }); // ...in the next tap handler: await open(); } ``` | Method | Backend intent | Answer carries | |:-------|:---------------|:---------------| | `signIn()` | `signin` | `token` and `user`, or `isTwoFactor` and `twoFactorToken`; `deletionCancelled` when the sign-in cancelled a scheduled deletion. | | `beginConnect(proof)` / `connect(proof)` | `connect` | `connectedProvider`. Needs the caller's bearer token. | | `confirm()` | `confirm` | `confirmationToken`, a single-use step-up proof. Needs the caller's bearer token. | | `signOut()` | none | Ends the provider SDK's own session; a no-op by default. | `proof` is the step-up field the account can give: `{'password': ...}`, `{'code': ...}` or `{'confirmation_token': ...}`; `null` for a guest, who sends none. It is minted for this one call; never cache or reuse it. `beginConnect` exists for the web. A connect needs a link ticket first, which is a network request; a popup opened after an `await` is blocked as not user-initiated. So `beginConnect` does everything that needs the network and returns the call that opens the provider before its own first `await`. Run it from a fresh tap (an explicit "Continue to GitHub" button) and the popup opens. `connect(proof)` is `beginConnect` followed by the opener in one go, for mobile. On the web a `signIn()` opens the popup in the same synchronous run as the call, so call it straight from the tap handler with no `await` before it. ## SocialAuthResult | Field | Type | Set by | |:------|:-----|:-------| | `token` | `String?` | A completed sign-in: the Sanctum token. | | `user` | `Map?` | A completed sign-in: the user resource. | | `isTwoFactor` | `bool` | A sign-in on an account with confirmed 2FA. | | `twoFactorToken` | `String?` | Same: finish at `auth/two-factor-challenge` with it. | | `deletionCancelled` | `bool` | A sign-in that cancelled a scheduled account deletion. | | `connectedProvider` | `String?` | A connect. | | `confirmationToken` | `String?` | A confirm. | `AppleSignInResult` extends it with `givenName` and `familyName`: Apple shares the name on the first authorisation only and never puts it in the ID token, so pass it on to a profile update or it is lost. ## Built-in Drivers The manager picks the driver that runs on the current platform. `SocialAuth.driver('google')` is a `GoogleDriver` on iOS and Android and a `RedirectDriver` on the web. ### GoogleDriver The native Google SDK (`google_sign_in`) on iOS and Android. The SDK's ID token is posted to `auth/social/google/token`, which verifies it. No nonce goes with it: the backend prohibits one for Google. - Config: `ios_client_id` (iOS only) and `server_client_id` (the ID token's audience). See [Configuration](https://anilcancakir.com/magic/docs/social_auth/getting-started/configuration.md#providers). - The SDK accepts one `initialize` per process, so every instance shares the first one. - `signOut()` signs the SDK out so the next sign-in offers the account picker again. - A cancelled sheet throws `SocialAuthCancelledException`. Android also reports a misconfigured client (SHA-1, package name, `server_client_id`) as cancelled. ### AppleDriver Sign in with Apple through the native sheet on iOS (`sign_in_with_apple`). Every sheet gets a fresh `Nonce`: Apple receives its lowercase sha256 hex and seals it into the ID token, the backend receives the raw value and checks the two match, so a token lifted from another sign-in is refused. The authorisation code goes along for the refresh token that account deletion revokes. The result is an `AppleSignInResult`. ### RedirectDriver Any provider through the backend's browser flow: GitHub and Microsoft everywhere, Apple on Android and the web, Google on the web. The app mints a PKCE pair, opens `/auth/social/{provider}/redirect`, receives a one-time code on the callback and trades it with the verifier at `auth/social/exchange`. See [Flows](https://anilcancakir.com/magic/docs/social_auth/basics/flows.md#browser-flow). ## Platform Support Matrix | Provider | iOS | Android | Web | |:---------|:----|:--------|:----| | Google | native SDK | native SDK | browser flow (popup) | | Apple | native sheet | browser flow | browser flow (popup) | | GitHub | browser flow | browser flow | browser flow (popup) | | Microsoft | browser flow | browser flow | browser flow (popup) | macOS, Windows and Linux are not supported: `SocialAuth.supports(name)` answers `false` there, and `SocialAuthButtons` omits the provider. ## Registering a Custom Driver The backend serves Google, Apple, GitHub and Microsoft. A custom driver is for a provider your own backend adds, or for a different way of running one of these. Extend `SocialDriver`, or reuse `RedirectDriver` for a provider the backend hosts a browser flow for: ```dart import 'package:magic_social_auth/magic_social_auth.dart'; SocialAuth.manager.extend( 'gitlab', (config) => RedirectDriver('gitlab', config), ); SocialAuth.manager.registerProviderDefaults( 'gitlab', const SocialProviderDefaults( label: 'GitLab', iconSvg: '...', order: 5, ), ); ``` Call `extend()` before the first `SocialAuth.driver('gitlab')`. It clears a cached instance of that name, so re-registering is safe. A custom driver is resolved after the `enabled` check, so `social_auth.providers.gitlab.enabled: false` still disables it. ## Gotchas | Mistake | Fix | |:--------|:----| | An `await` before `signIn()` on the web | The popup opens in the same synchronous run as the call, so call it straight from the tap handler. For a connect on the web, run `beginConnect` first and the returned opener from the next tap. | | Caching a `proof` map or a link ticket across attempts | Build the `proof` per call. Every connect mints a new PKCE pair, a new link ticket and a new proof. | | `SocialAuth.driver(name)` for a provider with `enabled: false` | It throws `ProviderNotConfiguredException`; an unknown name throws `ArgumentError`. Ask `SocialAuth.supports(name)` first, which answers `false` for both. | | A custom provider that never appears in `SocialAuthButtons` | The widget walks `social_auth.providers`, so the provider needs its own entry there as well as `extend()`. | | Sending a nonce for Google, or the raw nonce to Apple, from a custom driver on `SocialFlow.token` | Google takes none. Apple gets `Nonce.hashed` and the backend gets `Nonce.raw`. | | Dropping `AppleSignInResult.givenName` and `familyName` | Apple shares the name on the first authorisation only; hand it to a profile update straight away. | ## Related Documentation - [Flows](https://anilcancakir.com/magic/docs/social_auth/basics/flows.md): the browser flow, the native token flow, errors and guarantees. - [Configuration](https://anilcancakir.com/magic/docs/social_auth/getting-started/configuration.md): the keys each driver reads. - [Installation](https://anilcancakir.com/magic/docs/social_auth/getting-started/installation.md): `social:install` and `social:doctor`. - [Architecture overview](https://anilcancakir.com/magic/docs/social_auth/architecture/overview.md): how the manager, drivers and flow client fit together. --- # Flows Every provider ends at the same place: `magic-starter-laravel` answers a Sanctum token, or a two-factor challenge when the account confirmed 2FA, and this package hands the answer to the caller as a `SocialAuthResult` without ever logging the app in. - [Native Token Flow](#native-token-flow) - [Browser Flow](#browser-flow) - [Completing a Sign-In](#completing-a-sign-in) - [Connecting a Provider](#connecting-a-provider) - [Confirming an Identity](#confirming-an-identity) - [Account Deletion](#account-deletion) - [Signing Out](#signing-out) - [Errors](#errors) - [Guarantees](#guarantees) - [Gotchas](#gotchas) - [Related Documentation](#related-documentation) ## Native Token Flow There are two ways to reach the backend, and a driver picks one per provider and platform (see [Drivers](https://anilcancakir.com/magic/docs/social_auth/basics/drivers.md#platform-support-matrix)). Google (iOS, Android) and Apple (iOS) already hold an ID token after their native sheet, so the app skips the browser and posts it to `POST auth/social/{provider}/token` with an `intent` of `signin`, `connect` or `confirm`. - A provider access token is never sent: the backend accepts an ID token checked against its configured audiences. - Apple: the sheet gets the lowercase sha256 hex of a fresh nonce; the backend gets the raw nonce and the authorisation code. One nonce per sheet. - Google: no nonce at all. - The token is single use; a replayed one is refused. ## Browser Flow GitHub and Microsoft everywhere, Apple on Android and the web, Google on the web. Three steps, hosted by the backend: 1. **Redirect.** The app mints a PKCE pair and opens `GET /auth/social/{provider}/redirect?platform=&challenge=` in the system browser. A connect adds `ticket=`; a confirm adds `intent=confirm`. 2. **Callback.** The provider sends the browser to the backend's fixed callback, which sends it on to the app: `myapp://auth/social?code=...` on iOS, `https://auth.example.com/auth/social?code=...` on Android, the app's `auth.html` on the web. A refusal arrives as `?error=`. No token is ever placed in a URL. 3. **Exchange.** The app posts `{code, code_verifier}` to `POST auth/social/exchange`. The code is single use, bound to the PKCE challenge, and worthless without the verifier. On iOS the browser is a web authentication session; on Android an Auth Tab with `httpsHost` and `httpsPath` from `callback.android`; on the web a popup. ## Completing a Sign-In Without `magic_starter`, the app finishes the sign-in itself: ```dart import 'package:magic/magic.dart'; import 'package:magic_social_auth/magic_social_auth.dart'; Future signInWith(String provider) async { try { final SocialAuthResult result = await SocialAuth.driver(provider).signIn(); if (result.isTwoFactor) { // The account confirmed 2FA: finish at auth/two-factor-challenge with // result.twoFactorToken and the user's code. return; } await Auth.login( {'token': result.token}, SocialAuth.manager.createUser(result.user!), ); if (result.deletionCancelled) { // Signing in cancelled a scheduled account deletion: tell the user. } } on SocialAuthCancelledException catch (error) { // The user backed out, or another flow took the browser. if (!error.superseded) { // Offer a retry. } } on SocialAuthException catch (error) { // Switch on error.code, never on error.message. } } ``` On the web, call this straight from the tap handler: the provider popup has to open in the same synchronous run as the tap, so nothing may be `await`ed first. `SocialAuthButtons` calls `onPressed` synchronously for this reason. With Apple, check for `AppleSignInResult` to pick up `givenName` and `familyName`; they exist on the first authorisation only. `magic_starter` apps do not write any of this: the bridge `social:install` publishes feeds the result into the starter's login and registration completion, which handles 2FA, `Auth.login` and `deletion_cancelled`. ## Connecting a Provider A signed-in user links another provider to the account. A linked identity is a new way into the account, so the caller steps up first: | Account | Proof sent with the connect | |:--------|:----------------------------| | Has a password | `{'password': ...}` | | No password, 2FA confirmed | `{'code': }`, or a `confirmation_token` | | No password | `{'confirmation_token': ...}` from [confirming](#confirming-an-identity) a provider already linked | | Guest (`is_guest`, no password) | none (`null`) | ```dart import 'package:magic_social_auth/magic_social_auth.dart'; // Mobile: one call. Future connectOnMobile(String password) { return SocialAuth.driver('github').connect({'password': password}); } // Web: the link ticket is a network call, so open the popup from a second tap. Future Function()> prepareOnWeb(String password) { return SocialAuth.driver('github').beginConnect({'password': password}); } // ...in the next tap handler (an explicit "Continue to GitHub" button): Future continueOnWeb( Future Function() open, ) { return open(); } ``` The backend answers 422 `step_up_required` with `accepts` naming the proofs this account can send when no live proof came along. Every connect mints a new PKCE pair, a new link ticket and a new proof; nothing is cached across attempts. A link ticket is single use and expires after the backend's `link_ticket_ttl` (300 seconds by default). This package has no disconnect. Unlinking a provider (`DELETE user/social-accounts/{provider}`) and setting a first password (`POST user/password/set`) are backend calls that `magic_starter`'s own screens make, see [connected accounts](https://anilcancakir.com/magic/docs/starter/basics/connected-accounts) and [set password](https://anilcancakir.com/magic/docs/starter/basics/set-password). The backend refuses to remove the last sign-in method of a password-less account (`last_login_method`). ## Confirming an Identity A password-less account that is not a guest has no password to type for a sensitive action (deleting the account, removing a session, changing 2FA, linking a provider, setting a password). It re-authenticates with a provider it already linked: ```dart import 'package:magic_social_auth/magic_social_auth.dart'; Future confirmWithGoogle() async { final SocialAuthResult result = await SocialAuth.driver('google').confirm(); // Send it as {'confirmation_token': proof} to the gated call. return result.confirmationToken!; } ``` `confirm()` needs the caller's bearer token. The proof is single use and short lived (the backend's `confirmation_ttl`, 600 seconds by default). On iOS the browser session is ephemeral, so the provider asks for the account again instead of waving a remembered one through. A confirm for an identity that is not linked to the caller is refused with 403 `invalid_identity`. ## Account Deletion Deleting an account is scheduled, not immediate. `DELETE user` answers `202` with `data.deletion_scheduled_at`, revokes every token of the user at once, and the account is purged after a grace period (30 days by default). Signing in again, by any method, within the grace period cancels the deletion: the sign-in answer carries `deletion_cancelled: true`, which this package exposes as `SocialAuthResult.deletionCancelled`. The user resource carries `deletion_scheduled_at` so a client holding a token can tell a deletion is pending. ## Signing Out The Google SDK keeps its own session, so the next sign-in skips the account picker unless it is signed out. `GoogleDriver.signOut()` does it. `SocialAuth.signOut()` signs out every driver the manager has cached in this process, then clears the cache. A session restored at boot has created no driver, so sign Google out by name on every transition to signed-out: ```dart import 'package:magic_social_auth/magic_social_auth.dart'; Future signGoogleOut() async { // supports() is false when Google is disabled; driver() would throw // ProviderNotConfiguredException instead. if (SocialAuth.supports('google')) { await SocialAuth.driver('google').signOut(); } } ``` The bridge `social:install` publishes does this for `magic_starter` apps, listening to `Auth.stateNotifier`. An app without `magic_starter` has to do it on its own sign-out (see [Installation](https://anilcancakir.com/magic/docs/social_auth/getting-started/installation.md#without-magic_starter)). ## Errors | Exception | Meaning | |:----------|:--------| | `SocialAuthCancelledException` | The user closed the sheet, or another flow took the browser (`superseded` is `true`; the newer flow reports the outcome, so stay quiet). On Android an Auth Tab whose App Link verification failed also reports this, so the message invites a retry. | | `SocialAuthException` | A backend refusal. `code` is the backend's machine code (or the `error` a browser callback carried), `statusCode` the HTTP status, `message` a translated sentence. A failure of the SDK or the browser carries the code `sdk_error`. | | `UnsupportedPlatformException` | The browser flow does not run on this platform. | | `ProviderNotConfiguredException` | The provider has `enabled: false` in `social_auth.providers`. | Switch on `code`, never on `message`. The codes the backend sends: | Code | Meaning | |:-----|:--------| | `social_email_taken` | An account with this email exists. The owner signs in and connects the provider from their profile. | | `social_account_taken` | The provider account is linked to another user, or the caller already holds another account of that provider. | | `last_login_method` | The last sign-in method of a password-less account cannot be removed. | | `provider_not_supported` | Unknown provider, or not on the backend allowlist. | | `platform_not_configured` | No redirect target for the platform, or the provider is not configured. | | `flow_expired` | The state, code or ticket is unknown, expired or already used. | | `invalid_identity` | The provider's answer or ID token could not be verified. | | `provider_email_missing` | The provider returned no email for a new account. | | `password_already_set` | The account already has a password. | | `password_not_set` | The account has no password to change; set one instead. | | `step_up_required` | A sensitive action needs a `code` or `confirmation_token`. | | `provider_unavailable` | The provider's key set could not be fetched (503); retry later. | | `owns_shared_teams`, `team_has_active_subscription`, `subscription_active` | Account deletion refused. | ## Guarantees - Every browser flow mints a new PKCE pair (verifier of 64 characters from `A-Z a-z 0-9 - _`, challenge `base64url(sha256(verifier))`, 43 characters). Nothing is persisted. - One browser flow at a time on mobile: a second start while one is open throws `SocialAuthCancelledException(superseded: true)`. On the web a new click supersedes a pending popup, and only the newest flow spends its code. - A request that fails because of a missing redirect key names the key (`social_auth.callback.ios`) in its message. ## Gotchas | Mistake | Fix | |:--------|:----| | Reading a refusal from `SocialAuthException.message` | The backend translates it. Switch on `code`. | | Calling `Auth.login` with `result.token` when `result.isTwoFactor` is `true` | `token` and `user` are `null` on a challenged sign-in. Finish the 2FA challenge with `twoFactorToken` first. | | Treating every `SocialAuthCancelledException` as the user backing out | A failed Android App Link verification and a misconfigured Google client report the same cancel. Offer a retry, and stay quiet only when `superseded` is `true`. | | Relying on `SocialAuth.signOut()` to sign Google out after the app restarted | It only reaches drivers cached in this process. Sign Google out by name, behind `SocialAuth.supports('google')`, on every transition to signed-out. | | Looking for a disconnect method on a driver | There is none. Unlinking is the backend's `DELETE user/social-accounts/{provider}`, which `magic_starter`'s screens call. | | Starting a second mobile flow while one is open | It throws `SocialAuthCancelledException(superseded: true)`. Pass `SocialAuthButtons.loadingProvider` while a flow runs: it disables the other buttons. | ## Related Documentation - [Drivers](https://anilcancakir.com/magic/docs/social_auth/basics/drivers.md): the driver contract and the platform matrix. - [Configuration](https://anilcancakir.com/magic/docs/social_auth/getting-started/configuration.md): the callback keys the browser flow returns to and the `SocialAuthButtons` parameters. - [Installation](https://anilcancakir.com/magic/docs/social_auth/getting-started/installation.md): `social:install`, `social:doctor` and the backend values. - [Architecture overview](https://anilcancakir.com/magic/docs/social_auth/architecture/overview.md): how the flow client fits with the drivers. - [Connected accounts in magic_starter](https://anilcancakir.com/magic/docs/starter/basics/connected-accounts): the screens that link and unlink providers. --- # Architecture Overview `magic_social_auth` is the client half of `magic-starter-laravel`'s social login: a service provider registers a singleton manager, a static facade reaches it, and the manager dispatches to interchangeable driver objects while a flow client carries the wire protocol. - [Core Patterns](#core-patterns) - [Component Diagram](#component-diagram) - [Data Flow](#data-flow) - [IoC Integration](#ioc-integration) - [Extensibility Points](#extensibility-points) - [UI Layer](#ui-layer) - [The magic_starter Bridge](#the-magic_starter-bridge) - [Related Documentation](#related-documentation) ## Core Patterns | Pattern | Role | |:--------|:-----| | **ServiceProvider** | `SocialAuthServiceProvider` registers the `SocialAuthManager` singleton under `social_auth`; it is wired into `Magic.init` through the app's providers list. | | **Singleton Manager** | `SocialAuthManager` resolves and caches drivers, and picks the driver that runs on the current platform. | | **Driver (Strategy)** | `SocialDriver` subclasses (`GoogleDriver`, `AppleDriver`, `RedirectDriver`): one provider's way into the backend. | | **Flow client** | `SocialFlow` speaks the backend's protocol: browser redirect, exchange, link ticket, native token. Drivers compose it. | | **Facade** | `SocialAuth` is the static entry point, delegating to `Magic.make('social_auth')`. | ## Component Diagram ``` App ├─ SocialAuthButtons ── reads config, filters by platform + enabled flag └─ SocialAuth (facade) ── manager · driver(name) · supports(name) · signOut() │ SocialAuthManager (singleton) ├─ driver(name): enabled check → custom factory or built-in → cache ├─ extend(name, factory) · registerProviderDefaults(...) └─ signOut(): each cached driver.signOut(), then clear the cache │ SocialDriver (abstract) ── signIn · beginConnect · connect · confirm · signOut ├─ GoogleDriver native SDK on iOS/Android ──┐ ├─ AppleDriver native sheet on iOS ────────┤ SocialFlow.token() └─ RedirectDriver GitHub, Microsoft; Apple │ on Android/web; Google │ on web ──────────────────────┤ SocialFlow.signIn / authorize ▼ SocialFlow ── Pkce · Nonce · WebFlowSlot ├─ redirectUrl(): /auth/social/{provider}/redirect ├─ browse(): flutter_web_auth_2 (iOS session, Android Auth Tab, web popup) ├─ exchange(): POST auth/social/exchange {code, code_verifier} ├─ linkTicket(): POST user/social-accounts/link-ticket └─ token(): POST auth/social/{provider}/token │ magic Http facade ── auth interceptor attaches the bearer ``` Which driver runs is decided in `SocialAuthManager`: Google is native off the web, Apple is native on iOS, everything else is a `RedirectDriver`. A driver whose `supportedPlatforms` lacks the current platform answers `false` from `SocialAuth.supports(name)`. ## Data Flow Signing in with GitHub on Android, from tap to session: ``` 1. The user taps "Sign in with GitHub" SocialAuthButtons.onPressed('github') 2. The app calls: final result = await SocialAuth.driver('github').signIn() 3. SocialAuthManager.driver('github') - cache miss -> Config.get('social_auth.providers.github') -> enabled? -> RedirectDriver 4. RedirectDriver.signIn() -> SocialFlow.signIn('github') - Pkce.generate() new pair for this flow only - WebFlowSlot.claim() this flow owns the browser - FlutterWebAuth2.authenticate(...) Auth Tab on /auth/social/github/redirect ?platform=android&challenge= 5. Backend -> GitHub -> backend callback -> 302 to social_auth.callback.android with ?code= 6. SocialFlow.exchange(code, verifier) - POST auth/social/exchange {code, code_verifier} - SocialAuthResult.fromJson(answer) 7. The caller decides what the result means: - isTwoFactor -> challenge flow - otherwise Auth.login({'token': result.token}, createUser(result.user)) ``` The native token flow skips steps 4 to 6: the driver opens the SDK sheet and posts its ID token to `auth/social/{provider}/token`. ## IoC Integration `SocialAuthServiceProvider` registers the manager as a singleton in `register()`; its `boot()` has nothing to do. ```dart class SocialAuthServiceProvider extends ServiceProvider { @override void register() { app.singleton('social_auth', () => SocialAuthManager()); } } ``` The `SocialAuth` facade resolves it on every call: `Magic.make('social_auth')`. Config is read lazily when a driver is first resolved, so config can change between `Magic.init` and the first `SocialAuth.driver(...)`, which is useful in tests. ## Extensibility Points ### Custom drivers: `extend()` ```dart SocialAuth.manager.extend('gitlab', (config) => RedirectDriver('gitlab', config)); ``` Registers a factory for the name and clears a cached instance. Config is read from `social_auth.providers.gitlab`. The `enabled` flag is checked before the factory runs. ### Platform seams Each driver and `SocialFlow` expose the platform call as a `@visibleForTesting` member (`initializeSdk`, `nativeSignIn`, `requestCredential`, `authenticate`), and `SocialAuthManager.platformOverride` forces the platform. Tests stand in for the platform there instead of mocking a method channel. There is no handler seam. The package never creates a session: the caller owns `Auth.login`, which is what lets 2FA and a cancelled deletion complete properly. ## UI Layer `SocialAuthButtons` is a config-driven stateless widget. It never calls a driver; it calls the `onPressed(provider)` callback synchronously from the tap (a web popup needs that), so the parent decides what a press does. Resolution order for button metadata: ``` config['label'] / config['icon_svg'] / config['order'] ↓ fallback SocialProviderIcons.forProvider(name) ← registered via registerProviderDefaults() ↓ fallback Capitalised provider name, insertion-order index ``` Providers with `enabled: false`, and providers where `SocialAuth.supports(name)` is `false`, are omitted. On iOS Apple is always first. ## The magic_starter Bridge This package does not depend on `magic_starter`, and `magic_starter` does not depend on it. `magic_starter` declares a `MagicStarterSocialAuth` contract (`providers`, `label`, `icon`, `signIn`, `beginConnect`, `confirm`, `signOut`) and renders the buttons, the connected accounts page and the step-up dialog itself. `social:install` publishes `lib/app/providers/social_auth_starter_service_provider.dart` into the app, the one place that sees both packages. It implements the contract over `SocialAuth`, registers it with `MagicStarter.useSocialAuth`, translates every failure into the starter's own exception type (a cancel is marked, a refusal carries its `code`), and signs Google out when `Auth.stateNotifier` goes to signed-out. ## Related Documentation - [Installation](https://anilcancakir.com/magic/docs/social_auth/getting-started/installation.md): `social:install`, `social:doctor` and the backend values. - [Configuration](https://anilcancakir.com/magic/docs/social_auth/getting-started/configuration.md): the `social_auth` config keys. - [Drivers](https://anilcancakir.com/magic/docs/social_auth/basics/drivers.md): the driver contract and the platform matrix. - [Flows](https://anilcancakir.com/magic/docs/social_auth/basics/flows.md): the browser and native token flows, errors and guarantees. - [Connected accounts in magic_starter](https://anilcancakir.com/magic/docs/starter/basics/connected-accounts): the starter screens the bridge feeds.