Overview

Relevant source files

• README.md
• assets/ios-sso-alert.png
• auth0_flutter/CHANGELOG.md
• auth0_flutter/README.md
• auth0_flutter/android/src/main/AndroidManifest.xml
• auth0_flutter/darwin/auth0_flutter.podspec
• auth0_flutter/example/.env.example
• auth0_flutter/example/.gitignore
• auth0_flutter/example/README.md
• auth0_flutter/example/android/app/src/main/AndroidManifest.xml
• auth0_flutter/ios/auth0_flutter.podspec
• auth0_flutter/lib/src/version.dart
• auth0_flutter/macos/auth0_flutter.podspec
• auth0_flutter/pubspec.yaml
• auth0_flutter_platform_interface/CHANGELOG.md
• auth0_flutter_platform_interface/README.md
• auth0_flutter_platform_interface/pubspec.yaml

Purpose and Scope

This document provides a high-level introduction to the auth0-flutter repository, an Auth0 SDK for Flutter applications supporting Android, iOS, macOS, and Web platforms. The SDK enables Flutter developers to integrate authentication and authorization functionality from Auth0 into their cross-platform applications.

This overview covers the repository structure, core components, and architectural patterns. For detailed information about specific aspects:

• Package architecture and federated plugin design: see Package Architecture
• Platform-specific requirements and minimum versions: see Platform Support
• Core SDK functionality and APIs: see Core SDK (auth0_flutter)
• Usage examples and integration patterns: see Usage Guide and Examples

---

What is auth0-flutter

The auth0-flutter repository contains a Flutter SDK that provides:

• Universal Login integration via browser-based authentication flows
• Authentication API access for custom UI implementations
• Credentials Management with automatic token renewal and secure storage
• DPoP (Demonstrating Proof of Possession) support for enhanced token security
• Multi-platform support with optimized native implementations

The SDK is distributed as two pub.dev packages:

Package	Version	Purpose
auth0_flutter	2.0.0-beta.5	Main SDK package for application integration
auth0_flutter_platform_interface	2.0.0-beta.4	Platform abstraction layer and shared contracts

Sources: auth0_flutter/pubspec.yaml1-8 auth0_flutter_platform_interface/pubspec.yaml1-3 README.md7-12

---

Repository Structure

The repository follows a federated plugin architecture with clear separation between platform-agnostic Dart code and platform-specific native implementations:

The main SDK package (auth0_flutter) depends on the platform interface package and includes platform-specific implementations for Android, iOS/macOS (Darwin), and Web. The platform interface defines abstract contracts that each implementation must fulfill.

Sources: auth0_flutter/pubspec.yaml1-56 auth0_flutter_platform_interface/pubspec.yaml1-14 README.md9-12

---

Core Components

The SDK exposes three primary components through the main entry point classes:

SDK Entry Points

Applications instantiate one of two classes depending on the target platform:

• Auth0 class: Used for Android, iOS, and macOS applications. Constructed with domain and client ID parameters.
• Auth0Web class: Used for web applications. Provides web-specific functionality like popup-based authentication.

Three Core APIs

1. WebAuthentication API (webAuthentication())

   • Browser-based Universal Login flows
   • Supports both redirect and popup patterns (web)
   • Handles OAuth/OIDC protocol interactions
   • Platform-specific browser integration (SafariViewController, Custom Tabs)

2. Authentication API (api property)

   • Direct API calls for custom UI implementations
   • Login, signup, password reset operations
   • Passwordless authentication (OTP, email, SMS)
   • Multi-factor authentication challenges
   • Token refresh and exchange

3. Credentials Manager (credentialsManager property)

   • Secure credential storage using platform keychains
   • Automatic access token renewal
   • Biometric authentication integration
   • Credential validation and lifecycle management

Sources: auth0_flutter/README.md131-293 auth0_flutter/lib/src/version.dart1

---

Architecture Patterns

Federated Plugin Pattern

The SDK implements Flutter's federated plugin architecture, which separates interface definitions from platform implementations:

Plugin Registration

The plugin registers with Flutter using platform-specific plugin classes defined in pubspec.yaml:

Platform	Plugin Class	File Location
Android	Auth0FlutterPlugin	android/src/main/kotlin/
iOS	Auth0FlutterPlugin	darwin/Classes/ (shared)
macOS	Auth0FlutterPlugin	darwin/Classes/ (shared)
Web	Auth0FlutterPlugin	lib/src/web.dart

The sharedDarwinSource: true configuration in pubspec.yaml enables code sharing between iOS and macOS implementations.

Sources: auth0_flutter/pubspec.yaml38-56 auth0_flutter/ios/auth0_flutter.podspec1-29 auth0_flutter/darwin/auth0_flutter.podspec1-29

---

Key Features

Authentication Methods

• Browser-based Universal Login: OAuth/OIDC compliant authentication flows
• Passwordless Authentication: Email, SMS, and one-time password (OTP) support
• Multi-Factor Authentication: Challenge/response MFA flows
• Custom Token Exchange: Support for custom authentication tokens
• Native to Web SSO: Session transfer from native apps to WebViews

Security Features

• DPoP Token Binding: RFC 9449 compliant proof-of-possession tokens
• ID Token Validation: JWT signature verification
• Biometric Authentication: Platform-native biometric prompts for credential access
• Secure Storage: Platform keychain integration (Keychain on iOS/macOS, EncryptedSharedPreferences on Android)

Platform-Specific Optimizations

• Android: Custom Tabs for authentication, Android API 21+ support
• iOS/macOS: SafariViewController/ASWebAuthenticationSession, Universal Links support (iOS 17.4+/macOS 14.4+)
• Web: Popup and redirect authentication patterns, WASM compilation support (Flutter 3.24.0+)

Sources: auth0_flutter/README.md356-392 auth0_flutter/CHANGELOG.md1-36 auth0_flutter_platform_interface/CHANGELOG.md1-35

---

SDK Requirements

The SDK has specific minimum version requirements across platforms:

Component	Minimum Version
Flutter SDK	3.24.0+
Dart SDK	3.5.0+
Android API	21+
Android Java	8+
iOS	14+
macOS	11+
Swift	5.9+
Xcode	15.x / 16.x

Native SDK Dependencies:

Sources: auth0_flutter/README.md29-35 auth0_flutter/pubspec.yaml6-16 auth0_flutter/ios/auth0_flutter.podspec16-24 auth0_flutter/darwin/auth0_flutter.podspec16-24

---

Distribution and Publication

The SDK is distributed through pub.dev as two separate packages that are versioned independently:

• Main package: Published with af-v* git tags (e.g., af-v2.0.0-beta.5)
• Platform interface: Published with afpi-v* git tags (e.g., afpi-v2.0.0-beta.4)

Both packages undergo security scanning via Reversing Labs before publication. The CI/CD pipeline automates testing across all platforms and aggregates code coverage reports to Codecov.

Sources: auth0_flutter/pubspec.yaml1-4 auth0_flutter_platform_interface/pubspec.yaml1-3 README.md1-35

---

Getting Started

To begin using the SDK:

1. Install the package: flutter pub add auth0_flutter
2. Configure Auth0 Dashboard with callback URLs
3. Initialize the SDK with your Auth0 domain and client ID
4. Use the appropriate APIs for your authentication flow

For detailed setup instructions and code examples, see Getting Started and Authentication Flows.

Sources: auth0_flutter/README.md37-293 auth0_flutter/example/README.md1-92