Configuration

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:

// 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<String, dynamic> 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.<name> for google, apple, github and microsoft.

Google#

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.<platform> is where the backend sends the browser when a browser flow ends. It must equal the backend's redirect target for the same platform.

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.

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

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',
  );
}

Keys Owned by Other Packages#

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.

Map<String, dynamic> 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:

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

Related Documentation#

• Installation: social:install flags and social:doctor checks.
• Drivers: which driver reads which key.
• Flows: how the callbacks are used by the browser flow.
• Architecture overview: how the manager resolves a provider from this config.