Installation

Requirements#

The Dart and Flutter floors come from sign_in_with_apple 8.2. The package depends on google_sign_in ^7.2.0, sign_in_with_apple ^8.2.0, flutter_web_auth_2 ^5.1.0 and crypto ^3.0.7.

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.

Install the Package#

Add magic_social_auth to your pubspec.yaml:

dependencies:
  magic_social_auth: ^0.0.11

Fetch dependencies, then register the package's artisan commands (social:install, social:doctor):

flutter pub get
dart run fluttersdk_artisan 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:

dart run <app>:artisan 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:

dart run <app>:artisan social:install --dry-run

<app> is your app's pubspec package name. 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#

The Google client ids must look like 123-abc.apps.googleusercontent.com; anything else stops the run before a file is touched.

Re-running with different flag values rewrites the files the installer created while you have not edited them. A file you edited is reported as a conflict, and --force overwrites it.

What social:install Writes#

The browser flow's iOS custom scheme is not registered in Info.plist: ASWebAuthenticationSession delivers the return only to the app that started it. The Android Google sign-in needs no manifest edit.

Run social:doctor#

dart run <app>:artisan 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.

The doctor 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://<app origin>/auth.html
  MAGIC_STARTER_SOCIAL_GOOGLE_AUDIENCES=123-abc.apps.googleusercontent.com,123-def.apps.googleusercontent.com
  MAGIC_STARTER_SOCIAL_APPLE_AUDIENCES=<ios bundle id>
  MAGIC_STARTER_APPLE_TEAM_ID=
  MAGIC_STARTER_APPLE_KEY_ID=
  MAGIC_STARTER_APPLE_PRIVATE_KEY=
  MAGIC_STARTER_APPLE_BUNDLE_ID=<ios bundle id>
  MAGIC_STARTER_APPLE_SERVICES_ID=
  https://<api host>/magic-starter/social/google/callback
  https://<api host>/magic-starter/social/apple/callback
  https://<api host>/magic-starter/social/github/callback
  https://<api host>/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 <network.drivers.api.base_url>/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://<api host>/magic-starter/social/{provider}/callback

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 ASWebAuthenticationSession and return through the custom scheme from --ios-scheme.
• The callback is a custom scheme on purpose: an https callback needs iOS 17.4. ASWebAuthenticationSession 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 authorization 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 Credential Manager; 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#

• All four providers use 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.
• Do not serve the app shell or auth.html with Cross-Origin-Opener-Policy: same-origin. It severs the popup's link to the app (window.opener), which is how the result gets back.
• 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). 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:

Auth.stateNotifier.addListener(() {
  if (!Auth.check()) {
    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. Guard the call to google being enabled and the platform being iOS or Android.

Manual Setup#

social:install is the supported path. To wire it by hand: register the provider and the config factory,

// lib/config/app.dart
(app) => SocialAuthServiceProvider(app),

// lib/main.dart
await Magic.init(
  configFactories: [
    () => appConfig,
    () => socialAuthConfig,
  ],
);

and make the native edits listed under What social:install Writes. SocialAuthServiceProvider must come after your auth provider, because SocialAuthManager.createUser delegates to Auth.manager.createUser.

Verify the Installation#

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

• Configuration reference
• Drivers
• Flows
• Architecture overview