Apple auth via native iOS flow

[gnprice]

After #462, the app will support using Apple auth, aka "Sign in with Apple", to log into Zulip.

The initial version of that will mean going through the web-based flow. That's the only flow that's available in any case on Android, and it's a perfectly reasonable UX; it's the same kind of UX as when people log in via GitHub, or Google, or any other form of SSO.

But on iOS, there's an alternate flow for "Sign in with Apple" which uses native UI provided by the system, and it'd be nice to use that instead. This issue is for doing that.

Implementation

Because this issue is closely tied to our interaction with Apple, it will need to be done by a member of the core team.

Upstream docs here:
https://developer.apple.com/sign-in-with-apple/
but I hope we can complete this feature without (re-)reading those in any detail — instead we can crib from the work we did back in 2020, when we read up on this closely in order to implement it the first time.

We'll follow the example of the legacy app. See the implementation there, from 2020:
https://github.com/zulip/zulip-mobile/pull/4034/files

That implementation uses a library from Expo, in the RN ecosystem, namely expo-apple-authentication, to do much of the work. For Flutter, @chrisbobbe found at #36 (comment) that there's a "Flutter Favorite" plugin for it: package:sign_in_with_apple. So let's try using that.

Key points appear in particular commits from the legacy app's implementation:

• the main commit: zulip/zulip-mobile@b72e9a3
• the logic for which servers we can use the native iOS flow with: zulip/zulip-mobile@f900521 and zulip/zulip-mobile@c7b37e2
• how to test: zulip/zulip-mobile@c19cbe2
• the UI for the button: zulip/zulip-mobile@cc8b569 (hopefully the library provides this for us, but we'll see)
• zulip/zulip-mobile@98a626a
• the Apple "entitlement" for the feature, in zulip/zulip-mobile@c7d982e (the rest of that commit won't apply)
• zulip/zulip-mobile@8d056ed (some information from studying Apple docs, filling a gap in that Expo library, in case the same info is needed with the Flutter-based library we'll try)

Testing

An important part of the work on this issue will be to test it end to end. The only practical way to do that is manually: fire up the app with your draft implementation of the feature, and try using it.

For instructions on how to do that, see zulip/zulip-mobile@c19cbe2, or perhaps more readably:
https://github.com/zulip/zulip-mobile/blob/main/docs/howto/ios-tips.md#sign-in-with-apple

See also this 2025 thread which has some updates to those instructions:
#mobile-dev-help > Enable "Sign in with Apple" for Flutter App

Related issues

• From when we originally implemented this feature in the server and the legacy mobile app, in 2020 when Apple's mandate of it took effect:
  Support "Sign In with Apple" auth zulip#14168
  Support "Sign In with Apple" auth [iOS] zulip-mobile#3964
  Those have a lot of links to Apple docs and other background information. (But again, I hope we can skip reading or re-reading most of that — instead borrow from the work we did in 2020.)

[shkshreyas]

Implementing Apple Auth via Native iOS Flow

my solution for implementing Apple authentication using the native iOS flow in the Flutter app. This implementation will use the sign_in_with_apple package, which is a Flutter Favorite plugin.

Step 1: Add the required dependencies

First, we need to add the sign_in_with_apple package to the pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  sign_in_with_apple: ^4.3.0

Step 2: Configure iOS entitlements

We need to add the Apple Sign In entitlement to the iOS app:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.applesignin</key>
    <array>
        <string>Default</string>
    </array>
</dict>
</plist>

Also, update the Info.plist file to include the capability:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>com.zulip.flutter</string>
        </array>
    </dict>
</array>

Step 3: Create an Apple Auth Service

Let's create a service to handle Apple authentication:

import 'dart:convert';
import 'dart:io';

import 'package:flutter/foundation.dart';
import 'package:sign_in_with_apple/sign_in_with_apple.dart';
import 'package:http/http.dart' as http;

class AppleAuthService {
  /// Checks if the Apple Sign In is available on this device
  static Future<bool> isAvailable() async {
    if (!Platform.isIOS) {
      return false;
    }
    
    try {
      return await SignInWithApple.isAvailable();
    } catch (e) {
      debugPrint('Error checking Apple Sign In availability: $e');
      return false;
    }
  }
  
  /// Determines if we can use native Apple auth for a given server
  static bool canUseNativeAppleAuthForServer(String serverHost) {
    // Based on the legacy app logic, we can use native Apple auth for:
    // 1. Zulip Cloud (zulipchat.com)
    // 2. Local development servers
    return serverHost.endsWith('zulipchat.com') || 
           serverHost.contains('localhost') || 
           serverHost.contains('127.0.0.1');
  }
  
  /// Performs the Apple Sign In flow and returns the auth data
  static Future<Map<String, dynamic>> signInWithApple() async {
    try {
      final credential = await SignInWithApple.getAppleIDCredential(
        scopes: [
          AppleIDAuthorizationScopes.email,
          AppleIDAuthorizationScopes.fullName,
        ],
      );
      
      // Format the auth data as expected by the Zulip server
      return {
        'id_token': credential.identityToken,
        'code': credential.authorizationCode,
        'user': {
          'name': {
            'firstName': credential.givenName,
            'lastName': credential.familyName,
          },
          'email': credential.email,
        },
      };
    } catch (e) {
      debugPrint('Error during Apple Sign In: $e');
      rethrow;
    }
  }
  
  /// Sends the Apple auth data to the Zulip server
  static Future<Map<String, dynamic>> authenticateWithServer(
    String serverUrl,
    Map<String, dynamic> appleAuthData,
  ) async {
    final uri = Uri.parse('$serverUrl/api/v1/fetch_api_key');
    
    try {
      final response = await http.post(
        uri,
        headers: {'Content-Type': 'application/json'},
        body: jsonEncode({
          'method': 'apple',
          'id_token': appleAuthData['id_token'],
          'code': appleAuthData['code'],
        }),
      );
      
      if (response.statusCode == 200) {
        return jsonDecode(response.body);
      } else {
        throw Exception('Failed to authenticate: ${response.body}');
      }
    } catch (e) {
      debugPrint('Error authenticating with server: $e');
      rethrow;
    }
  }
}

Step 4: Update the Login Screen

Now, let's update the login screen to include the Apple Sign In button:

import 'package:flutter/material.dart';
import 'package:sign_in_with_apple/sign_in_with_apple.dart';
import 'package:zulip_flutter/auth/apple_auth_service.dart';

class LoginScreen extends StatefulWidget {
  final String serverUrl;
  
  const LoginScreen({Key? key, required this.serverUrl}) : super(key: key);
  
  @override
  _LoginScreenState createState() => _LoginScreenState();
}

class _LoginScreenState extends State<LoginScreen> {
  bool _isAppleAuthAvailable = false;
  bool _isLoading = false;
  
  @override
  void initState() {
    super.initState();
    _checkAppleAuthAvailability();
  }
  
  Future<void> _checkAppleAuthAvailability() async {
    final isAvailable = await AppleAuthService.isAvailable();
    final serverHost = Uri.parse(widget.serverUrl).host;
    final canUseNative = AppleAuthService.canUseNativeAppleAuthForServer(serverHost);
    
    setState(() {
      _isAppleAuthAvailable = isAvailable && canUseNative;
    });
  }
  
  Future<void> _handleAppleSignIn() async {
    setState(() {
      _isLoading = true;
    });
    
    try {
      final appleAuthData = await AppleAuthService.signInWithApple();
      final serverResponse = await AppleAuthService.authenticateWithServer(
        widget.serverUrl,
        appleAuthData,
      );
      
      // Handle successful authentication
      // Navigate to home screen or store auth token
      
    } catch (e) {
      // Handle error
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Authentication failed: $e')),
      );
    } finally {
      setState(() {
        _isLoading = false;
      });
    }
  }
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Sign in to Zulip'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            // Other login options...
            
            if (_isAppleAuthAvailable) ...[
              const SizedBox(height: 16),
              SignInWithAppleButton(
                onPressed: _isLoading ? null : _handleAppleSignIn,
                style: SignInWithAppleButtonStyle.black,
              ),
            ],
            
            // Web-based login fallback...
          ],
        ),
      ),
    );
  }
}

Step 5: Update the Auth Manager

Finally, let's update the auth manager to handle Apple authentication:

import 'package:flutter/material.dart';
import 'package:zulip_flutter/auth/apple_auth_service.dart';

class AuthManager {
  // Existing code...
  
  Future<bool> handleAppleAuth(BuildContext context, String serverUrl) async {
    final serverHost = Uri.parse(serverUrl).host;
    
    // Check if we can use native Apple auth for this server
    if (Platform.isIOS && 
        await AppleAuthService.isAvailable() && 
        AppleAuthService.canUseNativeAppleAuthForServer(serverHost)) {
      try {
        final appleAuthData = await AppleAuthService.signInWithApple();
        final serverResponse = await AppleAuthService.authenticateWithServer(
          serverUrl,
          appleAuthData,
        );
        
        // Store the API key and user info
        await _storeCredentials(
          serverUrl,
          serverResponse['email'],
          serverResponse['api_key'],
        );
        
        return true;
      } catch (e) {
        debugPrint('Native Apple auth failed: $e');
        // Fall back to web-based flow
        return _handleWebBasedAuth(context, serverUrl, 'apple');
      }
    } else {
      // Use web-based flow for non-iOS or when native flow isn't available
      return _handleWebBasedAuth(context, serverUrl, 'apple');
    }
  }
  
  // Existing web-based auth method...
}

Testing Instructions

To test this implementation:

1. Ensure you have an Apple Developer account
2. Configure your app with the correct bundle ID and team ID in Xcode
3. Add the Sign In with Apple capability in Xcode
4. Run the app on a physical iOS device (simulator won't work for Apple Sign In)
5. Try signing in with Apple on both Zulip Cloud and a development server

This implementation follows the pattern from the legacy app while using the Flutter-specific sign_in_with_apple package. It handles the authentication flow, communicates with the Zulip server, and provides a fallback to the web-based flow when needed.

[gnprice]

@shkshreyas It looks like you asked ChatGPT or another LLM how to solve this issue, and then just pasted its response into the comment box. That isn't useful.

If you'd like to contribute to Zulip, see our contributing guide, linked from the README.