https://github.com/fluttersdk/magic_social_auth
Social authentication plugin for Magic Framework. Laravel Socialite-style API with extensible drivers.
https://github.com/fluttersdk/magic_social_auth
authentication flutter magic-framework oauth social-auth socialite
Last synced: 3 months ago
JSON representation
Social authentication plugin for Magic Framework. Laravel Socialite-style API with extensible drivers.
- Host: GitHub
- URL: https://github.com/fluttersdk/magic_social_auth
- Owner: fluttersdk
- License: mit
- Created: 2026-02-04T23:07:34.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-03-24T22:54:59.000Z (3 months ago)
- Last Synced: 2026-03-26T04:21:40.019Z (3 months ago)
- Topics: authentication, flutter, magic-framework, oauth, social-auth, socialite
- Language: Dart
- Homepage: https://magic.fluttersdk.com/social-auth
- Size: 63.5 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Magic Social Auth
Laravel Socialite-style social authentication for the Magic Framework.
Config-driven OAuth with extensible drivers for Google, Microsoft, GitHub, and beyond.
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
```yaml
dependencies:
magic_social_auth: ^0.0.1-alpha.1
```
### 2. Register the service provider
```dart
// lib/config/app.dart
import 'package:magic_social_auth/magic_social_auth.dart';
Map get appConfig => {
'app': {
'providers': [
// ... other providers
(app) => SocialAuthServiceProvider(app),
],
},
};
```
### 3. Create the config file
```dart
// lib/config/social_auth.dart
import 'package:magic/magic.dart';
Map 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
```dart
// lib/main.dart
import 'config/social_auth.dart';
await Magic.init(
configFactories: [
() => appConfig,
() => socialAuthConfig, // Add this
],
);
```
### 5. Authenticate
```dart
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:
```dart
Map 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](https://magic.fluttersdk.com/packages/social-auth/getting-started/configuration).
---
## Usage
### Basic Authentication
```dart
await SocialAuth.driver('google').authenticate();
await SocialAuth.driver('microsoft').authenticate();
await SocialAuth.driver('github').authenticate();
```
### Check Platform Support
```dart
if (SocialAuth.supports('google')) {
// Show Google sign-in button
}
```
### Custom Driver
```dart
// 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:
```dart
class FirebaseAuthHandler implements SocialAuthHandler {
@override
Future 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:
```dart
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:
```dart
SocialAuth.manager.registerProviderDefaults('apple', SocialProviderDefaults(
label: 'Apple',
iconSvg: '...',
order: 4,
));
```
### Sign Out
```dart
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](https://magic.fluttersdk.com/packages/social-auth/getting-started/installation) | Adding the package and registering the provider |
| [Configuration](https://magic.fluttersdk.com/packages/social-auth/getting-started/configuration) | Config reference, OAuth setup for Google/Microsoft/GitHub |
| [Drivers](https://magic.fluttersdk.com/packages/social-auth/basics/drivers) | Built-in drivers and writing custom ones |
| [Handlers](https://magic.fluttersdk.com/packages/social-auth/basics/handlers) | Default HTTP handler and custom handler implementations |
| [Architecture](https://magic.fluttersdk.com/packages/social-auth/architecture/overview) | Manager, facade, driver, and handler patterns |
---
## Contributing
Contributions are welcome! Please see the [issues page](https://github.com/fluttersdk/magic_social_auth/issues) 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](LICENSE).
---
Built with care by FlutterSDK
If Magic Social Auth helps your project, consider giving it a star on GitHub.