|
| 1 | +--- |
| 2 | +title: Stricter Android `Intent` Verification for App Entrypoints |
| 3 | +description: >- |
| 4 | + Android `Intent` extras for routing, entrypoints, and cached engines |
| 5 | + are now strictly verified. |
| 6 | +--- |
| 7 | + |
| 8 | +{% render "docs/breaking-changes.md" %} |
| 9 | + |
| 10 | +## Summary |
| 11 | + |
| 12 | +To prevent [`Intent`][]-based vulnerability exploits, |
| 13 | +the Flutter Android embedder |
| 14 | +(`FlutterActivity` and `FlutterFragmentActivity`) |
| 15 | +now verifies the sender of `Intent` objects |
| 16 | +before processing `EXTRA_INITIAL_ROUTE`, `EXTRA_DART_ENTRYPOINT`, |
| 17 | +`EXTRA_DART_ENTRYPOINT_ARGS`, `EXTRA_CACHED_ENGINE_ID`, |
| 18 | +and `EXTRA_CACHED_ENGINE_GROUP_ID`. |
| 19 | + |
| 20 | +In release mode, external `Intent` objects cannot set these extras |
| 21 | +unless verified as originating from the app itself. |
| 22 | +If verification fails, the embedder ignores the extras |
| 23 | +and falls back to manifest metadata or default values for initial routes |
| 24 | +and Dart entrypoints. |
| 25 | + |
| 26 | +## Context |
| 27 | + |
| 28 | +Previously, the Flutter Android embedder accepted routing, entrypoint, |
| 29 | +and engine configuration directly from `Intent` extras. |
| 30 | +This allowed external apps or malicious actors to: |
| 31 | + |
| 32 | +1. Hijack app navigation to sensitive internal routes |
| 33 | + (`EXTRA_INITIAL_ROUTE`). |
| 34 | +1. Execute arbitrary Dart entrypoints or pass unsafe arguments |
| 35 | + (`EXTRA_DART_ENTRYPOINT` and `EXTRA_DART_ENTRYPOINT_ARGS`). |
| 36 | +1. Reuse active, pre-authenticated in-memory engine instances |
| 37 | + (`EXTRA_CACHED_ENGINE_ID` and `EXTRA_CACHED_ENGINE_GROUP_ID`). |
| 38 | + |
| 39 | +To fix these vulnerabilities, Flutter now validates the `Intent` sender. |
| 40 | +Deep links remain supported, |
| 41 | +but they must match the `<intent-filter>` declarations |
| 42 | +in your `AndroidManifest.xml`. |
| 43 | + |
| 44 | +## Description of change |
| 45 | + |
| 46 | +In release builds, the Android embedder strictly validates `Intent` extras: |
| 47 | +`"route"`, `"dart_entrypoint"`, `"dart_entrypoint_args"`, |
| 48 | +`"cached_engine_id"`, and `"cached_engine_group_id"`. |
| 49 | + |
| 50 | +### Intent verification rules |
| 51 | + |
| 52 | +An `Intent` is verified as safe if: |
| 53 | + |
| 54 | +* **The activity is not exported:** |
| 55 | + Activities with `android:exported="false"` are automatically trusted. |
| 56 | +* **On Android 14 and later (API 34+):** |
| 57 | + The launching UID matches the application's UID (`getLaunchedFromUid()`). |
| 58 | +* **On Android 13 and earlier (API 33 and lower):** |
| 59 | + The calling package matches the app package (`getCallingPackage()`). |
| 60 | + This requires launching with `startActivityForResult()` |
| 61 | + or `startActivityIfNeeded()`. |
| 62 | + |
| 63 | +For deep links (`Intent.ACTION_VIEW`), |
| 64 | +the link URI must match an `<intent-filter>` |
| 65 | +declared in the application manifest, |
| 66 | +unless the `Intent` is verified as self-sent. |
| 67 | + |
| 68 | +### Fallback behavior |
| 69 | + |
| 70 | +If verification fails in release builds, the extras are ignored: |
| 71 | + |
| 72 | +* **Initial route (`EXTRA_INITIAL_ROUTE`):** |
| 73 | + Falls back to command-line arguments or `io.flutter.InitialRoute` metadata |
| 74 | + in `AndroidManifest.xml`. |
| 75 | + If neither is specified, it defaults to `"/"`. |
| 76 | +* **Dart entrypoint (`EXTRA_DART_ENTRYPOINT`):** |
| 77 | + Falls back to `io.flutter.Entrypoint` metadata in `AndroidManifest.xml`. |
| 78 | + If not specified, it defaults to `"main"`. |
| 79 | +* **Entrypoint arguments (`EXTRA_DART_ENTRYPOINT_ARGS`):** |
| 80 | + Ignored; returns `null`. |
| 81 | +* **Cached engine IDs (`EXTRA_CACHED_ENGINE_ID` and |
| 82 | + `EXTRA_CACHED_ENGINE_GROUP_ID`):** |
| 83 | + Ignored; returns `null`. |
| 84 | + |
| 85 | +### Behavior in debug and profile modes |
| 86 | + |
| 87 | +In debug and profile builds, |
| 88 | +the embedder bypasses verification to preserve developer tooling |
| 89 | +(such as `adb shell am start`) and automated tests. |
| 90 | +However, if an `Intent` fails verification, |
| 91 | +the embedder logs a warning with the target component, |
| 92 | +intent extras, and migration instructions. |
| 93 | + |
| 94 | +## Migration guide |
| 95 | + |
| 96 | +You do not need to migrate if: |
| 97 | + |
| 98 | +* You do not pass `route`, `dart_entrypoint`, `dart_entrypoint_args`, |
| 99 | + `cached_engine_id`, or `cached_engine_group_id` extras in `Intent`s. |
| 100 | +* Your target `FlutterActivity` or `FlutterFragmentActivity` |
| 101 | + is not exported (`android:exported="false"`). |
| 102 | + |
| 103 | +If you pass these extras to an exported activity, |
| 104 | +choose one of the following migration strategies: |
| 105 | + |
| 106 | +### Set host activities to non-exported |
| 107 | + |
| 108 | +If external apps do not need to open your activity directly, |
| 109 | +set `android:exported="false"` in `AndroidManifest.xml`: |
| 110 | + |
| 111 | +```xml title="AndroidManifest.xml" |
| 112 | +<activity |
| 113 | + android:name=".MyFlutterActivity" |
| 114 | + android:exported="false"> |
| 115 | +</activity> |
| 116 | +``` |
| 117 | + |
| 118 | +:::note |
| 119 | +Your app's main launcher activity (with `ACTION_MAIN` |
| 120 | +and `CATEGORY_LAUNCHER`) must remain exported so that the system launcher |
| 121 | +can launch your app. |
| 122 | +::: |
| 123 | + |
| 124 | +### Migrate to deep links for external routing |
| 125 | + |
| 126 | +To route to specific screens from external sources, |
| 127 | +shortcuts, or notifications, |
| 128 | +use standard [deep links][] instead of `EXTRA_INITIAL_ROUTE`: |
| 129 | + |
| 130 | +```java |
| 131 | +Intent intent = new Intent(context, MainActivity.class); |
| 132 | +intent.setAction(Intent.ACTION_VIEW); |
| 133 | +intent.setData(Uri.parse("myapp://product_details")); |
| 134 | +``` |
| 135 | + |
| 136 | +Declare matching `<intent-filter>` entries in `AndroidManifest.xml` |
| 137 | +so the embedder can validate the incoming URL. |
| 138 | + |
| 139 | +### Declare entrypoints and routes in AndroidManifest.xml |
| 140 | + |
| 141 | +For static entrypoints or initial routes, |
| 142 | +declare them as `<meta-data>` in `AndroidManifest.xml`: |
| 143 | + |
| 144 | +```xml title="AndroidManifest.xml" |
| 145 | +<activity |
| 146 | + android:name=".MyFlutterActivity" |
| 147 | + android:exported="true"> |
| 148 | + <meta-data |
| 149 | + android:name="io.flutter.Entrypoint" |
| 150 | + android:value="myCustomEntrypoint" /> |
| 151 | + <meta-data |
| 152 | + android:name="io.flutter.InitialRoute" |
| 153 | + android:value="/customRoute" /> |
| 154 | +</activity> |
| 155 | +``` |
| 156 | + |
| 157 | +### Use startActivityForResult on Android 13 and earlier |
| 158 | + |
| 159 | +For internal app launches to an exported activity on Android 13 and earlier, |
| 160 | +call `startActivityForResult()` instead of `startActivity()`: |
| 161 | + |
| 162 | +```diff |
| 163 | +- startActivity(intent); |
| 164 | ++ startActivityForResult(intent, REQUEST_CODE); |
| 165 | +``` |
| 166 | + |
| 167 | +This populates `getCallingPackage()`, allowing the embedder to verify |
| 168 | +that the `Intent` originated from your app. |
| 169 | +You do not need to handle the result in `onActivityResult()`. |
| 170 | + |
| 171 | +### Override configuration methods in an activity subclass |
| 172 | + |
| 173 | +To provide dynamic entrypoints or arguments without relying on `Intent` extras, |
| 174 | +subclass `FlutterActivity` or `FlutterFragmentActivity` |
| 175 | +and override the configuration methods: |
| 176 | + |
| 177 | +```java |
| 178 | +public class MyFlutterActivity extends FlutterActivity { |
| 179 | + @NonNull |
| 180 | + @Override |
| 181 | + public String getDartEntrypointFunctionName() { |
| 182 | + return ConfigManager.getEntrypoint(); |
| 183 | + } |
| 184 | + |
| 185 | + @Nullable |
| 186 | + @Override |
| 187 | + public List<String> getDartEntrypointArgs() { |
| 188 | + return ConfigManager.getArgs(); |
| 189 | + } |
| 190 | +} |
| 191 | +``` |
| 192 | + |
| 193 | +## Timeline |
| 194 | + |
| 195 | +Landed in version: TBD<br> |
| 196 | +In stable release: TBD |
| 197 | + |
| 198 | +## References |
| 199 | + |
| 200 | +* [Android `Intent` filters][] |
| 201 | +* [Set up Flutter Android deep links][] |
| 202 | + |
| 203 | +Relevant issues: |
| 204 | + |
| 205 | +* [Issue 190450][] |
| 206 | +* [Issue 190452][] |
| 207 | + |
| 208 | +Relevant PR: |
| 209 | + |
| 210 | +* [PR 190249][] |
| 211 | + |
| 212 | +[`Intent`]: https://developer.android.com/reference/android/content/Intent |
| 213 | +[deep links]: /cookbook/navigation/set-up-app-links |
| 214 | +[intent filters]: https://developer.android.com/guide/components/intents-filters |
| 215 | +[Android `Intent` filters]: |
| 216 | +https://developer.android.com/guide/components/intents-filters |
| 217 | +[Set up Flutter Android deep links]: /cookbook/navigation/set-up-app-links |
| 218 | +[Issue 190450]: https://github.com/flutter/flutter/issues/190450 |
| 219 | +[Issue 190452]: https://github.com/flutter/flutter/issues/190452 |
| 220 | +[PR 190249]: https://github.com/flutter/flutter/pull/190249 |
| 221 | + |
0 commit comments