Installation

Requirements#

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.

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:

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:

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:

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#

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#

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#

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.

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://<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 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). 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:

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,

// 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. SocialAuthManager.createUser delegates to Auth.manager.createUser, which uses the app's registered user factory.

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 Documentation#

• Configuration: every social_auth key.
• Drivers: the driver contract and the platform matrix.
• Flows: the browser and native token flows, errors and guarantees.
• Architecture overview: how the manager, drivers and flow client fit together.
• Connected accounts in magic_starter: the starter screens the bridge feeds.