Smart Auth Unified

Unified authentication for Flutter/Dart with one simple API across many providers: Firebase, Supabase, Cognito, Auth0/Okta/Azure, Google, Apple, Facebook, Twitter/X, GitHub, LinkedIn, SAML, OIDC, LDAP, and custom JWT.

Table of contents

• Getting started
  • Install
  • Production checklist
  • Quick start
• Core concepts
  • Unified API
  • Features
• Provider matrix
• Provider guides
  • Google Android | Google iOS | Google Use
  • Apple iOS | Apple Use
  • Facebook Android | Facebook iOS | Facebook Use
  • GitHub Console | GitHub App setup | GitHub Use
  • LinkedIn Console | LinkedIn App setup | LinkedIn Use
  • Twitter Console | Twitter App setup | Twitter Use
  • Firebase Enable providers | Firebase Use
  • Supabase Enable providers | Supabase Use
  • Cognito Console | Cognito Use
  • OIDC Console | OIDC Use
  • SAML Backend | SAML Use
  • LDAP Backend | LDAP Use
• Example app
• License

Getting started

Install

Add to pubspec.yaml:

dependencies:
  smart_auth_unified: ^0.0.1

Then run flutter pub get.

Production checklist

• Configure platform setup for providers (Android/iOS/Web)
• Use SecureTokenStorage.defaultInstance(aesKey: '32-char-secret') for AES-at-rest
• Gate sensitive flows with biometrics where possible
• For Firebase/Supabase, sign in with their SDKs, then mirror the session via adapters

Quick start

import 'package:smart_auth_unified/smart_auth_unified.dart';

void main() async {
  final auth = SmartAuthClient(
    storage: SecureTokenStorage.defaultInstance(),
  );

  await auth.registerProvider(GoogleAuthProvider());
  await auth.registerProvider(
    EmailPasswordAuthProvider(signInCallback: (email, password) async {
      // Call your backend and return a JwtSession
      return JwtSession(
        providerId: 'jwt',
        accessToken: 'token',
        refreshToken: 'refresh',
        expiresAt: DateTime.now().add(const Duration(hours: 1)),
        user: const AuthUser(id: '1', email: 'you@example.com'),
        roles: const {'user'},
        claims: const {'tenant': 'acme'},
      );
    }),
  );

  final session = await auth.signIn(provider: AuthProvider.google);
  print('Signed in as: ${session.user.email}');
}

Core concepts

Unified API

• auth.signIn(provider: AuthProvider.google)
• auth.signOut()
• auth.currentSession
• auth.onAuthStateChanged (stream)
• auth.hasRole('admin'), auth.hasClaim('tenant', 'acme')

Features

• Unified API via pluggable providers
• Secure token storage; optional AES encryption at rest
• Sessions: auto-restore, refresh, stream, multi-provider registry
• Offline-first: cached sessions and queued actions to replay
• Roles & claims helpers
• Biometric unlock (Face ID / Touch ID / PIN)
• Cross-platform: iOS, Android, Web (limited), Desktop, backend Dart
• Observability: debug logs and hooks

Provider matrix

Provider	Package	Status
Google	google_sign_in	Implemented
Email/Password	custom	Implemented
JWT (custom backend)	custom	Implemented
Apple	sign_in_with_apple	Implemented
Facebook	flutter_facebook_auth	Implemented
GitHub	OAuth (web)	Implemented
LinkedIn	OAuth (web)	Implemented
Twitter/X	twitter_login	Implemented
Firebase	firebase_auth	Implemented (adapter)
Supabase	supabase_flutter	Implemented (adapter)
Cognito	flutter_appauth	Implemented (OIDC)
OIDC (generic)	flutter_appauth	Implemented
SAML	flutter_web_auth_2 (backend ACS)	Implemented
LDAP	custom backend	Implemented

General platform setup

• Android: add OAuth redirect intent filters; register SHA-1/SHA-256 where needed
• iOS: add URL schemes/capabilities; associated domains if required
• Web: authorize redirect URLs in provider consoles

Provider guides

Quick index:

• Google: Android | iOS | Use
• Apple: iOS | Use
• Facebook: Android | iOS | Use
• GitHub: Console | App setup | Use
• LinkedIn: Console | App setup | Use
• Twitter/X: Console | App setup | Use
• Firebase adapter: Enable providers | Use
• Supabase adapter: Enable providers | Use
• Cognito: Console | Use
• OIDC: Console | Use
• SAML: Backend | Use
• LDAP: Backend | Use

Google

Google Android

• Create OAuth client in Google Cloud for Android
• Add SHA-1/SHA-256 fingerprints

Google iOS

• Create iOS OAuth client; add reversed client ID in URL Schemes

Info.plist (URL Types) example:

<key>CFBundleURLTypes</key>
<array>
<dict>
  <key>CFBundleURLSchemes</key>
  <array>
    <string>com.googleusercontent.apps.YOUR_REVERSED_CLIENT_ID</string>
  </array>
</dict>
</array>

Google Use

await auth.registerProvider(GoogleAuthProvider());
final session = await auth.signIn(provider: AuthProvider.google);

Apple

Apple iOS

• Enable “Sign in with Apple” capability in target settings

Apple Use

await auth.registerProvider(AppleAuthProvider());
final session = await auth.signIn(provider: AuthProvider.apple);

Facebook

Facebook Android

android/app/src/main/res/values/strings.xml

<resources>
  <string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
  <string name="fb_login_protocol_scheme">fbYOUR_FACEBOOK_APP_ID</string>
</resources>

AndroidManifest (application):

<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id" />
<activity android:name="com.facebook.FacebookActivity" android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation" />
<provider android:authorities="com.facebook.app.FacebookContentProvider${applicationId}" android:name="com.facebook.FacebookContentProvider" android:exported="true" />

Facebook iOS

Info.plist:

<key>CFBundleURLTypes</key>
<array>
<dict>
  <key>CFBundleURLSchemes</key>
  <array>
    <string>fbYOUR_FACEBOOK_APP_ID</string>
  </array>
</dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
<string>fbapi</string>
<string>fb-messenger-share-api</string>
<string>fbauth2</string>
</array>

Facebook Use

await auth.registerProvider(FacebookAuthProvider());
final session = await auth.signIn(provider: AuthProvider.facebook);

GitHub (OAuth via web)

GitHub Console

• Create an OAuth App and set callback to your.app://callback

GitHub App setup

• iOS: add your.app scheme in URL Types
• Android: add intent filter if needed

GitHub Use

await auth.registerProvider(GitHubAuthProvider(
clientId: 'GITHUB_CLIENT_ID',
clientSecret: 'GITHUB_CLIENT_SECRET',
redirectUri: 'your.app://callback',
));
final session = await auth.signIn(provider: AuthProvider.github);

LinkedIn (OAuth via web)

LinkedIn Console

• Create app; set redirect URI

LinkedIn App setup

• Add URL scheme for your redirect

LinkedIn Use

await auth.registerProvider(LinkedInAuthProvider(
clientId: 'LINKEDIN_CLIENT_ID',
clientSecret: 'LINKEDIN_CLIENT_SECRET',
redirectUri: 'your.app://callback',
));
final session = await auth.signIn(provider: AuthProvider.linkedin);

Twitter/X

Twitter Console

• Create developer app; set callback to your.app://callback

Twitter App setup

• iOS URL scheme; Android intent filter if needed

Twitter Use

await auth.registerProvider(TwitterAuthProvider(
apiKey: 'TWITTER_API_KEY',
apiSecretKey: 'TWITTER_API_SECRET',
redirectUri: 'your.app://callback',
));
final session = await auth.signIn(provider: AuthProvider.twitter);

Firebase (adapter; dynamic)

Firebase Enable providers

• In Firebase Console, enable Google/Apple/GitHub/Twitter/etc.
• Use firebase_auth (and provider plugins/FirebaseUI) for sign-in

Firebase Use

await auth.registerProvider(FirebaseAuthProvider());
final session = await auth.signIn(provider: AuthProvider.firebase);

Supabase (adapter; dynamic)

Supabase Enable providers

• In Supabase Dashboard, enable providers and configure redirect URL

Supabase Use

await auth.registerProvider(SupabaseAuthProvider());
final session = await auth.signIn(provider: AuthProvider.supabase);

Cognito (OIDC via AppAuth)

Cognito Console

• Create a User Pool app client (no secret); set hosted UI domain and redirect URL

Cognito Use

await auth.registerProvider(CognitoAuthProvider(
clientId: 'COGNITO_CLIENT_ID',
redirectUrl: 'your.app://callback',
discoveryUrl: 'https://your-domain/.well-known/openid-configuration',
));
final session = await auth.signIn(provider: AuthProvider.cognito);
await auth.refresh();

OIDC (Auth0/Okta/Azure AD/Keycloak)

OIDC Console

• Create native app; set redirect URI your.app://callback; copy discovery URL

OIDC Use

await auth.registerProvider(OidcAuthProvider(
clientId: 'OIDC_CLIENT_ID',
redirectUrl: 'your.app://callback',
discoveryUrl: 'https://issuer/.well-known/openid-configuration',
));
final session = await auth.signIn(provider: AuthProvider.oidc);

SAML (backend ACS)

SAML Backend

• Implement SAML initiation and ACS on your server; redirect back to app scheme with token

SAML Use

await auth.registerProvider(SamlAuthProvider(
authUrl: 'https://your-backend.example.com/auth/saml/start',
callbackScheme: 'your.app',
));
final session = await auth.signIn(provider: AuthProvider.saml);

LDAP (backend)

LDAP Backend

• Expose an endpoint to bind/authenticate and issue JWT

LDAP Use

await auth.registerProvider(LdapAuthProvider(signInCallback: (username, password) async {
// call your backend and return a JwtSession
throw UnimplementedError();
}));

Example app

See example/ for a Flutter demo covering email/password, Google Sign-In, role checks, and biometric unlock.

License

MIT — see LICENSE.