Fixed - CRITICAL OAuth2 Compatibility Issues #

Issue 1: PKCE Parameters Not Supported by Frappe

• Problem: SDK was unconditionally sending PKCE parameters (code_challenge, code_challenge_method) in authorization requests
• Root Cause: Frappe OAuth2 does not support PKCE, causing 404 errors
• Fix: Made PKCE parameters optional in UrlBuilder.buildAuthorizationUrlStatic()
• Impact: Authorization requests now work with Frappe OAuth2 servers

Issue 2: Token Exchange Using Wrong Content-Type

• Problem: Token exchange was sending application/json instead of application/x-www-form-urlencoded
• Root Cause: Used body parameter instead of formData in network service
• Fix: Changed token exchange to use formData parameter in _exchangeCodeForTokens()
• Impact: Token exchange now succeeds with Frappe OAuth2 servers

Issue 3: Removed Unused PKCE Code

• Removed _generateCodeChallenge() method (no longer needed)
• Removed unused crypto package import
• Cleaned up code generation for PKCE parameters

Technical Changes #

• lib/utils/url_builder.dart: Made codeChallenge and codeChallengeMethod optional parameters
• lib/frappe_oauth_client_simple.dart:
  • Removed PKCE parameters from authorization URL
  • Changed token exchange to use form data
  • Removed unused code challenge generation
• pubspec.yaml: Bumped version to 0.1.4

Why This Fix Matters #

• Before: OAuth2 flow failed with 404 errors at authorization and token exchange steps
• After: OAuth2 flow works correctly with Frappe OAuth2 servers
• Before: All users experienced authentication failures
• After: Users can successfully authenticate with Frappe servers

Testing #

• All 107 existing tests pass
• OAuth2 flow now compatible with Frappe OAuth2 specification
• Tested against Frappe server at https://ako.nesscale.com

Fixed #

• CRITICAL: Fixed OAuth2 redirect handling - Chrome Custom Tab now closes automatically
• Added FlutterWebAuth2Options with 120-second timeout to web authentication flow
• Prevents 404 errors when manually closing the Chrome Custom Tab
• Ensures authorization code is properly received after authentication

Technical Details #

• Chrome Custom Tab now closes automatically after successful authentication
• 120-second timeout gives users sufficient time to enter credentials
• Matches working app implementation (tra_scango)
• Prevents indefinite waiting for user authentication
• Proper error handling for timeout scenarios

Why This Fix Matters #

• Before: Chrome Custom Tab stayed open indefinitely, user had to manually close it
• After: Tab closes automatically, seamless redirect back to app
• Before: Manually closing tab resulted in 404 error instead of authorization code
• After: Authorization code properly extracted and processed

Fixed #

• Removed package attribute from plugin's AndroidManifest.xml to fix Android Gradle plugin compatibility
• Resolves "Incorrect package attribute" error in newer Android Gradle versions
• CRITICAL: Fixed OAuth2 scope handling - Updated to use only Frappe-supported scopes (openid and all)
• Corrected example code that was using unsupported scopes (profile, email)

Technical Details #

• Android Gradle plugin no longer supports package attribute in library manifests
• Namespace is now defined in build.gradle instead
• This fix ensures compatibility with latest Android build tools
• Frappe OAuth2 only supports openid and all scopes (not standard OIDC scopes like profile, email)
• User information is available via /openid_profile endpoint, not through scopes

Documentation #

• Enhanced OAuthConfig documentation to clarify Frappe-supported scopes
• Added comprehensive scope handling guide (FRAPPE_OAUTH2_SCOPES_GUIDE.md)
• Added detailed scope analysis and migration guide (SCOPE_HANDLING_CORRECTED.md)
• Updated example code with correct scopes and explanatory comments

Fixed #

• Improved redirect URI configuration documentation to prevent mismatch errors
• Added comprehensive platform setup guides for Android and iOS
• Enhanced example app with proper OAuth2 callback activity configuration
• Added troubleshooting guide for common redirect issues

Added #

• Detailed redirect URI configuration examples in README
• Three-way configuration matching guide (Frappe Server, Flutter Code, Platform Config)
• Platform-specific troubleshooting section in documentation
• Example configurations for Android (AndroidManifest.xml) and iOS (Info.plist)
• Debug steps for testing redirect URIs

Documentation #

• Updated README with redirect URI explanation and examples
• Enhanced Platform Setup Guide with troubleshooting section
• Added common error scenarios and solutions
• Included debug commands for testing OAuth2 callbacks

Added #

• Complete OAuth2 authorization code flow with PKCE support
• Cross-platform support (iOS, Android, Web, macOS, Windows, Linux)
• Headless design with no UI components - developers control the interface
• SharedPreferences-based token storage for simplicity
• Automatic token refresh functionality
• Comprehensive error handling with specific exception types
• 85+ unit tests with high code coverage
• Complete API documentation and guides

Features #

• Factory constructor pattern for clean initialization (FrappeOAuthClient.create())
• Configuration validation to prevent common setup errors
• Deep link security validation for OAuth callbacks
• PKCE implementation for enhanced mobile security
• Support for custom scopes and redirect schemes
• Clean, intuitive API with helper getters (isSuccess, isCancelled, etc.)

Documentation #

• Quick start guide for 10-minute setup
• Complete API reference with examples
• Platform setup guides for all supported platforms
• Best practices documentation for security and architecture
• Comprehensive troubleshooting guide

Security #

• PKCE (Proof Key for Code Exchange) implementation
• Secure token storage with validation
• Deep link validation to prevent security issues
• Configuration validation to prevent misconfigurations
• No client secrets required (more secure for mobile apps)