Skip to main content

Platform Setup

Authentication runs in the external browser. When it finishes, the browser opens a URL with your app's custom scheme, and the OS hands that URL back to the app. You register the scheme in the app; the library does not add it to your Manifest or Info.plist.

Use the same scheme string on iOS (CFBundleURLSchemes) and Android (<data android:scheme="...">). They must match exactly. macOS needs no registration; see macOS.

iOS​

Add the scheme to ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<string>com.yourcompany.yourapp</string>
<key>CFBundleURLSchemes</key>
<array>
<string>yourscheme</string>
</array>
</dict>
</array>

Android​

Add CallbackActivity from flutter_web_auth_2 to android/app/src/main/AndroidManifest.xml:

<activity
android:name="com.linusu.flutter_web_auth_2.CallbackActivity"
android:exported="true"
android:taskAffinity="">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<!-- Minimum: scheme only -->
<data android:scheme="yourscheme" />
<!-- Optional (OAuth only): restrict host/path to the custom scheme URL the browser finally opens.
MiAuth calls back to `yourscheme://` without host/path, so keep the scheme-only filter if you use MiAuth. -->
<!-- <data android:scheme="yourscheme" android:host="oauth" android:path="/callback" /> -->
</intent-filter>
</activity>

A complete configuration is in example/android/app/src/main/AndroidManifest.xml. Treat it as the reference for Android.

Notes:

  • The android:label attribute on the <intent-filter> is optional.
  • On Android 12 and later (API 31+), an Activity with an intent-filter must declare android:exported="true".
  • Apps that make network requests must declare <uses-permission android:name="android.permission.INTERNET" /> directly under <manifest> in android/app/src/main/AndroidManifest.xml. A declaration in the debug or profile Manifest does not apply to release builds.
  • If you restrict the intent-filter by host or path, match the custom scheme URL that the browser finally opens: redirect_uri itself, or the URL that your relay page forwards to. Do not restrict it if you also use MiAuth, which calls back to yourscheme://.

When the Browser Tab Stays Open​

The sample Manifest sets android:taskAffinity="" on both the exported MainActivity and CallbackActivity, as flutter_web_auth_2 recommends.

With that setting, the browser tab may stay open after authentication when the default browser does not support Auth Tab (for example, Chrome earlier than 137). Authentication still succeeds, but the user has to close the tab. flutter_web_auth_2 uses Auth Tab when the browser supports it and falls back to a Custom Tab otherwise. On the fallback path tested with Chrome 109, Chrome starts CallbackActivity in a new task, so it cannot close the tab left in the app's task.

  • To close the tab on the fallback path too, remove android:taskAffinity="" from both MainActivity and CallbackActivity. Removing it from only one of them does not help. With Auth Tab, this change is not needed; on Android 13 with Chrome 154, the tab closed with either setting.
  • taskAffinity="" is sometimes used as a partial mitigation against task hijacking (StrandHogg) on devices before Android 11 (API 30). Android's own recommendation for this vulnerability is minSdkVersion 30 or later. See flutter_web_auth_2 issue #158 for the upstream discussion.

PlatformException(CANCELED, User canceled login, ...)​

The library reports this as UserCancelledException. If it happens even though the user did not cancel, common causes are:

  1. The callback did not reach the app. Check that CallbackActivity has a matching <intent-filter>.
  2. A PWA or another app intercepted the link.
  3. The redirect_uri did not exactly match a <link rel="redirect_uri"> on the client_id page, so Misskey did not redirect back.

macOS​

macOS needs no scheme registration. flutter_web_auth_2 opens the authentication page in ASWebAuthenticationSession, which receives the callback URL directly, so you do not add CFBundleURLTypes to macos/Runner/Info.plist.

Add the following entitlements to both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<!-- Requests from the sandboxed app to the Misskey server -->
<key>com.apple.security.network.client</key>
<true/>
<!-- The keychain that SecureTokenStore uses by default -->
<key>keychain-access-groups</key>
<array/>

A complete configuration is in example/macos/Runner/.

Notes:

  • keychain-access-groups requires the app to be signed by your Apple Developer team with a provisioning profile. In Xcode, open macos/Runner.xcworkspace and select your team under Signing & Capabilities of the Runner target. Without a team, Xcode cannot sign the app with this entitlement.
  • With a free Apple Developer account, the development provisioning profile only lets the app launch on the Mac that built it.
  • If keychain-access-groups is missing, saving a token fails with a PlatformException with code -34018.

Storing Tokens Without keychain-access-groups​

If you do not want the entitlement, pass a FlutterSecureStorage that does not use the data protection keychain. mOptions applies only on macOS, so the same code works on the other platforms:

import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:misskey_auth/misskey_auth.dart';

final auth = MisskeyAuthManager(
miauth: MisskeyMiAuthClient(),
oauth: MisskeyOAuthClient(),
store: const SecureTokenStore(
storage: FlutterSecureStorage(
mOptions: MacOsOptions(usesDataProtectionKeychain: false),
),
),
);
  • Tokens saved with one setting cannot be read with the other. If you switch after release, users must sign in again.
  • This setting only changes where tokens are stored. Distributing the app still requires signing and notarization as usual.