Migrate Existing Sessions to DPoP

Starting in Mobile SDK 14.0, upgradeToDPoP() migrates an existing Bearer session to a DPoP-bound session in place. The method reuses the user’s existing refresh token, without a new interactive login or consent prompt.

The migration is app-initiated. Mobile SDK doesn’t run it automatically on upgrade. If your app never calls upgradeToDPoP(), users who logged in before adopting DPoP stay on Bearer tokens indefinitely.

For how DPoP works, how the server treats proofs, and how to set the client flag, see OAuth 2.0 Demonstrating Proof of Possession (DPoP).

Prerequisites

Upgrade the app to Mobile SDK 14.0 or later.
Leave the external client app or connected app in the DPoP allowed posture until migration is complete. See How the Server Treats DPoP.
Set the DPoP client flag to true before new logins that you want to receive bound tokens. See Controlling DPoP on the Client.

Call upgradeToDPoP()

To migrate the current user’s Bearer session, call upgradeToDPoP().

The migration is silent. The user sees at most a brief loading state. Mobile SDK doesn’t run this call automatically.

Important

Android

1val userAccount = UserAccountManager.getInstance().currentUser ?: return
2UserAccountManager.getInstance().upgradeToDPoP(
3    userAccount,
4    { upgradedAccount ->
5        // Success — upgradedAccount is now DPoP-bound.
6    },
7    { error, errorDescription, throwable ->
8        // Failure — the session remains on Bearer.
9    }
10)

iOS

1guard let user = SFUserAccountManager.sharedInstance().currentUser else { return }
2SFUserAccountManager.sharedInstance().upgradeToDPoP(
3    user,
4    success: { upgradedAccount in
5        // Success — the account is now DPoP-bound.
6    },
7    failure: { error in
8        // Failure — the session remains on Bearer.
9    }
10)

If upgradeToDPoP() fails, the session stays on Bearer tokens. Don’t treat that session as DPoP-bound. Don’t call upgradeToDPoP() again while other requests are using the refresh token.

Use these practices when you migrate sessions.

Trigger the migration at a natural, low-traffic moment. The app foreground event is a good choice.
Make sure that no other network calls are in flight when you call upgradeToDPoP(). The underlying refresh-token exchange needs exclusive use of the refresh token. Concurrent requests can interfere with it.
Upgrade to Mobile SDK 14.0 and start migrating well ahead of DPoP enforcement. Give the migration time to run across your installed base before enforcement so that you avoid a mass logout.

Prepare to Require DPoP

Requiring DPoP on an external client app or connected app causes the server to reject unbound (Bearer) tokens. Any user still on a Bearer session is logged out. A client that can’t present DPoP—for example, an app that isn’t yet built on Mobile SDK 14.0—can’t log back in.

Warning

Before you require DPoP, make sure that your entire user base can present bound tokens.

Confirm that every app build in the field is on Mobile SDK 14.0 or later.
Ship with the DPoP client flag set to true (the default) so that new logins are DPoP-bound.
Call upgradeToDPoP() for users who logged in before DPoP was turned on. Otherwise they stay on Bearer tokens indefinitely and are logged out when the server starts requiring DPoP.

After all three conditions are true, require DPoP on the server. Until then, leave the app in the DPoP allowed posture, where bound and Bearer tokens coexist.

Migrate Existing Sessions to DPoP

Prerequisites

Call upgradeToDPoP()

Prepare to Require DPoP

See Also