Setting Up the Social Auth SDK

What you'll learn

• Generating the Social Auth SDK with per-provider feature flags
• Understanding the generated package structure and DI wiring order
• Configuring Google Sign-In, Sign in with Apple, and Facebook Login
• Apple's App Store requirement for Sign in with Apple

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Auth SDK already generated (see Auth SDK Setup)

Pro Feature

social_auth_sdk is available on the Pro tier and above.

Step 1: Generate the Social Auth SDK

archipelago generate social_auth_sdk

You will be prompted for:

• includeGoogle — true (generates Google Sign-In implementation)
• includeApple — true (generates Sign in with Apple implementation)
• includeFacebook — false (generates Facebook Login implementation)

App Store policy

Apple requires Sign in with Apple whenever your app offers any other third-party login. If you set includeApple: false while enabling Google or Facebook, the generator will warn you at generation time. You can proceed, but your app will be rejected by App Store review unless you add Sign in with Apple before submission.

Or use a config file:

{
  "includeGoogle": true,
  "includeApple": true,
  "includeFacebook": false
}

archipelago generate social_auth_sdk --config social_auth_config.json

Step 2: Understand the Generated Structure

The brick generates one package per enabled provider plus a shared API contract and an orchestrator impl:

features/social_auth/
├── social_auth_api/
│   └── lib/src/
│       └── social_auth_sdk.dart              # Shared contract
├── social_auth_impl/
│   └── lib/src/
│       └── social_auth_impl.dart             # Orchestrator (wires providers)
├── google_social_auth_impl/                  # includeGoogle=true
│   └── lib/src/
│       └── google_social_auth_impl.dart
├── apple_social_auth_impl/                   # includeApple=true
│   └── lib/src/
│       └── apple_social_auth_impl.dart
└── facebook_social_auth_impl/               # includeFacebook=true (if enabled)
    └── lib/src/
        └── facebook_social_auth_impl.dart

Step 3: Register the Feature

post_gen auto-wires DI, but the registration order matters. Each provider module must be registered before the orchestrator:

// bootstrap.dart
import 'package:google_social_auth_impl/google_social_auth_impl.dart';
import 'package:apple_social_auth_impl/apple_social_auth_impl.dart';
import 'package:social_auth_impl/social_auth_impl.dart';

// 1. Register each provider module first
FeatureRegistry.register(GoogleSocialAuthImpl());
FeatureRegistry.register(AppleSocialAuthImpl());

// 2. Register the orchestrator last
FeatureRegistry.register(SocialAuthImpl());

Step 4: Configure Google Sign-In

Follow the google_sign_in setup guide.

Android — add the OAuth 2.0 client ID as a resValue in android/app/build.gradle:

android {
  defaultConfig {
    resValue "string", "default_web_client_id", "<YOUR_CLIENT_ID>.apps.googleusercontent.com"
  }
}

iOS — add the reversed client ID to Info.plist:

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

Step 5: Configure Sign in with Apple

Follow the sign_in_with_apple setup guide.

1. In Xcode, enable the Sign in with Apple capability under your app's target → Signing & Capabilities.
2. In the Apple Developer portal, configure a Services ID for web/Android redirect support (required for non-iOS platforms).
3. No Info.plist or build.gradle changes needed — the capability alone is sufficient for iOS.

Step 6: Configure Facebook Login (optional)

Follow the flutter_facebook_auth setup guide.

Android — add to android/app/src/main/res/values/strings.xml:

<string name="facebook_app_id">YOUR_APP_ID</string>
<string name="facebook_client_token">YOUR_CLIENT_TOKEN</string>

iOS — add to Info.plist:

<key>FacebookAppID</key>
<string>YOUR_APP_ID</string>
<key>FacebookClientToken</key>
<string>YOUR_CLIENT_TOKEN</string>
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fbYOUR_APP_ID</string>
    </array>
  </dict>
</array>

Step 7: Use the Social Auth API

Resolve the orchestrator from GetIt and sign in with any provider:

final socialAuth = getIt<SocialAuthSDK>();

// Google
await socialAuth.signInWithGoogle();

// Apple
await socialAuth.signInWithApple();

// Facebook
await socialAuth.signInWithFacebook();

The orchestrator delegates to the registered provider impl and returns a unified SocialAuthResult containing the provider token, which the Auth SDK then exchanges for your backend session token.

Common Customizations

Customization	Where to Change
Add a provider later	Re-run archipelago generate social_auth_sdk with the new flag enabled
Custom error handling	Override onError in the provider impl's DI module
Scope changes (Google)	Pass scopes to GoogleSignIn() in google_social_auth_impl
Server-side token exchange	Modify social_auth_impl to POST the provider token to your backend

Next Steps

• Set up Monitoring to track social login success and failure rates
• Configure the UI Kit to add social login buttons to the generated login page