managarten/manadeck/apps/mobile/SOCIAL_AUTH_SETUP.md

Social Authentication Setup Guide for Manadeck

This guide explains how to set up Google Sign-In and Apple Sign-In for the Manadeck mobile app.

Overview

Manadeck uses Mana Core authentication middleware which supports:

• Email/Password authentication
• Google Sign-In (Android & iOS)
• Apple Sign-In (iOS only)

All authentication methods issue JWT tokens that work with your Supabase backend and respect Row-Level Security (RLS) policies.

Prerequisites

Required Accounts and Credentials

1. Google Cloud Console Account

   • OAuth 2.0 credentials for Android and iOS
   • Web Client ID (for Android)
   • iOS Client ID (for iOS)

2. Apple Developer Account

   • Sign in with Apple capability enabled
   • App ID configured with Sign in with Apple

3. Mana Core Backend

   • Backend must support /v1/auth/google-signin and /v1/auth/apple-signin endpoints
   • Backend URL configured in .env.local

Installation

The required dependencies are already installed:

• @react-native-google-signin/google-signin@^14.0.1
• expo-apple-authentication@~8.0.7
• base64-js

Configuration Steps

1. Google Cloud Console Setup

Create OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project or select existing project
3. Navigate to APIs & Services → Credentials

For Android:

1. Click Create Credentials → OAuth 2.0 Client ID
2. Select Android as application type
3. Fill in:
   • Package name: com.tilljs.manadeck
   • SHA-1 certificate fingerprint: Get from cd android && ./gradlew signingReport
4. Click Create

For iOS:

1. Click Create Credentials → OAuth 2.0 Client ID
2. Select iOS as application type
3. Fill in:
   • Bundle ID: com.tilljs.manadeck
4. Click Create
5. Save the iOS Client ID (format: XXXXX.apps.googleusercontent.com)

For Web (Required for Android):

1. Click Create Credentials → OAuth 2.0 Client ID
2. Select Web application as application type
3. Fill in:
   • Name: Manadeck Web (for Android)
4. Click Create
5. Save the Web Client ID (format: XXXXX.apps.googleusercontent.com)

2. Apple Developer Console Setup

Enable Sign in with Apple

1. Go to Apple Developer Portal
2. Navigate to Certificates, Identifiers & Profiles
3. Click Identifiers in the sidebar
4. Find and select your App ID: com.tilljs.manadeck
5. In the Capabilities section, find Sign in with Apple
6. Check the Sign in with Apple checkbox
7. Click Save

Configure in Xcode (Optional but Recommended)

1. Open your iOS project:

   cd /Users/tillschneider/Documents/__00__Code/manadeck/apps/mobile
   open ios/manadeck.xcworkspace
   

2. Select your project target in the left sidebar
3. Go to Signing & Capabilities tab
4. Click + Capability button
5. Add Sign in with Apple
6. Ensure proper signing team is selected (Team ID: QP3GLU8PH3)

3. Update Environment Variables

Edit /Users/tillschneider/Documents/__00__Code/manadeck/apps/mobile/.env.local:

# Existing Supabase Configuration
EXPO_PUBLIC_SUPABASE_URL=https://vksoodohrbjwyloitvsz.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_2ndX-kBHFpbDlL_ZeeOnfQ_ZlLI8ONk

# Existing Backend API Configuration
EXPO_PUBLIC_API_URL=https://manadeck-backend-pduya7fsoq-ey.a.run.app

# Google OAuth Configuration (ADD THESE)
# Web Client ID (used for Android authentication)
EXPO_PUBLIC_GOOGLE_CLIENT_ID=YOUR_WEB_CLIENT_ID.apps.googleusercontent.com
# iOS Client ID (used for iOS authentication)
EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=YOUR_IOS_CLIENT_ID.apps.googleusercontent.com

Replace the placeholder values with your actual OAuth Client IDs from Google Cloud Console.

4. Update app.json

The app.json has already been configured with:

{
  "expo": {
    "ios": {
      "config": {
        "googleSignIn": {
          "reservedClientId": "com.googleusercontent.apps.PLACEHOLDER_IOS_CLIENT_ID"
        }
      },
      "usesAppleSignIn": true
    },
    "plugins": [
      "expo-router",
      "@react-native-google-signin/google-signin",
      "expo-apple-authentication"
    ]
  }
}

Important: Replace PLACEHOLDER_IOS_CLIENT_ID in app.json with your actual iOS Client ID (without the com.googleusercontent.apps. prefix).

For example, if your iOS Client ID is 123456789-abc123.apps.googleusercontent.com, the reservedClientId should be:

"reservedClientId": "com.googleusercontent.apps.123456789-abc123"

5. Rebuild Native Code

After updating app.json and environment variables, rebuild the native code:

cd /Users/tillschneider/Documents/__00__Code/manadeck/apps/mobile

# For iOS
npx expo prebuild --clean
npx expo run:ios

# For Android
npx expo prebuild --clean
npx expo run:android

6. IMPORTANT: Manually Add iOS URL Scheme

⚠️ Critical Step: The Expo plugin may not automatically add the Google Sign-In URL scheme to iOS. You must verify and add it manually.

Verify and Add URL Scheme to Info.plist

1. Open ios/manadeck/Info.plist
2. Find the CFBundleURLTypes array
3. Add a new URL scheme entry for Google Sign-In:

<key>CFBundleURLTypes</key>
<array>
  <!-- Existing URL schemes -->
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>manadeck</string>
      <string>com.tilljs.manadeck</string>
    </array>
  </dict>

  <!-- Add this new entry for Google Sign-In -->
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.googleusercontent.apps.111768794939-cgen6eklloo7k8vppcaq01o8r8nd7anb</string>
    </array>
  </dict>
</array>

Replace 111768794939-cgen6eklloo7k8vppcaq01o8r8nd7anb with your actual iOS Client ID.

Why This is Required

Without this URL scheme, Google Sign-In will fail with:

Your app is missing support for the following URL schemes:
com.googleusercontent.apps.XXXXX

iOS uses this URL scheme to redirect back to your app after Google authentication.

Backend Requirements

Your Mana Core backend must support the following endpoints:

POST /v1/auth/google-signin

⚠️ Important: The backend expects deviceInfo as a nested object, not spread at the root level.

Request body:

{
  "token": "GOOGLE_ID_TOKEN",
  "deviceInfo": {
    "deviceId": "device-uuid",
    "deviceName": "iPhone 15 Pro",
    "deviceType": "ios"
  }
}

Response:

{
  "appToken": "JWT_TOKEN",
  "refreshToken": "REFRESH_TOKEN"
}

POST /v1/auth/apple-signin

⚠️ Important: The backend expects deviceInfo as a nested object, not spread at the root level.

Request body:

{
  "token": "APPLE_IDENTITY_TOKEN",
  "deviceInfo": {
    "deviceId": "device-uuid",
    "deviceName": "iPhone 15 Pro",
    "deviceType": "ios"
  }
}

Response:

{
  "appToken": "JWT_TOKEN",
  "refreshToken": "REFRESH_TOKEN"
}

Common Error: If you send device info spread at root level instead of nested:

// ❌ WRONG - Will fail with "Complete device information is required"
{
  "token": "...",
  "deviceId": "...",
  "deviceName": "...",
  "deviceType": "ios"
}

// ✅ CORRECT - deviceInfo as nested object
{
  "token": "...",
  "deviceInfo": {
    "deviceId": "...",
    "deviceName": "...",
    "deviceType": "ios"
  }
}

Testing

Test on iOS

1. Build and run:

   cd /Users/tillschneider/Documents/__00__Code/manadeck/apps/mobile
   npx expo run:ios
   

2. Test Google Sign-In:

   • Tap "Mit Google anmelden"
   • Should show Google account picker
   • Select account
   • Should authenticate and navigate to home

3. Test Apple Sign-In:

   • Tap "Mit Apple anmelden"
   • Should show Face ID/Touch ID prompt
   • Authenticate
   • Should navigate to home

Test on Android

1. Build and run:

   npx expo run:android
   

2. Test Google Sign-In:

   • Tap "Mit Google anmelden"
   • Should show Google account picker
   • Select account
   • Should authenticate and navigate to home

3. Apple Sign-In won't show on Android (iOS only)

Project Structure

The social authentication implementation includes:

manadeck/apps/mobile/
├── services/
│   └── authService.ts              # Extended with Google/Apple methods
├── store/
│   └── authStore.ts                # Updated with social sign-in actions
├── components/
│   └── auth/
│       ├── GoogleSignInButton.tsx  # Google Sign-In button component
│       └── AppleSignInButton.tsx   # Apple Sign-In button component
├── app/
│   └── (auth)/
│       └── login.tsx               # Updated with social buttons
├── app.json                        # Configured with plugins
└── .env.local                      # OAuth credentials

Troubleshooting

Google Sign-In Issues

"Your app is missing support for the following URL schemes" on iOS

Cause: Google Sign-In URL scheme not added to Info.plist

Solution:

1. Open ios/manadeck/Info.plist
2. Add the Google Sign-In URL scheme to CFBundleURLTypes:

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

3. Replace YOUR_IOS_CLIENT_ID with your actual iOS Client ID
4. Rebuild the app: npx expo run:ios

"DEVELOPER_ERROR" on Android

Cause: SHA-1 fingerprint mismatch or incorrect web client ID

Solution:

# Get your SHA-1
cd android && ./gradlew signingReport

# Add SHA-1 to Google Cloud Console
# Use Web Client ID (not Android Client ID) in EXPO_PUBLIC_GOOGLE_CLIENT_ID

"Sign-in failed" on iOS

Cause: Incorrect iOS Client ID or bundle identifier mismatch

Solution:

• Verify EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID matches Google Cloud Console
• Verify bundle identifier in app.json matches Google Cloud Console
• Update reservedClientId in app.json with correct iOS Client ID

"Play Services not available"

Cause: Google Play Services missing or outdated on Android

Solution:

• Update Google Play Services on device
• Test on device with Google Play Store installed
• Use emulator with Google Play

Apple Sign-In Issues

Button doesn't appear

Cause: Platform is not iOS

Solution: Apple Sign-In only works on iOS 13+

"Operation canceled" every time

Cause: Sign in with Apple not enabled in developer portal

Solution:

• Enable capability in Apple Developer Portal
• Add capability in Xcode
• Ensure usesAppleSignIn: true in app.json

Backend Connection Issues

"Complete device information is required"

Cause: Device info sent incorrectly (spread at root instead of nested object)

Solution: Ensure your authService sends deviceInfo as a nested object:

// ✅ Correct
body: JSON.stringify({
  token: idToken,
  deviceInfo,  // Nested object
})

// ❌ Wrong
body: JSON.stringify({
  token: idToken,
  ...deviceInfo,  // Spread at root - will fail
})

"Network error" or timeout

Cause: Backend URL incorrect or unreachable

Solution:

• Verify EXPO_PUBLIC_API_URL is correct
• Test backend health endpoint
• Check network connectivity
• Ensure HTTPS is used (not HTTP)

"Invalid token" or "Authentication failed"

Cause: Backend endpoints not implemented or configured incorrectly

Solution:

• Verify backend supports /v1/auth/google-signin and /v1/auth/apple-signin
• Check backend logs for detailed error messages
• Ensure backend validates tokens correctly with Google/Apple

Security Considerations

1. Never commit credentials: Keep .env.local in .gitignore
2. Use HTTPS only: Always use HTTPS for backend communication
3. Validate tokens on backend: Always validate social tokens on the backend
4. Device binding: Tokens are bound to device IDs for security
5. Secure storage: Tokens stored using platform-specific secure storage

Production Setup

For Production Release

Android Production SHA-1:

When ready to publish to Google Play, get your production SHA-1:

# For EAS builds
eas credentials -p android

# Or if using your own keystore
keytool -list -v -keystore /path/to/release.keystore -alias YOUR_KEY_ALIAS

Add the production SHA-1 to your Android OAuth client in Google Cloud Console.

iOS Production:

The same iOS Client ID works for both development and production.

Additional Resources

• React Native Google Sign-In Documentation
• Expo Apple Authentication Documentation
• Google OAuth 2.0 Documentation
• Apple Sign In Guidelines

Quick Reference

Your Credentials (Fill in as you obtain them)

Web OAuth Client ID: ________________________________.apps.googleusercontent.com
iOS OAuth Client ID: ________________________________.apps.googleusercontent.com
Android SHA-1 (Debug): ________________________________
Android SHA-1 (Prod): ________________________________
Apple Team ID: QP3GLU8PH3
Bundle ID: com.tilljs.manadeck
Package Name: com.tilljs.manadeck

Important Commands

# Get Android SHA-1
cd android && ./gradlew signingReport

# Rebuild native code
npx expo prebuild --clean

# Run on iOS
npx expo run:ios

# Run on Android
npx expo run:android

# Build with EAS
eas build --profile development

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review backend logs for detailed error messages
3. Consult Google Cloud Console and Apple Developer Portal documentation
4. Check that all credentials are correctly configured

---

Integration completed successfully! Social authentication is now available in the Manadeck mobile app.