auth_uae_pass 0.0.5

The definitive Flutter SDK for UAE PASS authentication. Seamlessly integrate United Arab Emirates' national identity system (UAEPASS) with support for native redirects, webview fallbacks, and user pro [...]

UAE PASS Authentication for Flutter (UAEPASS SDK)

The definitive, production-ready Flutter package for UAE PASS, the United Arab Emirates' official digital identity. Built for robustness, security, and developer ease-of-use, this SDK handles native app redirects, deep link resumption, and OIDC token flows out of the box with over 120+ UI variations.

🌟 Key Features

• ⚡ Zero-Setup Lazy Resumption: Automatically handles deep link returns (even after app restarts) without complex initState logic.
• 🛡️ Simplified API: One-call signInWithProfile handles context, token exchange, and profile retrieval.
• 🎨 120+ Button Variations: Dark, Outline, and Logo-only variants with customizable borders, radii, and grayscale modes.
• 🌍 Native RTL Support: Built-in support for Arabic (LTR/RTL flipping) compliant with official design guidelines.
• 📱 Intelligent App Detection: Gracefully falls back to Web/Push flows if the UAE PASS app is not installed.
• 🛠️ SOP Level Detection: Automatically detects and returns the Success Of Person (SOP) level (Biometrics vs Password).

---

🛠️ Platform Configuration (CRITICAL)

To handle the "Coming back from UAE PASS" flow correctly, you must configure your native platforms to listen for your redirect URI.

🤖 Android (AndroidManifest.xml)

1. Set Launch Mode: Your MainActivity MUST be singleTask.
2. Add Intent Filter: Register your redirect scheme.
3. Package Queries: Allow the app to "see" UAE PASS.

<activity
    android:name=".MainActivity"
    android:launchMode="singleTask"
    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|screenLayout|density|uiMode"
    android:hardwareAccelerated="true"
    android:windowSoftInputMode="adjustResize">
    
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="your_app_scheme" />
    </intent-filter>
</activity>

<!-- Allow detecting UAE PASS apps -->
<queries>
    <package android:name="ae.uaepass.mainapp" />
    <package android:name="ae.uaepass.mainapp.stg" />
    <package android:name="ae.uaepass.mainapp.qa" />
</queries>

🍎 iOS (Info.plist)

1. URL Types: Register your custom scheme.
2. Query Schemes: Allow the app to check for UAE PASS native apps.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>your_app_scheme</string>
        </array>
    </dict>
</array>

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>uaepass</string>
    <string>uaepassstg</string>
    <string>uaepassqa</string>
</array>

---

🚀 Usage

1. Simple Authentication (All-in-One)

The simplest way to integrate is using signInWithProfile. This method handles the browser popup, token exchange, and profile fetching in a single call.

import 'package:auth_uae_pass/auth_uae_pass.dart';

final auth = AuthUaePass();

void _login(BuildContext context) async {
  final UaePassAuthData result = await auth.signInWithProfile(
    context,
    clientId: 'your_client_id',
    clientSecret: 'your_client_secret',
    redirectUri: 'your_app_scheme://',
    environment: UaePassEnvironment.staging, // Use .production for live
    uiLocale: 'en', // 'en' or 'ar'
  );

  if (result.isSuccess && result.profile != null) {
      print('Welcome, ${result.profile!.fullNameEN}');
      print('SOP Level: ${result.sopLevel}');
  }
}

2. Silent Logout

Background logout via HeadlessInAppWebView—no more blank/black screen flickers. This ensures the next login attempt starts with a clean session.

void _onLogout(BuildContext context) async {
  await auth.logout(
    context,
    environment: UaePassEnvironment.staging,
    redirectUri: 'your_app_scheme://',
  );
  print('Logged out from UAE PASS session');
}

3. User Profile Data

The signInWithProfile method returns a UaePassAuthData object containing the following structure:

Field	Type	Description
isSuccess	bool	Helper to check if authentication succeeded
status	UaePassFlowStatus	Enum: loginSuccess, cancelled, error, etc.
profile	UaePassUserProfile?	Detailed user data (see below)
token	UaePassUserToken?	Access, ID, and Refresh tokens
sopLevel	UaePassSopLevel	Enum: sop1, sop2, sop3, or none
errorCode	String?	Technical error code from UAE PASS
errorDescription	String?	Human-readable error description

UaePassUserProfile Fields

Field	Description
sub	Subject identifier (Unique for the user)
uuid	Unique user identifier (Alternative UUID)
spuuid	Service Provider specific UUID
idn	Emirates ID Number
unifiedId	Unified ID (available with Visitor Integration)
email	User's verified email address
mobile	User's verified mobile number
fullNameEN / fullNameAR	User's full name in English/Arabic
firstnameEN / firstnameAR	User's first name in English/Arabic
lastnameEN / lastnameAR	User's last name in English/Arabic
titleEN / titleAR	User's title (e.g. Mr., Ms.) in English/Arabic
nationalityEN / nationalityAR	User's nationality
gender	User's gender
userType	Type of user (e.g. SOP1, SOP2)
idType	Type of identity document
profileType	Resident vs Visitor profile type
acr	Authentication Context Class Reference
amr	List of Authentication Methods References
raw	Full Map of all raw claims returned by UAE PASS

4. Custom Login Button

The package includes a highly customizable login button that adheres to official branding.

UaePassLoginButton(
  onPressed: _login,
  language: UaePassButtonLanguage.english, // or .arabic
  labelType: UaePassButtonLabelType.continueWith,
  style: UaePassButtonStyle.outlineVariant(
    border: Colors.teal,
    radius: 14,
  ),
)

5. Logo Only Variations

For compact layouts or social login grids.

UaePassLoginButton(
  onPressed: _login,
  hideLabel: true,
  style: UaePassButtonStyle.darkVariant(
    background: Colors.black,
    radius: 100, // Makes it a circle
  ).copyWith(height: 48, width: 48),
)

---

🏁 Final Checks

Check	Success Criteria
Android LaunchMode	Must be singleTask
Redirect URI	Must match the service provider portal dashboard EXACTLY
Custom Scheme	Same as Redirect URI scheme
Environment	Production credentials will NOT work in Staging environment

---

💡 Advanced Scenarios

Cold Start Resumption

If your app is terminated while the user is inside the UAE PASS native app, the deep link is saved. When the user returns and you call signInWithProfile() again, the package instantly detects the pending link and completes the login without showing a browser popup.

Visitor Integration

To fetch unifiedID and profileType, the first authentication must use the extended visitor scope. You can enable this in the configuration:

final result = await auth.signInWithProfile(
  context,
  // ... other params
  visitorIntegrationFirstAuth: true,
);

SOP Level Detection

The package automatically identifies the "Success Of Person" level used for authentication:

• sop1: Simple Password.
• sop2: Biometrics (Fingerprint/FaceID).
• sop3: Verified Face ID (Official Govt verification).

Check this via result.sopLevel in the UaePassAuthData.

---

License

MIT License - see LICENSE for details.

---

🔍 Search & Discovery Keywords

UAE PASS | UAEPASS | United Arab Emirates | Digital Identity | Official SDK | Smart Dubai | TDRA | Authentication | OIDC | Identity Provider | Dubai | Abu Dhabi | Emirates ID | KYC