Authentication Guide

• Apple Sign In - Native iOS authentication
• Google Sign In - OAuth via Google
• Email/Password - Traditional email authentication

​

Features

​

Unified Sign In Experience

• Single Sign In Screen: All authentication options on one screen
• Social OAuth: Apple and Google sign in via Supabase Auth
• Email Authentication: Sign up and sign in with email/password
• Password Reset: Forgot password flow via email

​

Session Persistence

1. Keychain Storage: Auth tokens are securely stored in iOS Keychain
2. Automatic Session Loading: When the app launches, sessions are restored from Keychain
3. Expired Session Recovery: Even if access token has expired, the app automatically refreshes using the refresh token
4. Proactive Refresh: Tokens are refreshed 60 seconds before expiry
5. Retry Logic: Failed refresh attempts retry up to 3 times with exponential backoff

​

Session Behavior

​

Session Lifecycle

App Launch
    ↓
Load Session from Keychain
    ↓
Access Token Valid? ──No──→ Attempt Refresh with Refresh Token
    ↓ Yes                         ↓
    ↓                    Refresh Successful? ──No──→ Show Sign In Screen
    ↓                             ↓ Yes
Navigate to Main Screen  ←────────┘
    ↓
Schedule Proactive Refresh (60s before expiry)
    ↓
Silent background refresh
    ↓
Continue using app seamlessly

​

Setup

​

1. Configure Supabase

​

Enable Social Providers

1. Go to Supabase Dashboard
2. Select your project
3. Navigate to Authentication → Providers

​

Apple Sign In Setup (Step-by-Step)

​

Google Sign In Setup

• A Web OAuth client for Supabase, because Supabase owns the OAuth callback URL
• An iOS OAuth client for the native Google Sign-In SDK, because the app runs on iPhone and is identified by your Bundle ID

https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback

​

2. Configure iOS App

# Config/Secrets.xcconfig
SUPABASE_URL = https://YOUR_PROJECT_REF.supabase.co
SUPABASE_ANON_KEY = YOUR_PUBLIC_ANON_KEY

# For Google Sign In (optional)
GOOGLE_CLIENT_ID = YOUR_IOS_CLIENT_ID

dependencies: [
    .package(url: "https://github.com/google/GoogleSignIn-iOS", from: "7.0.0")
]

​

Google Credential Reference

​

3. Setup CompositionRoot

// CompositionRoot.swift

// Create auth client with social providers
let authClient = SessionManager(
    httpClient: httpClient,
    keychain: keychain,
    apple: AppleSignInCoordinator(),
    google: GoogleSignInCoordinator(clientID: googleClientID), // Optional
    config: authConfig
)

​

Usage

​

Sign In Flow

SignInView(authClient: authClient)

• Clean, Apple-like aesthetic with generous whitespace
• Native Apple button (HIG compliant) as primary CTA
• Visual hierarchy: Apple → Google → “Use email instead” link
• Premium feel with continuous corner radii and subtle borders
• Adapts to light/dark mode automatically

• Apple Sign In: Native button (HIG compliant) - primary option
• Google Sign In: Secondary button with subtle border
• Email Sign In: Shown via “Use email instead” link (opens sheet)
• Create Account: Accessible from email login sheet
• Forgot Password: Accessible from email login sheet

• Links and accents use DSColors.accentPrimary (warm pink in Aurora, neutral in others)
• Text colors use DSColors.textPrimary and DSColors.textSecondary
• Backgrounds and surfaces adapt to theme palette
• Icons inherit theme accent color
• No hardcoded system blue - everything theme-aware

• Top space: Spacer().frame(height: 100) - Adjust for vertical positioning
• Between hero and buttons: 64pt - Control breathing room
• Bottom space: 80pt then 48pt - Legal section padding

• App title: 28pt semibold rounded - Adjust size/weight
• Tagline: 15pt regular, 0.3 tracking, 70% opacity - Refine elegance
• Legal text: 12pt, 55% opacity - Keep whisper-quiet

• Avatar blur: blur(radius: 20) on gradient circle
• Background: Subtle top-to-bottom gradient
• Google button: surface.opacity(0.6) with 0.5pt border
• Link colors: Uses accentPrimary.opacity(0.7) for cohesion

• Hero fade-in: .easeOut(duration: 0.6) on appear
• Buttons slide: .delay(0.15) for staggered entrance
• Error message: .spring(response: 0.35) for smooth entry

• Max width: 380pt for button container (narrower = more refined)

​

Check Authentication State

// Check current user
let user = await authClient.currentUser()

if let user = user {
    print("Signed in as: \(user.email ?? "unknown")")
} else {
    print("Not signed in")
}

// Observe auth state changes
for await state in authClient.authStates() {
    switch state {
    case .authenticated(let user):
        print("User signed in: \(user.id)")
    case .unauthenticated:
        print("User signed out")
    case .refreshing:
        // Show loading UI while recovering expired session
        print("Refreshing session...")
    }
}

​

Sign Out

try await authClient.signOut()

1. Revoke the access token on the server
2. Clear tokens from Keychain
3. Clear in-memory session
4. Navigate to sign-in screen

​

How It Works

​

Apple Sign In Flow

1. User taps “Continue with Apple”
2. System shows Apple Sign In sheet
3. User authenticates with Face ID/Touch ID
4. App receives Apple ID token + nonce
5. Token is exchanged with Supabase for session
6. Session stored in Keychain
7. User navigated to main screen

// Internal flow
let (idToken, nonce) = try await apple.requestIDToken(...)
let session = try await api.exchangeAppleIDToken(idToken: idToken, nonce: nonce)
try await persistSession(session)

​

Google Sign In Flow

1. User taps “Continue with Google”
2. Google Sign In SDK presents OAuth flow
3. User selects Google account
4. App receives Google ID token
5. Token is exchanged with Supabase for session
6. Session stored in Keychain
7. User navigated to main screen

// Internal flow
let idToken = try await google.requestIDToken()
let session = try await api.exchangeGoogleIDToken(idToken: idToken)
try await persistSession(session)

​

Email Sign In Flow

1. User enters email and password
2. Credentials sent to Supabase
3. Supabase validates and returns session
4. Session stored in Keychain
5. User navigated to main screen

// Internal flow
let session = try await api.signInWithEmail(email: email, password: password)
try await persistSession(session)

​

Session Persistence Details

​

How Sessions Are Stored

- auth_access_token: JWT access token
- auth_refresh_token: Long-lived refresh token
- auth_expires_at: Token expiration timestamp
- auth_user_json: User profile data

• Uses kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
• Data is encrypted by iOS
• Survives app updates
• Deleted on app uninstall

​

Automatic Session Loading

1. Load from Keychain: Attempts to load stored session
2. Validate Expiry: Checks if access token is expired
3. Attempt Refresh: If expired, tries to refresh using the refresh token (up to 3 attempts)
4. Recover or Clear: Restores session if refresh succeeds, clears if refresh token is also expired
5. Emit State: Notifies observers of auth state (.refreshing during recovery)

// SessionManager.swift
private func loadInitialSession() async {
    if let session = try loadSession() {
        if Date.now > session.expiresAt {
            // Access token expired - attempt refresh
            stateContinuation?.yield(.refreshing)
            
            do {
                try await attemptSessionRefresh()
                // Refresh succeeded - user stays logged in
            } catch {
                // Refresh token also expired - user must sign in again
                try? clearSession()
                stateContinuation?.yield(.unauthenticated)
            }
        } else {
            // Session valid, restore it
            currentSession = session
            stateContinuation?.yield(.authenticated(session.user))
            
            // Schedule proactive refresh
            scheduleRefresh(for: session)
        }
    }
}

​

Token Refresh Strategy

1. Schedule Refresh: 60 seconds before token expiry
2. Silent Background Execution: User never sees a loading state
3. Token Rotation: Handles Supabase refresh token rotation

1. Detect Expired Session: On app launch, check if access token expired
2. Attempt Refresh: Use refresh token to get new access token
3. Retry Logic: Up to 3 attempts with exponential backoff
4. Emit .refreshing State: Show loading UI if needed

// Proactive: Scheduled 60 seconds before expiry
let refreshTime = session.expiresAt.addingTimeInterval(-60)
refreshTask = Task {
    try await sleeper.sleep(for: refreshTime.timeIntervalSinceNow)
    try await refreshIfNeeded()
}

// Reactive: Recover expired session on app launch
func attemptSessionRefresh() async throws {
    stateContinuation?.yield(.refreshing)
    
    for attempt in 1...3 {
        do {
            let newSession = try await api.refreshSession(refreshToken: session.refreshToken)
            try persistSession(newSession)
            stateContinuation?.yield(.authenticated(newSession.user))
            return
        } catch {
            if attempt < 3 {
                try await Task.sleep(for: .seconds(pow(2.0, Double(attempt))))
            }
        }
    }
    throw AuthError.sessionExpired
}

​

Navigation Based on Auth State

// LaunchRouter observes auth state
for await state in authClient.authStates() {
    switch state {
    case .authenticated:
        destination = .main  // Show main app
    case .unauthenticated:
        destination = .signIn  // Show sign in
    case .refreshing:
        // Keep current screen, just refreshing token
    }
}

• ✅ Users automatically navigate to main screen when signed in
• ✅ Users automatically navigate to sign in when signed out
• ✅ No manual navigation needed
• ✅ Works for all auth methods (Apple, Google, Email)

​

Best Practices

​

Always Check Auth State

// Don't store user state yourself
// ❌ Bad
@State private var isSignedIn = false

// ✅ Good - observe auth state
for await state in authClient.authStates() {
    // React to state changes
}

​

Handle Sign Out Gracefully

func signOut() {
    Task {
        do {
            try await authClient.signOut()
            // Navigation handled automatically by LaunchRouter
        } catch {
            // Show error to user
            errorMessage = "Failed to sign out: \(error.localizedDescription)"
        }
    }
}

​

Use Session Tokens for API Calls

// Auth tokens are automatically attached by AuthInterceptor
let request = FetchProfileRequest()
let profile: UserProfile = try await httpClient.execute(request)
// Headers include: Authorization: Bearer <access_token>

​

Troubleshooting

​

Users Have to Sign In Every Time

1. Keychain is accessible (not disabled in Xcode capabilities)
2. loadInitialSession() is being called
3. No errors in SessionManager initialization
4. Check logs for refresh attempts and failures
5. Verify refresh token hasn’t expired (7+ days of inactivity)

​

Google Sign In Not Working

1. Verify GOOGLE_CLIENT_ID is set to the iOS OAuth Client ID, not the Web Client ID.
2. Verify the Supabase Google provider uses the Web OAuth Client ID and Web OAuth Client Secret.
3. Ensure the Google Cloud Web OAuth client has this exact authorized redirect URI: https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback.
4. Ensure the Google Cloud iOS OAuth client Bundle ID exactly matches PRODUCT_BUNDLE_IDENTIFIER in Config/App.xcconfig.
5. If you changed Secrets.xcconfig, run bash scripts/update-config.sh, clean, and rebuild.
6. Verify GoogleSignIn SDK is installed.
7. For local development, do not block on App Store ID. Add it later after creating the app in App Store Connect.

​

Apple Sign In Fails

1. Supabase Configuration: Verify Apple provider is enabled in Supabase Authentication → Providers
2. Apple Developer Portal: Check that Sign in with Apple capability is enabled on your App ID
3. Xcode Capability: Ensure “Sign in with Apple” capability is added in Signing & Capabilities
4. Credentials: Verify Team ID, Key ID, and Private Key are correct in Supabase
5. Bundle ID: Check bundle ID matches between Xcode, App Store Connect, and Supabase

​

Token Refresh Fails

• Network connectivity issues
• Supabase service status
• Invalid refresh token (forces re-authentication)
• Too many concurrent refresh attempts

​

Security Considerations

1. Tokens in Keychain: Never store tokens in UserDefaults or files
2. HTTPS Only: All auth requests use HTTPS
3. Token Expiry: Access tokens expire (default: 1 hour), but sessions persist via refresh tokens
4. Refresh Token Lifetime: Configurable in Supabase dashboard (default: 7+ days)
5. Refresh Rotation: Supabase rotates refresh tokens for security
6. Server-Side Validation: Always validate tokens server-side
7. Detailed Logging: Auth events are logged for debugging (tokens are never logged)

​

Next Steps