feat(android): add opt-in Trusted Web Activity and Auth Tab support by utkrishtsahu · Pull Request #961 · auth0/auth0-flutter

utkrishtsahu · 2026-10-12T05:16:07Z

All new/changed/fixed functionality is covered by tests (or N/A)
I have added documentation for all new/changed functionality (or N/A)

📋 Changes

Adds opt-in support for Trusted Web Activity (TWA) and Auth Tab on Android, using the launch mechanisms Auth0.Android already provides (withTrustedWebActivity() / withAuthTab()). Both are off by default, so existing behaviour is unchanged.

Auth Tab uses the Chrome Custom Tabs Activity Result API instead of inferring the result from the activity lifecycle, which avoids spurious user-cancelled errors when the user leaves and returns to the app. It needs Chrome 137+; older browsers fall back to a standard Custom Tab. Ephemeral sessions (useEphemeralSession) are honoured on Auth Tab.
TWA opens the Auth0 domain without browser UI and requires the app to be verified for the domain through Digital Asset Links. Ephemeral sessions are not supported by TWA.

auth0_flutter_platform_interface

CustomTabsOptions: added two fields, bool useTrustedWebActivity and bool useAuthTab, both non-nullable and defaulting to false. Both are included in toMap(). This is additive and non-breaking; no existing signatures change.

auth0_flutter (Android)

LoginWebAuthRequestHandler and LogoutWebAuthRequestHandler read the flags from the customTabsOptions map and call withTrustedWebActivity() / withAuthTab() only when the flag is true.
The flags are forwarded as-is. If both are true, Auth0.Android resolves the conflict and TWA takes precedence. This is documented on the Dart fields and in EXAMPLES.md.
Ignored on iOS, macOS, Windows and web.
Dependency: bumps com.auth0.android:auth0 from 4.0.0 to 4.1.0. 4.0.0 cannot do Auth Tab logout (it fails with a0.invalid_authorize_url; fixed upstream in 4.0.1), and 4.1.0 adds ephemeral-session support for Auth Tab. 4.1.0 contains only additive changes.

Docs

EXAMPLES.md: new "Using Trusted Web Activity or Auth Tab (Android only)" section (including an "Ephemeral sessions" note), two new rows in the CustomTabsOptions table, and a table-of-contents entry.

Usage

// Auth Tab
await auth0.webAuthentication().login(
    customTabsOptions: const CustomTabsOptions(useAuthTab: true));

// Trusted Web Activity
await auth0.webAuthentication().logout(
    customTabsOptions: const CustomTabsOptions(useTrustedWebActivity: true));

Design note: the flags live on the existing CustomTabsOptions rather than as new top-level login() / logout() parameters, which keeps Android browser configuration in one place and avoids growing the method signatures.

🎯 Testing

Automated (added in this PR)

auth0_flutter_platform_interface/test/custom_tabs_options_test.dart (3 tests): toMap() includes both flags, both default to false, and both are passed through WebAuthLoginOptions and WebAuthLogoutOptions.
auth0_flutter/test/mobile/web_authentication_test.dart (2 tests): the flags are passed through to the platform on login, and they default to false.
LoginWebAuthRequestHandlerTest.kt and LogoutWebAuthRequestHandlerTest.kt (5 tests each): TWA only, Auth Tab only, both set, both false, and customTabsOptions absent. Each case verifies exactly which builder methods are called. These run in the Run native Android unit tests CI job; I could not run them locally.

Manual, on a device

Pixel 10, Android 17, Chrome 154, Auth0.Android 4.1.0, using the example app with a custom URL scheme redirect:

Add useTrustedWebActivity and useAuthTab to CustomTabsOptions. Both are off by default and apply to web auth login and logout on Android. When both are set, Trusted Web Activity takes precedence (Auth0.Android behaviour). Co-Authored-By: Claude

coderabbitai · 2026-10-12T05:16:17Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (3)

main
beta-release/.*
release/.*

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: auth0/auth0-flutter/.coderabbit.yaml
Review profile: ASSERTIVE
Plan: Advanced
Run ID: 84233b71-5d07-4fd4-87d5-d43f9bd12f4c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

Co-Authored-By: Claude <noreply@anthropic.com>

NandanPrabhu · 2026-10-12T06:24:32Z


        buildCustomTabsOptions(args)?.let { builder.withCustomTabsOptions(it) }

+        // TWA and Auth Tab are mutually exclusive; if both are set, TWA wins


@utkrishtsahu this is handled inside auth0.android right?

Yes, Auth0.Android resolves it: if both are set, TWA wins. We just forward the flags. I've reworded the comment to say that.

NandanPrabhu · 2026-10-12T06:42:43Z

+
+Both launch mechanisms are opt-in and are enabled through `CustomTabsOptions`. They apply to `login` and `logout`, and are ignored on iOS, macOS, Windows and web.
+
+- **Auth Tab** uses the Chrome Custom Tabs Activity Result API instead of inferring the result from the activity lifecycle. This avoids spurious `isUserCancelledException` errors when Chrome is minimized. It requires Chrome 137+; older browsers fall back to a standard Custom Tab.


we can mention authtab supporting ephemeral browsing but not TWA

added an "Ephemeral sessions" note. It needs Auth0.Android 4.1.0 (older versions drop the flag for Auth Tab), so I bumped the dependency from 4.0.0 to 4.1.0. That bump also fixes Auth Tab logout, which fails on 4.0.0.

pmathew92 · 2026-10-12T06:52:58Z

+  /// spurious user-cancelled errors caused by Chrome being minimized. It
+  /// requires Chrome 137+; older browsers fall back to a standard Custom Tab.
+  /// Defaults to `false`. Ignored when [useTrustedWebActivity] is `true`.
+  final bool? useAuthTab;


Why are these two properties marked nullable. They are boolean. The default value can be false

Both are plain bool now with a default of false, and the tests expect false instead of null.

Make useTrustedWebActivity and useAuthTab non-nullable (default false), document ephemeral session behaviour for Auth Tab and TWA, and bump Auth0.Android to 4.1.0 (Auth Tab logout fix and ephemeral support). Co-Authored-By: Claude

pmathew92 · 2026-10-13T06:11:22Z

 | `backgroundInteractionEnabled` | `bool?` | Whether the user can interact with the app behind the partial tab. Defaults to `false`. |
 | `allowedBrowsers` | `List<String>` | Allowlist of browser packages for Custom Tabs. |
+| `useTrustedWebActivity` | `bool?` | Launch the browser as a [Trusted Web Activity](#using-trusted-web-activity-or-auth-tab-android-only). Defaults to `false`. |
+| `useAuthTab` | `bool?` | Launch the browser as an [Auth Tab](#using-trusted-web-activity-or-auth-tab-android-only). Defaults to `false`. |


Nit : These are non-null properties now

Co-Authored-By: Claude

4.1.0 adds an optional organization parameter to resetPassword, so the two-argument call compiles to a static default-args helper that Mockito cannot stub. Stub the three-argument method instead. Co-Authored-By: Claude

utkrishtsahu requested a review from a team as a code owner October 12, 2026 05:16

utkrishtsahu deployed to internal October 12, 2026 05:16 — with GitHub Actions Active

utkrishtsahu had a problem deploying to internal October 12, 2026 05:16 — with GitHub Actions Failure

utkrishtsahu deployed to internal October 12, 2026 05:16 — with GitHub Actions Active

utkrishtsahu had a problem deploying to internal October 12, 2026 05:16 — with GitHub Actions Error

fix(android): remove illegal character from test names

68b5110

Co-Authored-By: Claude <noreply@anthropic.com>

utkrishtsahu deployed to internal October 12, 2026 05:27 — with GitHub Actions Active

NandanPrabhu reviewed Oct 12, 2026

View reviewed changes

NandanPrabhu previously approved these changes Oct 12, 2026

View reviewed changes

NandanPrabhu reviewed Oct 12, 2026

View reviewed changes

pmathew92 reviewed Oct 12, 2026

View reviewed changes

utkrishtsahu dismissed NandanPrabhu’s stale review via fd7ba01 October 13, 2026 05:10

utkrishtsahu deployed to internal October 13, 2026 05:11 — with GitHub Actions Active

utkrishtsahu had a problem deploying to internal October 13, 2026 05:11 — with GitHub Actions Failure

utkrishtsahu deployed to internal October 13, 2026 05:11 — with GitHub Actions Active

pmathew92 reviewed Oct 13, 2026

View reviewed changes

docs: mark useTrustedWebActivity and useAuthTab as non-nullable

007e111

Co-Authored-By: Claude

utkrishtsahu deployed to internal October 13, 2026 06:14 — with GitHub Actions Active

utkrishtsahu had a problem deploying to internal October 13, 2026 06:14 — with GitHub Actions Failure

utkrishtsahu deployed to internal October 13, 2026 06:14 — with GitHub Actions Active

pmathew92 previously approved these changes Oct 13, 2026

View reviewed changes

utkrishtsahu had a problem deploying to internal October 13, 2026 06:21 — with GitHub Actions Failure

test(android): update resetPassword stubs for Auth0.Android 4.1.0

a559e99

4.1.0 adds an optional organization parameter to resetPassword, so the two-argument call compiles to a static default-args helper that Mockito cannot stub. Stub the three-argument method instead. Co-Authored-By: Claude

utkrishtsahu dismissed pmathew92’s stale review via a559e99 October 13, 2026 06:36

utkrishtsahu deployed to internal October 13, 2026 06:36 — with GitHub Actions Active

pmathew92 approved these changes Oct 13, 2026

View reviewed changes

utkrishtsahu merged commit c48d1ec into develop/v3.0 Oct 13, 2026
14 checks passed

utkrishtsahu deleted the feat/twa-auth-tab-v3 branch October 13, 2026 06:46

Navigation Menu

Repository navigation

feat(android): add opt-in Trusted Web Activity and Auth Tab support - #961

feat(android): add opt-in Trusted Web Activity and Auth Tab support#961
utkrishtsahu merged 5 commits into
develop/v3.0from
feat/twa-auth-tab-v3

utkrishtsahu commented Oct 12, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 12, 2026 •

edited

Loading

Review skipped

Uh oh!

NandanPrabhu Oct 12, 2026

Uh oh!

utkrishtsahu Oct 13, 2026

Uh oh!

NandanPrabhu Oct 12, 2026

Uh oh!

utkrishtsahu Oct 13, 2026

Uh oh!

pmathew92 Oct 12, 2026

Uh oh!

utkrishtsahu Oct 13, 2026

Uh oh!

pmathew92 Oct 13, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		buildCustomTabsOptions(args)?.let { builder.withCustomTabsOptions(it) }

		// TWA and Auth Tab are mutually exclusive; if both are set, TWA wins


		Both launch mechanisms are opt-in and are enabled through `CustomTabsOptions`. They apply to `login` and `logout`, and are ignored on iOS, macOS, Windows and web.

		- Auth Tab uses the Chrome Custom Tabs Activity Result API instead of inferring the result from the activity lifecycle. This avoids spurious `isUserCancelledException` errors when Chrome is minimized. It requires Chrome 137+; older browsers fall back to a standard Custom Tab.

Conversation

utkrishtsahu commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Changes

🎯 Testing

Uh oh!

coderabbitai Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

NandanPrabhu Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

utkrishtsahu Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

NandanPrabhu Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

utkrishtsahu Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

pmathew92 Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

utkrishtsahu Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

pmathew92 Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

utkrishtsahu commented Oct 12, 2026 •

edited

Loading

coderabbitai Bot commented Oct 12, 2026 •

edited

Loading