Frappe OAuth2 Flutter SDK #

A clean, headless Flutter SDK for OAuth2 authentication with Frappe servers. This SDK provides a simplified, developer-friendly API without UI components, allowing you to integrate OAuth2 authentication seamlessly into your Flutter applications.

✨ Features #

• 🔐 Complete OAuth2 Flow - Authorization code flow with PKCE support
• 📱 Cross-Platform - iOS, Android, Web, macOS, Windows, Linux
• 🎯 Headless Design - No UI components, you control the interface
• 💾 Simple Storage - SharedPreferences-based token storage
• 🔄 Auto Token Refresh - Automatic token management
• 🛡️ Secure - PKCE implementation, secure token handling
• 🧪 Well Tested - 85+ unit tests with comprehensive coverage
• 📚 Comprehensive Docs - Detailed guides and API reference

Quick Start #

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  frappe_oauth2_flutter_sdk: ^0.1.0

Basic Usage #

import 'package:frappe_oauth2_flutter_sdk/frappe_oauth2_flutter_sdk.dart';

// 1. Configure
final config = OAuthConfig(
  baseUrl: 'https://your-frappe-server.com',
  clientId: 'your-client-id',
  redirectScheme: 'yourapp',
  scopes: ['openid', 'profile', 'email'],
);

// 2. Create client
final client = await FrappeOAuthClient.create(config: config);

// 3. Login
final result = await client.login();
if (result.isSuccess) {
  print('Logged in as: ${result.userInfo?.email}');
} else if (result.isCancelled) {
  print('User cancelled login');
} else {
  print('Login failed: ${result.error?.message}');
}

// 4. Check authentication
if (await client.isAuthenticated()) {
  final token = await client.getAccessToken();
  // Use token for API calls
}

// 5. Logout
await client.logout();

� Understanding Redirect URIs #

The redirect URI is critical for OAuth2 to work. It tells the Frappe server where to send the user after authentication.

Format: scheme://host Example: trascango://oauth2redirect

⚠️ Important: Three-Way Configuration Match #

For OAuth2 to work, the redirect URI must match in three places:

1. Frappe Server - OAuth2 Client configuration
2. Flutter Code - OAuthConfig.redirectScheme
3. Platform Config - AndroidManifest.xml and Info.plist

If these don't match, you'll get a redirect mismatch error!

Example Configuration #

Frappe Server Setup (Setup → OAuth2 Client):

• Client ID: q5n9973f9e
• Redirect URI: trascango://oauth2redirect
• Default Redirect URI: trascango://oauth2redirect

Flutter Code:

final config = OAuthConfig(
  baseUrl: 'https://your-frappe-server.com',
  clientId: 'q5n9973f9e',
  redirectScheme: 'trascango',  // ← Must match Frappe server!
  scopes: ['openid', 'profile', 'email'],
);

Android (android/app/src/main/AndroidManifest.xml):

<activity
    android:name="com.linusu.flutter_web_auth_2.CallbackActivity"
    android:exported="true"
    android:launchMode="singleTop">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Must match redirectScheme: 'trascango' -->
        <data android:scheme="trascango" android:host="oauth2redirect" />
    </intent-filter>
</activity>

iOS (ios/Runner/Info.plist):

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>OAuth2 Redirect</string>
        <!-- Must match redirectScheme: 'trascango' -->
        <key>CFBundleURLSchemes</key>
        <array>
            <string>trascango</string>
        </array>
    </dict>
</array>

📋 Platform Setup #

For detailed platform-specific setup instructions, see Platform Setup Guide.

Quick Reference #

Android: Add CallbackActivity to AndroidManifest.xml with your redirect scheme iOS: Add CFBundleURLTypes to Info.plist with your redirect scheme Web: No additional configuration needed macOS/Windows/Linux: See Platform Setup Guide

📚 Documentation #

• Redirect URI Guide - ⭐ Start here! Complete guide to redirect URI configuration
• Quick Start Guide - Get up and running in 10 minutes
• API Reference - Complete API documentation
• Platform Setup - Detailed platform configuration with troubleshooting
• Best Practices - Security and architecture patterns

🧪 Testing #

The SDK includes comprehensive unit tests with 85+ test cases:

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

🔧 API Overview #

Core Classes #

• FrappeOAuthClient - Main authentication client
• OAuthConfig - Configuration settings
• AuthResult - Authentication result wrapper
• UserInfo - User profile information
• TokenResponse - OAuth2 token data

Key Methods #

// Factory constructor
static Future<FrappeOAuthClient> create({required OAuthConfig config})

// Authentication
Future<AuthResult> login()
Future<void> logout()

// State management
Future<bool> isAuthenticated()
Future<UserInfo?> getCurrentUser()
Future<String?> getAccessToken()
Future<TokenResponse?> refreshToken()

🛡️ Security Features #

• PKCE Implementation - Proof Key for Code Exchange
• Secure Token Storage - SharedPreferences with validation
• Automatic Token Refresh - Background token management
• Deep Link Validation - Secure callback URL handling
• Configuration Validation - Prevents common setup errors

🔧 Troubleshooting #

Redirect Mismatch Error #

Error: "Redirect URI mismatch" from Frappe server

Solution: Ensure the redirect URI matches in all three places:

1. Frappe Server (Setup → OAuth2 Client):

   Redirect URI: trascango://oauth2redirect
   

2. Flutter Code:

   redirectScheme: 'trascango'
   

3. Android (AndroidManifest.xml):

   <data android:scheme="trascango" android:host="oauth2redirect" />
   

4. iOS (Info.plist):

   <string>trascango</string>
   

App Doesn't Receive Callback #

Checklist:

• ❌ CallbackActivity added to AndroidManifest.xml
• ❌ CFBundleURLTypes added to Info.plist
• ❌ Scheme matches in all configurations
• ❌ App rebuilt after changes: flutter clean && flutter pub get && flutter run
• ❌ App reinstalled on device

Other Issues #

For more troubleshooting steps, see Platform Setup Guide - Troubleshooting.

🤝 Contributing #

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the Frappe community