Magic Logo

Magic Social Auth

Laravel Socialite-style social authentication for the Magic Framework.
Config-driven OAuth with extensible drivers for Google, Microsoft, GitHub, and beyond.

pub.dev version CI Status License: MIT pub points GitHub Stars

Website · Docs · pub.dev · Issues · Discussions

Alpha — magic_social_auth is under active development. APIs may change between minor versions until 1.0.0.

Why Magic Social Auth?

Adding social login to a Flutter app means juggling platform-specific SDKs, OAuth redirect flows, token exchange with your backend, and wiring it all together differently for each provider. Every project reinvents the same boilerplate.

Magic Social Auth gives you a Socialite-style facade. One config file declares your providers. One line authenticates. Drivers handle platform differences. A pluggable handler chain sends tokens to your backend.

Config-driven social auth. Define your providers, credentials, and scopes once. Magic Social Auth handles the rest.

Features

Feature Description
:key: Socialite-Style API SocialAuth.driver('google').authenticate() — familiar, expressive
:busts_in_silhouette: Built-in Drivers Google (native SDK), Microsoft (OAuth), GitHub (OAuth) out of the box
:electric_plug: Extensible Drivers Add any provider via manager.extend('apple', factory)
:arrows_counterclockwise: Custom Auth Handlers Swap the default HTTP handler for Firebase, Supabase, or anything else
:iphone: Platform Detection Drivers declare supported platforms — check with SocialAuth.supports()
:art: Config-Driven UI SocialAuthButtons widget renders enabled providers with icons automatically
:door: Sign-Out Support SocialAuth.signOut() clears cached sessions across all providers
:package: Service Provider Two-phase bootstrap via Magic's IoC container — zero manual wiring

Quick Start

1. Add the dependency

dependencies:
  magic_social_auth: ^0.0.1-alpha.1

2. Register the service provider

// lib/config/app.dart
import 'package:magic_social_auth/magic_social_auth.dart';

Map<String, dynamic> get appConfig => {
  'app': {
    'providers': [
      // ... other providers
      (app) => SocialAuthServiceProvider(app),
    ],
  },
};

3. Create the config file

// lib/config/social_auth.dart
import 'package:magic/magic.dart';

Map<String, dynamic> get socialAuthConfig => {
  'social_auth': {
    'endpoint': '/auth/social/{provider}',
    'providers': {
      'google': {
        'enabled': true,
        'client_id': env('GOOGLE_CLIENT_ID'),
        'server_client_id': env('GOOGLE_SERVER_CLIENT_ID'),
        'scopes': ['email', 'profile'],
      },
      'microsoft': {
        'enabled': true,
        'client_id': env('MICROSOFT_CLIENT_ID'),
        'tenant': env('MICROSOFT_TENANT', 'common'),
        'callback_scheme': 'myapp',
        'scopes': ['openid', 'profile', 'email'],
      },
      'github': {
        'enabled': true,
        'client_id': env('GITHUB_CLIENT_ID'),
        'callback_scheme': 'myapp',
        'scopes': ['read:user', 'user:email'],
      },
    },
  },
};

4. Register config in main.dart

// lib/main.dart
import 'config/social_auth.dart';

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

5. Authenticate

await SocialAuth.driver('google').authenticate();

That's it — the default HttpSocialAuthHandler sends the token to your Laravel backend and logs the user in via Sanctum.

Configuration

The config file at lib/config/social_auth.dart controls everything:

Map<String, dynamic> get socialAuthConfig => {
  'social_auth': {
    // Backend endpoint for token exchange
    'endpoint': '/auth/social/{provider}',

    'providers': {
      'google': {
        'enabled': true,
        'client_id': env('GOOGLE_CLIENT_ID'),
        'server_client_id': env('GOOGLE_SERVER_CLIENT_ID'),
        'scopes': ['email', 'profile'],
      },
      'microsoft': {
        'enabled': true,
        'client_id': env('MICROSOFT_CLIENT_ID'),
        'tenant': env('MICROSOFT_TENANT', 'common'),
        'callback_scheme': 'myapp',
        'scopes': ['openid', 'profile', 'email'],
      },
      'github': {
        'enabled': true,
        'client_id': env('GITHUB_CLIENT_ID'),
        'callback_scheme': 'myapp',
        'scopes': ['read:user', 'user:email'],
      },
    },
  },
};

All values are read at runtime via ConfigRepository. Provider-specific OAuth setup (Google Cloud Console, Azure Portal, GitHub Developer Settings) is covered in the configuration docs.

Usage

Basic Authentication

await SocialAuth.driver('google').authenticate();
await SocialAuth.driver('microsoft').authenticate();
await SocialAuth.driver('github').authenticate();

Check Platform Support

if (SocialAuth.supports('google')) {
  // Show Google sign-in button
}

Custom Driver

// Register in your ServiceProvider.boot()
SocialAuth.manager.extend('apple', (config) => AppleDriver(config));

// Use it
await SocialAuth.driver('apple').authenticate();

Custom Auth Handler

Replace the default HTTP handler with your own logic:

class FirebaseAuthHandler implements SocialAuthHandler {
  @override
  Future<void> handle(SocialToken token) async {
    final credential = GoogleAuthProvider.credential(
      idToken: token.idToken,
      accessToken: token.accessToken,
    );
    await FirebaseAuth.instance.signInWithCredential(credential);
  }
}

// Register it
SocialAuth.manager.setHandler(FirebaseAuthHandler());

SocialAuthButtons Widget

Config-driven UI that renders buttons for all enabled, platform-supported providers:

SocialAuthButtons(
  onAuthenticate: (provider) async {
    await SocialAuth.driver(provider).authenticate();
  },
  loadingProvider: currentlyLoading, // shows spinner on active button
  mode: SocialAuthMode.signIn,      // or SocialAuthMode.signUp
)

Register UI metadata for custom providers:

SocialAuth.manager.registerProviderDefaults('apple', SocialProviderDefaults(
  label: 'Apple',
  iconSvg: '<svg>...</svg>',
  order: 4,
));

Sign Out

await SocialAuth.signOut(); // Clears cached sessions across all providers

Architecture

App launch → SocialAuthServiceProvider.register()
  → binds SocialAuthManager singleton via IoC
  → SocialAuth facade resolves manager from container
  → SocialAuth.driver('google') → manager.driver('google')
    → reads config via ConfigRepository
    → resolves built-in or custom driver
  → driver.authenticate()
    → driver.getToken() (native SDK / OAuth browser)
    → manager.handleAuth(token) → handler.handle(token)
    → default handler POSTs to backend → Auth.login()

Key patterns:

Pattern Implementation
Singleton Manager SocialAuthManager — central orchestrator
Strategy (Driver) GoogleDriver, MicrosoftDriver, GithubDriver implement SocialDriver
Handler Chain SocialAuthHandler — swap HTTP for Firebase, Supabase, etc.
Service Provider Two-phase bootstrap: register() (sync) → boot() (async)
IoC Container Binding via app.singleton() / Magic.make()
Static Facade SocialAuth — zero-instance access to the manager

Documentation

Document Description
Installation Adding the package and registering the provider
Configuration Config reference, OAuth setup for Google/Microsoft/GitHub
Drivers Built-in drivers and writing custom ones
Handlers Default HTTP handler and custom handler implementations
Architecture Manager, facade, driver, and handler patterns

Contributing

Contributions are welcome! Please see the issues page for open tasks or to report bugs.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Write tests following the TDD flow — red, green, refactor
  4. Ensure all checks pass: flutter test, dart analyze, dart format .
  5. Submit a pull request

License

Magic Social Auth is open-sourced software licensed under the MIT License.

Built with care by FlutterSDK
If Magic Social Auth helps your project, consider giving it a star on GitHub.

Libraries

magic_social_auth