Review comments addressed

Author: pmathew92

EXAMPLES.md

@@ -545,14 +545,14 @@ authentication
 
 This feature allows you to authenticate a user in a web session using the refresh token obtained from the native session without requiring the user to log in again.
 
-Call the api to fetch a webSessionTransferToken in exchange for a refresh token. Use the obtained token to authenticate the user by calling the `/authorize` end point.
+Call the API to fetch a webSessionTransferToken in exchange for a refresh token. Use the obtained token to authenticate the user by calling the `/authorize` end point by passing as a query parameter or a cookie value.
 
 ```kotlin
     authentication
-    .fetchSessionTransferToken("refresh_token")
-    .start(object : Callback<SessionTransferCredentials, AuthenticationException> {
-        override fun onSuccess(result: SessionTransferCredentials) {
-            // Use the web_sso token to authenticate the user in a web session in your app
+    .ssoExchange("refresh_token")
+    .start(object : Callback<SSOCredentials, AuthenticationException> {
+        override fun onSuccess(result: SSOCredentials) {
+            // Use the sessionTransferToken token to authenticate the user in a web session in your app
         }
 
         override fun onFailure(exception: AuthenticationException) {
@@ -567,8 +567,8 @@ Call the api to fetch a webSessionTransferToken in exchange for a refresh token.
 
 ``` kotlin 
 try {
-    val sessionTransferCredentials = authentication
-        .fetchSessionTransferToken("refresh_token")
+    val ssoCredentials = authentication
+        .ssoExchange("refresh_token")
         .await()
 } catch (e: AuthenticationException) {
     e.printStacktrace()
@@ -581,10 +581,10 @@ try {
 
 ```java
 authentication
-    .fetchSessionTransferToken("refresh_token")
-    .start(new Callback<SessionTransferCredentials, AuthenticationException>() {
+    .ssoExchange("refresh_token")
+    .start(new Callback<SSOCredentials, AuthenticationException>() {
         @Override
-        public void onSuccess(@Nullable SessionTransferCredentials result) {
+        public void onSuccess(@Nullable SSOCredentials result) {
             // Handle success
         }
         @Override

auth0/src/main/java/com/auth0/android/authentication/AuthenticationAPIClient.kt

@@ -14,7 +14,7 @@ import com.auth0.android.result.Credentials
 import com.auth0.android.result.DatabaseUser
 import com.auth0.android.result.PasskeyChallenge
 import com.auth0.android.result.PasskeyRegistrationChallenge
-import com.auth0.android.result.SessionTransferCredentials
+import com.auth0.android.result.SSOCredentials
 import com.auth0.android.result.UserProfile
 import com.google.gson.Gson
 import okhttp3.HttpUrl.Companion.toHttpUrl
@@ -923,19 +923,25 @@ public class AuthenticationAPIClient @VisibleForTesting(otherwise = VisibleForTe
     }
 
     /**
-     * Creates a new request to fetch a web sso token in exchange for a refresh token.
+     * Creates a new request to exchange a refresh token for a session transfer token that can be used to perform web single sign-on.
+     *
+     * When opening your website on any browser or web view, add the session transfer token to the URL as a query
+     * parameter. Then your website can redirect the user to Auth0's `/authorize` endpoint, passing along the query
+     * parameter with the session transfer token. For example,
+     * `https://example.com/login?session_transfer_token=THE_TOKEN`.
+     *
      *
      * @param refreshToken A valid refresh token obtained as part of Auth0 authentication
-     * @return a request to fetch a web sso token
+     * @return a request to fetch a session transfer token
      *
      */
-    public fun fetchSessionTransferToken(refreshToken: String): Request<SessionTransferCredentials, AuthenticationException> {
+    public fun ssoExchange(refreshToken: String): Request<SSOCredentials, AuthenticationException> {
         val params = ParameterBuilder.newBuilder()
             .setGrantType(ParameterBuilder.REFRESH_TOKEN_KEY)
             .setAudience("urn:${auth0.domain}:session_transfer")
             .set(ParameterBuilder.REFRESH_TOKEN_KEY, refreshToken)
             .asDictionary()
-        return loginWithTokenGeneric<SessionTransferCredentials>(params)
+        return loginWithTokenGeneric<SSOCredentials>(params)
     }
 
     /**

auth0/src/main/java/com/auth0/android/authentication/ParameterBuilder.kt

@@ -160,9 +160,6 @@ public class ParameterBuilder private constructor(parameters: Map<String, String
         public const val GRANT_TYPE_TOKEN_EXCHANGE: String =
             "urn:ietf:params:oauth:grant-type:token-exchange"
         public const val GRANT_TYPE_PASSKEY :String = "urn:okta:params:oauth:grant-type:webauthn"
-        public const val TOKEN_TYPE_REFRESH_TOKEN :String = "urn:ietf:params:oauth:token-type:refresh_token"
-        public const val TOKEN_TYPE_SESSION_TRANSFER_TOKEN :String = "urn:auth0:params:oauth:token-type:session_transfer_token"
-        public const val SCOPE_OPENID: String = "openid"
         public const val SCOPE_OFFLINE_ACCESS: String = "openid offline_access"
         public const val SCOPE_KEY: String = "scope"
         public const val REFRESH_TOKEN_KEY: String = "refresh_token"

auth0/src/main/java/com/auth0/android/authentication/storage/BaseCredentialsManager.kt

@@ -4,7 +4,7 @@ import androidx.annotation.VisibleForTesting
 import com.auth0.android.authentication.AuthenticationAPIClient
 import com.auth0.android.callback.Callback
 import com.auth0.android.result.Credentials
-import com.auth0.android.result.SessionTransferCredentials
+import com.auth0.android.result.SSOCredentials
 import com.auth0.android.util.Clock
 import java.util.*
 
@@ -31,13 +31,13 @@ public abstract class BaseCredentialsManager internal constructor(
     @Throws(CredentialsManagerException::class)
     public abstract fun saveCredentials(credentials: Credentials)
     public abstract fun getCredentials(callback: Callback<Credentials, CredentialsManagerException>)
-    public abstract fun getSessionTransferCredentials(
+    public abstract fun getSsoCredentials(
         parameters: Map<String, String>,
-        callback: Callback<SessionTransferCredentials, CredentialsManagerException>
+        callback: Callback<SSOCredentials, CredentialsManagerException>
     )
 
-    public abstract fun getSessionTransferCredentials(
-        callback: Callback<SessionTransferCredentials, CredentialsManagerException>
+    public abstract fun getSsoCredentials(
+        callback: Callback<SSOCredentials, CredentialsManagerException>
     )
 
     public abstract fun getCredentials(
@@ -72,13 +72,13 @@ public abstract class BaseCredentialsManager internal constructor(
 
     @JvmSynthetic
     @Throws(CredentialsManagerException::class)
-    public abstract suspend fun awaitSessionTransferCredentials(parameters: Map<String, String>)
-            : SessionTransferCredentials
+    public abstract suspend fun awaitSsoCredentials(parameters: Map<String, String>)
+            : SSOCredentials
 
     @JvmSynthetic
     @Throws(CredentialsManagerException::class)
-    public abstract suspend fun awaitSessionTransferCredentials()
-            : SessionTransferCredentials
+    public abstract suspend fun awaitSsoCredentials()
+            : SSOCredentials
 
     @JvmSynthetic
     @Throws(CredentialsManagerException::class)

auth0/src/main/java/com/auth0/android/authentication/storage/CredentialsManager.kt

@@ -6,7 +6,7 @@ import com.auth0.android.authentication.AuthenticationAPIClient
 import com.auth0.android.authentication.AuthenticationException
 import com.auth0.android.callback.Callback
 import com.auth0.android.result.Credentials
-import com.auth0.android.result.SessionTransferCredentials
+import com.auth0.android.result.SSOCredentials
 import kotlinx.coroutines.suspendCancellableCoroutine
 import java.util.*
 import java.util.concurrent.Executor
@@ -55,22 +55,34 @@ public class CredentialsManager @VisibleForTesting(otherwise = VisibleForTesting
     }
 
     /**
-     * Fetches a new [SessionTransferCredentials] . It will fail with [CredentialsManagerException]
-     * if the existing refresh_token is null or no longer valid. This method will handle saving the refresh_token,
-     * if  a new one is issued.
+     * Creates a new request to exchange a refresh token for a session transfer token that can be used to perform web single sign-on.
+     *
+     * When opening your website on any browser or web view, add the session transfer token to the URL as a query
+     * parameter. Then your website can redirect the user to Auth0's `/authorize` endpoint, passing along the query
+     * parameter with the session transfer token. For example,
+     *  `https://example.com/login?session_transfer_token=THE_TOKEN`.
+     *
+     * It will fail with [CredentialsManagerException] if the existing refresh_token is null or no longer valid.
+     * This method will handle saving the refresh_token, if a new one is issued.
      */
-    override fun getSessionTransferCredentials(callback: Callback<SessionTransferCredentials, CredentialsManagerException>) {
-        getSessionTransferCredentials(emptyMap(), callback)
+    override fun getSsoCredentials(callback: Callback<SSOCredentials, CredentialsManagerException>) {
+        getSsoCredentials(emptyMap(), callback)
     }
 
     /**
-     * Fetches a new [SessionTransferCredentials] . It will fail with [CredentialsManagerException]
-     * if the existing refresh_token is null or no longer valid. This method will handle saving the refresh_token,
-     * if  a new one is issued.
+     * Creates a new request to exchange a refresh token for a session transfer token that can be used to perform web single sign-on.
+     *
+     * When opening your website on any browser or web view, add the session transfer token to the URL as a query
+     * parameter. Then your website can redirect the user to Auth0's `/authorize` endpoint, passing along the query
+     * parameter with the session transfer token. For example,
+     *  `https://example.com/login?session_transfer_token=THE_TOKEN`.
+     *
+     * It will fail with [CredentialsManagerException] if the existing refresh_token is null or no longer valid.
+     * This method will handle saving the refresh_token, if a new one is issued.
      */
-    override fun getSessionTransferCredentials(
+    override fun getSsoCredentials(
         parameters: Map<String, String>,
-        callback: Callback<SessionTransferCredentials, CredentialsManagerException>
+        callback: Callback<SSOCredentials, CredentialsManagerException>
     ) {
         serialExecutor.execute {
             val refreshToken = storage.retrieveString(KEY_REFRESH_TOKEN)
@@ -79,21 +91,18 @@ public class CredentialsManager @VisibleForTesting(otherwise = VisibleForTesting
                 return@execute
             }
 
-            val request = authenticationClient.fetchSessionTransferToken(refreshToken)
+            val request = authenticationClient.ssoExchange(refreshToken)
             try {
                 if (parameters.isNotEmpty()) {
                     request.addParameters(parameters)
                 }
                 val sessionTransferCredentials = request.execute()
-                saveSessionTransferCredentials(sessionTransferCredentials)
+                saveSsoCredentials(sessionTransferCredentials)
                 callback.onSuccess(sessionTransferCredentials)
             } catch (error: AuthenticationException) {
                 val exception = when {
-                    error.isRefreshTokenDeleted ||
-                            error.isInvalidRefreshToken -> CredentialsManagerException.Code.RENEW_FAILED
-
                     error.isNetworkError -> CredentialsManagerException.Code.NO_NETWORK
-                    else -> CredentialsManagerException.Code.API_ERROR
+                    else -> CredentialsManagerException.Code.SSO_EXCHANGE_FAILED
                 }
                 callback.onFailure(
                     CredentialsManagerException(
@@ -106,29 +115,41 @@ public class CredentialsManager @VisibleForTesting(otherwise = VisibleForTesting
     }
 
     /**
-     * Fetches a new [SessionTransferCredentials] . It will fail with [CredentialsManagerException]
-     * if the existing refresh_token is null or no longer valid. This method will handle saving the refresh_token,
-     * if  a new one is issued.
+     * Creates a new request to exchange a refresh token for a session transfer token that can be used to perform web single sign-on.
+     *
+     * When opening your website on any browser or web view, add the session transfer token to the URL as a query
+     * parameter. Then your website can redirect the user to Auth0's `/authorize` endpoint, passing along the query
+     * parameter with the session transfer token. For example,
+     *  `https://example.com/login?session_transfer_token=THE_TOKEN`.
+     *
+     * It will fail with [CredentialsManagerException] if the existing refresh_token is null or no longer valid.
+     * This method will handle saving the refresh_token, if a new one is issued.
      */
     @JvmSynthetic
     @Throws(CredentialsManagerException::class)
-    override suspend fun awaitSessionTransferCredentials(): SessionTransferCredentials {
-        return awaitSessionTransferCredentials(emptyMap())
+    override suspend fun awaitSsoCredentials(): SSOCredentials {
+        return awaitSsoCredentials(emptyMap())
     }
 
     /**
-     * Fetches a new [SessionTransferCredentials] . It will fail with [CredentialsManagerException]
-     * if the existing refresh_token is null or no longer valid. This method will handle saving the refresh_token,
-     * if  a new one is issued.
+     * Creates a new request to exchange a refresh token for a session transfer token that can be used to perform web single sign-on.
+     *
+     * When opening your website on any browser or web view, add the session transfer token to the URL as a query
+     * parameter. Then your website can redirect the user to Auth0's `/authorize` endpoint, passing along the query
+     * parameter with the session transfer token. For example,
+     *  `https://example.com/login?session_transfer_token=THE_TOKEN`.
+     *
+     * It will fail with [CredentialsManagerException] if the existing refresh_token is null or no longer valid.
+     * This method will handle saving the refresh_token, if a new one is issued.
      */
     @JvmSynthetic
     @Throws(CredentialsManagerException::class)
-    override suspend fun awaitSessionTransferCredentials(parameters: Map<String, String>): SessionTransferCredentials {
+    override suspend fun awaitSsoCredentials(parameters: Map<String, String>): SSOCredentials {
         return suspendCancellableCoroutine { continuation ->
-            getSessionTransferCredentials(
+            getSsoCredentials(
                 parameters,
-                object : Callback<SessionTransferCredentials, CredentialsManagerException> {
-                    override fun onSuccess(result: SessionTransferCredentials) {
+                object : Callback<SSOCredentials, CredentialsManagerException> {
+                    override fun onSuccess(result: SSOCredentials) {
                         continuation.resume(result)
                     }
 
@@ -466,21 +487,21 @@ public class CredentialsManager @VisibleForTesting(otherwise = VisibleForTesting
     }
 
     /**
-     * Helper method to store the given [SessionTransferCredentials] refresh token in the storage.
-     * Method will silently return ,if the passed credentials has no refresh token.
+     * Helper method to store the given [SSOCredentials] refresh token in the storage.
+     * Method will silently return if the passed credentials have no refresh token.
      *
-     * @param sessionTransferCredentials the credentials to save in the storage.
+     * @param ssoCredentials the credentials to save in the storage.
      */
     @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
-    internal fun saveSessionTransferCredentials(sessionTransferCredentials: SessionTransferCredentials) {
-        storage.store(KEY_ID_TOKEN, sessionTransferCredentials.idToken)
+    internal fun saveSsoCredentials(ssoCredentials: SSOCredentials) {
+        storage.store(KEY_ID_TOKEN, ssoCredentials.idToken)
         val existingRefreshToken = storage.retrieveString(KEY_REFRESH_TOKEN)
         // Checking if the existing one needs to be replaced with the new one
-        if (sessionTransferCredentials.refreshToken.isNullOrEmpty())
+        if (ssoCredentials.refreshToken.isNullOrEmpty())
             return // No refresh token to save
-        if (sessionTransferCredentials.refreshToken == existingRefreshToken)
+        if (ssoCredentials.refreshToken == existingRefreshToken)
             return // Same refresh token, no need to save
-        storage.store(KEY_REFRESH_TOKEN, sessionTransferCredentials.refreshToken)
+        storage.store(KEY_REFRESH_TOKEN, ssoCredentials.refreshToken)
     }
 
     @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)

auth0/src/main/java/com/auth0/android/authentication/storage/CredentialsManagerException.kt

@@ -44,7 +44,8 @@ public class CredentialsManagerException :
         BIOMETRICS_INVALID_USER,
         BIOMETRIC_AUTHENTICATION_FAILED,
         NO_NETWORK,
-        API_ERROR
+        API_ERROR,
+        SSO_EXCHANGE_FAILED,
     }
 
     private var code: Code?
@@ -142,6 +143,8 @@ public class CredentialsManagerException :
             CredentialsManagerException(Code.NO_NETWORK)
         public val API_ERROR: CredentialsManagerException =
             CredentialsManagerException(Code.API_ERROR)
+        public val SSO_EXCHANGE_FAILED: CredentialsManagerException =
+            CredentialsManagerException(Code.SSO_EXCHANGE_FAILED)
 
 
         private fun getMessage(code: Code): String {
@@ -187,6 +190,7 @@ public class CredentialsManagerException :
                 Code.BIOMETRIC_AUTHENTICATION_FAILED -> "Biometric authentication failed."
                 Code.NO_NETWORK -> "Failed to execute the network request."
                 Code.API_ERROR -> "An error occurred while processing the request."
+                Code.SSO_EXCHANGE_FAILED ->"The exchange of the refresh token for SSO credentials failed."
             }
         }
     }