Add token migration feature and AuthFlowTester UI to exercise it.

Author: brandonpage

libs/SalesforceSDK/AndroidManifest.xml

@@ -45,6 +45,12 @@
             android:configChanges="orientation|screenLayout|uiMode|screenSize|smallestScreenSize"
             android:exported="true" />
 
+        <!-- Token Migration Activity -->
+        <activity android:name="com.salesforce.androidsdk.ui.TokenMigrationActivity"
+            android:excludeFromRecents="true"
+            android:theme="@style/AccountSwitcher"
+            android:exported="false" />
+
         <!-- Screen Lock Activity-->
         <activity android:name="com.salesforce.androidsdk.ui.ScreenLockActivity"
             android:exported="false"

libs/SalesforceSDK/build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
     `publish-module`
     jacoco
     kotlin("plugin.serialization") version "2.0.21"
+    kotlin("plugin.parcelize")
 }
 
 dependencies {

libs/SalesforceSDK/src/com/salesforce/androidsdk/accounts/UserAccountManagerExtension.kt

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2026-present, salesforce.com, inc.
+ * All rights reserved.
+ * Redistribution and use of this software in source and binary forms, with or
+ * without modification, are permitted provided that the following conditions
+ * are met:
+ * - Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ * - Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ * - Neither the name of salesforce.com, inc. nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission of salesforce.com, inc.
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.salesforce.androidsdk.accounts
+
+import android.content.Intent
+import com.salesforce.androidsdk.app.SalesforceSDKManager
+import com.salesforce.androidsdk.config.OAuthConfig
+import com.salesforce.androidsdk.ui.TokenMigrationActivity
+import com.salesforce.androidsdk.util.SalesforceSDKLogger
+import java.util.UUID
+
+const val TAG = "UserAccountManager"
+
+/**
+ * Attempts to migrate the [userAccount] to the provided Connected App or
+ * External Client Application [appConfig].
+ *
+ * This might cause the approve/deny screen to be presented to the user to authorize the
+ * new app. If successful a new set of credentials (refresh token, access token) are obtained
+ * and replace the existing credentials for the user.
+ */
+fun UserAccountManager.migrateRefreshToken(
+    userAccount: UserAccount? = UserAccountManager.getInstance().currentUser,
+    appConfig: OAuthConfig,
+    onMigrationSuccess: (userAccount: UserAccount) -> Unit,
+    onMigrationError: (error: String, errorDesc: String?, e: Throwable?) -> Unit,
+) {
+    val loggedOnSuccess: (userAccount: UserAccount) -> Unit = { user ->
+        SalesforceSDKLogger.i(TAG, "User ($user) successfully migrated to " +
+                "new OAuthConfig ($appConfig).")
+        onMigrationSuccess.invoke(user)
+    }
+    val loggedOnError: (error: String, errorDesc: String?, e: Throwable?) -> Unit = { error, errorDesc, e ->
+        val message = error + errorDesc?.let { "\nDescription: $it" }
+        SalesforceSDKLogger.e(TAG, message, e)
+        onMigrationError.invoke(error, errorDesc, e)
+    }
+
+    val userId = userAccount?.userId ?: run {
+        loggedOnError("User account or userId is null.", null, null)
+        return
+    }
+    val orgId = userAccount.orgId ?: run {
+        loggedOnError("OrgId is null.", null, null)
+        return
+    }
+
+    val callbackKey = MigrationCallbackRegistry.register(
+        callbacks = MigrationCallbackRegistry.MigrationCallbacks(
+            onMigrationSuccess = loggedOnSuccess,
+            onMigrationError = loggedOnError,
+        )
+    )
+
+    val context = SalesforceSDKManager.getInstance().appContext
+    val intent = Intent(context, TokenMigrationActivity::class.java)
+    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+    intent.putExtra(TokenMigrationActivity.EXTRA_ORG_ID, orgId)
+    intent.putExtra(TokenMigrationActivity.EXTRA_USER_ID, userId)
+    intent.putExtra(TokenMigrationActivity.EXTRA_OAUTH_CONFIG, appConfig)
+    intent.putExtra(TokenMigrationActivity.EXTRA_CALLBACK_ID, callbackKey)
+    context.startActivity(intent)
+}
+
+/*
+    This mechanism is used to pass a _string_ id to the Activity to retrieve callback functions.
+
+    Lambda functions may appear Parcelable/Serializable but since we cannot guarantee the
+    content are they should not be passed.  For instance, if the lambda function contains
+    compose state an exception will be thrown.
+ */
+internal object MigrationCallbackRegistry {
+    private val callbacks = mutableMapOf<String, MigrationCallbacks>()
+
+    data class MigrationCallbacks(
+        val onMigrationSuccess: (UserAccount) -> Unit,
+        val onMigrationError: (String, String?, Throwable?) -> Unit
+    )
+
+    fun register(callbacks: MigrationCallbacks): String {
+        val key = UUID.randomUUID().toString()
+        this.callbacks[key] = callbacks
+        return key
+    }
+
+    fun consume(key: String): MigrationCallbacks? = callbacks.remove(key)
+}

libs/SalesforceSDK/src/com/salesforce/androidsdk/auth/AuthenticationUtilities.kt

@@ -98,6 +98,7 @@ internal suspend fun onAuthFlowComplete(
     onAuthFlowSuccess: (userAccount: UserAccount) -> Unit,
     buildAccountName: (username: String?, instanceServer: String?) -> String = ::defaultBuildAccountName,
     nativeLogin: Boolean = false,
+    tokenMigration: Boolean = false,
     context: Context = SalesforceSDKManager.getInstance().appContext,
     userAccountManager: UserAccountManager = SalesforceSDKManager.getInstance().userAccountManager,
     blockIntegrationUser: Boolean = (SalesforceSDKManager.getInstance().shouldBlockSalesforceIntegrationUser &&
@@ -189,9 +190,11 @@ internal suspend fun onAuthFlowComplete(
     }
     userAccountManager.sendUserSwitchIntent(userSwitchType, null)
 
-    // Kickoff the end of the flow before storing mobile policy to prevent launching
-    // the main activity over/after the screen lock.
-    startMainActivity()
+    if (!tokenMigration) {
+        // Kickoff the end of the flow before storing mobile policy to prevent launching
+        // the main activity over/after the screen lock.
+        startMainActivity()
+    }
 
     // Let the calling process resume
     onAuthFlowSuccess(account)
@@ -375,14 +378,21 @@ private fun handleScreenLockPolicy(
     userIdentity: OAuth2.IdServiceResponse?,
     account: UserAccount
 ) {
+    val internalScreenLockManager =
+        SalesforceSDKManager.getInstance().screenLockManager as ScreenLockManager?
+
+    // compareTo(0) is used to check if screenLockTimeout is non-null and greater than 0.
     if (userIdentity?.screenLockTimeout?.compareTo(0) == 1) {
         SalesforceSDKManager.getInstance().registerUsedAppFeature(FEATURE_SCREEN_LOCK)
         val timeoutInMills = userIdentity.screenLockTimeout * 1000 * 60
-        (SalesforceSDKManager.getInstance().screenLockManager as ScreenLockManager?)?.storeMobilePolicy(
+        internalScreenLockManager?.storeMobilePolicy(
             account,
-            userIdentity.screenLock,
-            timeoutInMills
+            enabled = userIdentity.screenLock,
+            timeoutInMills,
         )
+    } else if (internalScreenLockManager?.enabled == true) {
+        SalesforceSDKManager.getInstance().unregisterUsedAppFeature(FEATURE_SCREEN_LOCK)
+        internalScreenLockManager.cleanUp(account)
     }
 }
 
@@ -393,14 +403,20 @@ private fun handleBiometricAuthPolicy(
     userIdentity: OAuth2.IdServiceResponse?,
     account: UserAccount
 ) {
+    val internalBiometricAuthenticationManager =
+        SalesforceSDKManager.getInstance().biometricAuthenticationManager as BiometricAuthenticationManager?
+
     if (userIdentity?.biometricAuth == true) {
         SalesforceSDKManager.getInstance().registerUsedAppFeature(FEATURE_BIOMETRIC_AUTH)
         val timeoutInMills = userIdentity.biometricAuthTimeout * 60 * 1000
-        (SalesforceSDKManager.getInstance().biometricAuthenticationManager as BiometricAuthenticationManager?)?.storeMobilePolicy(
+        internalBiometricAuthenticationManager?.storeMobilePolicy(
             account,
-            userIdentity.biometricAuth,
+            enabled = userIdentity.biometricAuth,
             timeoutInMills
         )
+    } else if (internalBiometricAuthenticationManager?.enabled == true) {
+        SalesforceSDKManager.getInstance().unregisterUsedAppFeature(FEATURE_BIOMETRIC_AUTH)
+        internalBiometricAuthenticationManager.cleanUp(account)
     }
 }
 
@@ -438,6 +454,12 @@ private fun handleDuplicateUserAccount(
             clearCaches()
             userAccountManager.clearCachedCurrentUser()
 
+            // Remove the existing Account from AccountManager so createAccount can create a fresh one
+            val existingAccount = userAccountManager.buildAccount(duplicateUserAccount)
+            if (existingAccount != null) {
+                SalesforceSDKManager.getInstance().clientManager.removeAccount(existingAccount)
+            }
+
             // Revoke existing refresh token
             if (account.refreshToken != duplicateUserAccount.refreshToken) {
                 runCatching {

libs/SalesforceSDK/src/com/salesforce/androidsdk/auth/OAuth2.java

@@ -133,6 +133,7 @@ public class OAuth2 {
     private static final String QUESTION = "?";
     private static final String TOUCH = "touch";
     private static final String FRONTDOOR = "/secur/frontdoor.jsp?";
+    public static final String FRONTDOOR_URL_KEY = "frontdoor_uri";
     private static final String SID = "sid";
     private static final String RETURL = "retURL";
     protected static final String AUTHORIZATION = "Authorization";

libs/SalesforceSDK/src/com/salesforce/androidsdk/auth/idp/IDPAuthCodeHelper.kt

@@ -33,6 +33,7 @@ import android.webkit.WebViewClient
 import com.salesforce.androidsdk.R
 import com.salesforce.androidsdk.accounts.UserAccount
 import com.salesforce.androidsdk.app.SalesforceSDKManager
+import com.salesforce.androidsdk.auth.OAuth2.FRONTDOOR_URL_KEY
 import com.salesforce.androidsdk.auth.OAuth2.getAuthorizationUrl
 import com.salesforce.androidsdk.rest.ClientManager
 import com.salesforce.androidsdk.rest.RestClient
@@ -132,7 +133,7 @@ internal class IDPAuthCodeHelper private constructor(
             SalesforceSDKLogger.e(TAG, "Failed to obtain valid front door url", e)
             null
         }
-        return if (restResponse == null || !restResponse.isSuccess) null else restResponse.asJSONObject().getString("frontdoor_uri")
+        return if (restResponse == null || !restResponse.isSuccess) null else restResponse.asJSONObject().getString(FRONTDOOR_URL_KEY)
     }
 
     private fun onError(error: String, exception: java.lang.Exception? = null) {

libs/SalesforceSDK/src/com/salesforce/androidsdk/config/OAuthConfig.kt

@@ -26,11 +26,15 @@
  */
 package com.salesforce.androidsdk.config
 
+import android.os.Parcelable
+import kotlinx.parcelize.Parcelize
+
+@Parcelize
 data class OAuthConfig(
     val consumerKey: String,
     val redirectUri: String,
     val scopes: List<String>? = null,
-) {
+): Parcelable {
 
     internal constructor(bootConfig: BootConfig): this(
         bootConfig.remoteAccessConsumerKey,

libs/SalesforceSDK/src/com/salesforce/androidsdk/ui/LoginActivity.kt

@@ -239,6 +239,7 @@ open class LoginActivity : FragmentActivity() {
             newUserIntent = true
         }
 
+        // TODO: Move to non-deprecated getParcelableExtra when min API >= 33
         accountAuthenticatorResponse = intent.getParcelableExtra<AccountAuthenticatorResponse?>(
             KEY_ACCOUNT_AUTHENTICATOR_RESPONSE
         )?.apply {
@@ -1217,18 +1218,6 @@ open class LoginActivity : FragmentActivity() {
             d(TAG, "Received client certificate request from server")
             request.proceed(key, certChain)
         }
-
-        private fun validateAndExtractBackgroundColor(javaScriptResult: String): Color? {
-            val rgbMatch = rgbTextPattern.find(javaScriptResult)
-
-            // groupValues[0] is the entire match.  [1] is red, [2] is green, [3] is green.
-            rgbMatch?.groupValues?.get(3) ?: return null
-            val red = rgbMatch.groupValues[1].toIntOrNull() ?: return null
-            val green = rgbMatch.groupValues[2].toIntOrNull() ?: return null
-            val blue = rgbMatch.groupValues[3].toIntOrNull() ?: return null
-
-            return Color(red, green, blue)
-        }
     }
 
     companion object {
@@ -1245,15 +1234,27 @@ open class LoginActivity : FragmentActivity() {
         private const val RESPONSE_ERROR_DESCRIPTION_INTENT = "com.salesforce.auth.intent.RESPONSE_ERROR_DESCRIPTION"
 
         // This parses the expected "rgb(x, x, x)" string.
-        private val rgbTextPattern = "rgb\\((\\d{1,3}), (\\d{1,3}), (\\d{1,3})\\)".toRegex()
+        internal val rgbTextPattern = "rgb\\((\\d{1,3}), (\\d{1,3}), (\\d{1,3})\\)".toRegex()
 
         // endregion
         // region LoginWebviewClient Constants
 
         internal const val ABOUT_BLANK = "about:blank"
-        private const val BACKGROUND_COLOR_JAVASCRIPT =
+        internal const val BACKGROUND_COLOR_JAVASCRIPT =
             "(function() { return window.getComputedStyle(document.body, null).getPropertyValue('background-color'); })();"
 
+        internal fun validateAndExtractBackgroundColor(javaScriptResult: String): Color? {
+            val rgbMatch = rgbTextPattern.find(javaScriptResult)
+
+            // groupValues[0] is the entire match.  [1] is red, [2] is green, [3] is green.
+            rgbMatch?.groupValues?.get(3) ?: return null
+            val red = rgbMatch.groupValues[1].toIntOrNull() ?: return null
+            val green = rgbMatch.groupValues[2].toIntOrNull() ?: return null
+            val blue = rgbMatch.groupValues[3].toIntOrNull() ?: return null
+
+            return Color(red, green, blue)
+        }
+
         // endregion
         // region Log In Via Salesforce Identity API UI Bridge Front Door URL Public Implementation