fix: handle config changes in WebAuth flow with unified attach() API

utkrishtsahu · utkrishtsahu · commit 61e92fe6a7c8 · 2026-04-02T09:27:21.000+05:30
diff --git a/V4_MIGRATION_GUIDE.md b/V4_MIGRATION_GUIDE.md
@@ -308,19 +308,25 @@ the reference to the callback is immediately nulled out so the destroyed Activit
 in memory.
 
 If the authentication result arrives while the Activity is being recreated, it is cached internally.
-Use `consumePendingLoginResult()` or `consumePendingLogoutResult()` in your `onResume()` to recover it:
+Use `WebAuthProvider.attach()` in your `onResume()` to recover it — this single call handles both
+recovery scenarios and manages the callback lifecycle automatically:
 
 ```kotlin
 class LoginActivity : AppCompatActivity() {
-    private val callback = object : Callback<Credentials, AuthenticationException> {
-        override fun onSuccess(result: Credentials) { /* handle credentials */ }
-        override fun onFailure(error: AuthenticationException) { /* handle error */ }
-    }
 
     override fun onResume() {
         super.onResume()
-        // Recover result that arrived during configuration change
-        WebAuthProvider.consumePendingLoginResult(callback)
+        WebAuthProvider.attach(
+            lifecycleOwner = this,
+            loginCallback = object : Callback<Credentials, AuthenticationException> {
+                override fun onSuccess(result: Credentials) { /* handle credentials */ }
+                override fun onFailure(error: AuthenticationException) { /* handle error */ }
+            },
+            logoutCallback = object : Callback<Void?, AuthenticationException> {
+                override fun onSuccess(result: Void?) { /* handle logout */ }
+                override fun onFailure(error: AuthenticationException) { /* handle error */ }
+            }
+        )
     }
 
     fun onLoginClick() {
@@ -331,10 +337,17 @@ class LoginActivity : AppCompatActivity() {
 }
 ```
 
-For logout flows, use `WebAuthProvider.consumePendingLogoutResult(callback)` in the same way.
+`attach()` covers both scenarios in one call:
+
+| Scenario | How it's handled |
+|----------|-----------------|
+| **Configuration change** (rotation, locale, dark mode) | Any result cached while the Activity was recreating is delivered immediately to the callback |
+| **Process death** (system killed the app while browser was open) | `loginCallback` is registered as a listener and auto-removed when `lifecycleOwner` is destroyed — no manual `addCallback`/`removeCallback` calls needed |
+
+> **Note:** `logoutCallback` is optional — pass it only if your screen initiates logout flows.
 
 > **Note:** If you use the `suspend fun await()` API from a ViewModel coroutine scope, the
-> Activity is never captured in the callback chain, so you do not need `consumePending*` calls.
+> Activity is never captured in the callback chain, so you do not need `attach()` calls.
 > See the sample app for a ViewModel-based example.
 
 ## Getting Help
diff --git a/auth0/src/main/java/com/auth0/android/provider/LifecycleAwareCallback.kt b/auth0/src/main/java/com/auth0/android/provider/LifecycleAwareCallback.kt
@@ -7,19 +7,19 @@ import com.auth0.android.callback.Callback
 
 /**
  * Wraps a user-provided callback and observes the Activity/Fragment lifecycle.
- * When the host is destroyed (e.g. config change), [inner] is set to null so
+ * When the host is destroyed (e.g. config change), [delegateCallback] is set to null so
  * the destroyed Activity is no longer referenced by the SDK.
  *
- * If a result arrives after [inner] has been cleared, the [onDetached] lambda
- * is invoked to cache the result for later recovery via consumePending*Result().
+ * If a result arrives after [delegateCallback] has been cleared, the [onDetached] lambda
+ * is invoked to cache the result for later recovery via resumePending*Result().
  *
  * @param S the success type (Credentials for login, Void? for logout)
- * @param inner the user's original callback
+ * @param delegateCallback the user's original callback
  * @param lifecycleOwner the Activity or Fragment whose lifecycle to observe
  * @param onDetached called when a result arrives but the callback is already detached
  */
 internal class LifecycleAwareCallback<S>(
-    @Volatile private var inner: Callback<S, AuthenticationException>?,
+    private var delegateCallback: Callback<S, AuthenticationException>?,
     lifecycleOwner: LifecycleOwner,
     private val onDetached: (success: S?, error: AuthenticationException?) -> Unit,
 ) : Callback<S, AuthenticationException>, DefaultLifecycleObserver {
@@ -29,7 +29,7 @@ internal class LifecycleAwareCallback<S>(
     }
 
     override fun onSuccess(result: S) {
-        val cb = inner
+        val cb = delegateCallback
         if (cb != null) {
             cb.onSuccess(result)
         } else {
@@ -38,7 +38,7 @@ internal class LifecycleAwareCallback<S>(
     }
 
     override fun onFailure(error: AuthenticationException) {
-        val cb = inner
+        val cb = delegateCallback
         if (cb != null) {
             cb.onFailure(error)
         } else {
@@ -47,7 +47,7 @@ internal class LifecycleAwareCallback<S>(
     }
 
     override fun onDestroy(owner: LifecycleOwner) {
-        inner = null
+        delegateCallback = null
         owner.lifecycle.removeObserver(this)
     }
 }
diff --git a/auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt b/auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt
@@ -5,7 +5,7 @@ import android.content.Intent
 import android.net.Uri
 import android.os.Bundle
 import android.util.Log
-import androidx.annotation.VisibleForTesting
+import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
 import com.auth0.android.Auth0
 import com.auth0.android.annotation.ExperimentalAuth0Api
@@ -34,10 +34,9 @@ public object WebAuthProvider {
     private val TAG: String? = WebAuthProvider::class.simpleName
     private const val KEY_BUNDLE_OAUTH_MANAGER_STATE = "oauth_manager_state"
 
-    private val callbacks = CopyOnWriteArraySet<Callback<Credentials, AuthenticationException>>()
+    internal val callbacks = CopyOnWriteArraySet<Callback<Credentials, AuthenticationException>>()
 
     @JvmStatic
-    @get:VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
     internal var managerInstance: ResumableManager? = null
         private set
 
@@ -46,62 +45,86 @@ public object WebAuthProvider {
      * the original callback was no longer reachable (e.g. Activity destroyed
      * during a configuration change).
      */
-    internal sealed class PendingResult<out S, out E> {
-        data class Success<S>(val result: S) : PendingResult<S, Nothing>()
-        data class Failure<E>(val error: E) : PendingResult<Nothing, E>()
+    internal sealed class PendingResult<out S> {
+        data class Success<S>(val result: S) : PendingResult<S>()
+        data class Failure(val error: AuthenticationException) : PendingResult<Nothing>()
     }
 
-    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
-    internal val pendingLoginResult =
-        AtomicReference<PendingResult<Credentials, AuthenticationException>?>(null)
+    internal val pendingLoginResult = AtomicReference<PendingResult<Credentials>?>(null)
 
-    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
-    internal val pendingLogoutResult =
-        AtomicReference<PendingResult<Void?, AuthenticationException>?>(null)
+    internal val pendingLogoutResult = AtomicReference<PendingResult<Void?>?>(null)
 
     /**
-     * Check for and consume a pending login result that arrived during a configuration change.
-     * Call this in your Activity's `onResume()` to recover results that were delivered while the
-     * Activity was being recreated (e.g. due to screen rotation).
+     * Attaches login (and optionally logout) callbacks for the duration of the given
+     * [lifecycleOwner]'s lifetime. Call this once in `onResume()` — it covers both recovery
+     * scenarios automatically:
      *
-     * @param callback the callback to deliver the pending result to
-     * @return true if a pending result was found and delivered, false otherwise
-     */
-    @JvmStatic
-    public fun consumePendingLoginResult(callback: Callback<Credentials, AuthenticationException>): Boolean {
-        val result = pendingLoginResult.getAndSet(null) ?: return false
-        when (result) {
-            is PendingResult.Success -> callback.onSuccess(result.result)
-            is PendingResult.Failure -> callback.onFailure(result.error)
-        }
-        resetManagerInstance()
-        return true
-    }
-
-    /**
-     * Check for and consume a pending logout result that arrived during a configuration change.
-     * Call this in your Activity's `onResume()` to recover results that were delivered while the
-     * Activity was being recreated (e.g. due to screen rotation).
+     * - **Configuration change** (rotation, locale, dark mode): if a login or logout result
+     *   arrived while the Activity was being recreated, it is delivered immediately.
+     * - **Process death**: [loginCallback] is registered as a listener so that if the process
+     *   was killed while the browser was open, the result is delivered when the Activity is
+     *   restored. The callback is automatically unregistered when [lifecycleOwner] is destroyed,
+     *   so there is no need to call [removeCallback] manually.
+     *
+     * ```kotlin
+     * override fun onResume() {
+     *     super.onResume()
+     *     WebAuthProvider.attach(this, loginCallback = callback, logoutCallback = voidCallback)
+     * }
+     * ```
      *
-     * @param callback the callback to deliver the pending result to
-     * @return true if a pending result was found and delivered, false otherwise
+     * @param lifecycleOwner the Activity or Fragment whose lifecycle to observe
+     * @param loginCallback  receives login results (both direct delivery and recovered results)
+     * @param logoutCallback receives logout results recovered after a configuration change
      */
     @JvmStatic
-    public fun consumePendingLogoutResult(callback: Callback<Void?, AuthenticationException>): Boolean {
-        val result = pendingLogoutResult.getAndSet(null) ?: return false
-        when (result) {
-            is PendingResult.Success -> callback.onSuccess(result.result)
-            is PendingResult.Failure -> callback.onFailure(result.error)
-        }
-        resetManagerInstance()
-        return true
+    public fun attach(
+        lifecycleOwner: LifecycleOwner,
+        loginCallback: Callback<Credentials, AuthenticationException>,
+        logoutCallback: Callback<Void?, AuthenticationException>? = null,
+    ) {
+        // Process-death recovery: register and auto-remove on destroy
+        callbacks += loginCallback
+        lifecycleOwner.lifecycle.addObserver(object : DefaultLifecycleObserver {
+            override fun onDestroy(owner: LifecycleOwner) {
+                callbacks -= loginCallback
+                owner.lifecycle.removeObserver(this)
+            }
+        })
+
+        // Config-change recovery: deliver any result cached while Activity was recreating
+        pendingLoginResult.getAndSet(null)?.let { pending ->
+            when (pending) {
+                is PendingResult.Success -> loginCallback.onSuccess(pending.result)
+                is PendingResult.Failure -> loginCallback.onFailure(pending.error)
+            }
+            resetManagerInstance()
+        }
+
+        logoutCallback?.let { cb ->
+            pendingLogoutResult.getAndSet(null)?.let { pending ->
+                when (pending) {
+                    is PendingResult.Success -> cb.onSuccess(pending.result)
+                    is PendingResult.Failure -> cb.onFailure(pending.error)
+                }
+                resetManagerInstance()
+            }
+        }
     }
 
+    @Deprecated(
+        message = "Use attach() instead — it registers the callback and auto-removes it when the lifecycle owner is destroyed.",
+        replaceWith = ReplaceWith("attach(lifecycleOwner, loginCallback = callback)")
+    )
     @JvmStatic
     public fun addCallback(callback: Callback<Credentials, AuthenticationException>) {
         callbacks += callback
     }
 
+    @Deprecated(
+        message = "Use attach() instead — it auto-removes the callback when the lifecycle owner is destroyed.",
+        replaceWith = ReplaceWith("attach(lifecycleOwner, loginCallback = callback)")
+    )
     @JvmStatic
     public fun removeCallback(callback: Callback<Credentials, AuthenticationException>) {
         callbacks -= callback
@@ -198,7 +221,6 @@ public object WebAuthProvider {
     }
 
     @JvmStatic
-    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
     internal fun resetManagerInstance() {
         managerInstance = null
     }
@@ -304,7 +326,7 @@ public object WebAuthProvider {
 
             val effectiveCallback = if (context is LifecycleOwner) {
                 LifecycleAwareCallback<Void?>(
-                    inner = callback,
+                    delegateCallback = callback,
                     lifecycleOwner = context as LifecycleOwner,
                     onDetached = { _: Void?, error: AuthenticationException? ->
                         if (error != null) {
@@ -638,7 +660,6 @@ public object WebAuthProvider {
             return this
         }
 
-        @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
         internal fun withPKCE(pkce: PKCE): Builder {
             this.pkce = pkce
             return this
@@ -675,7 +696,7 @@ public object WebAuthProvider {
             pendingLoginResult.set(null)
             val effectiveCallback = if (context is LifecycleOwner) {
                 LifecycleAwareCallback<Credentials>(
-                    inner = callback,
+                    delegateCallback = callback,
                     lifecycleOwner = context as LifecycleOwner,
                     onDetached = { success: Credentials?, error: AuthenticationException? ->
                         if (success != null) {
diff --git a/auth0/src/test/java/com/auth0/android/provider/WebAuthProviderTest.kt b/auth0/src/test/java/com/auth0/android/provider/WebAuthProviderTest.kt
