Auth0 Android v2 Migration Guide

Version 2 of the Auth0 Android SDK includes many improvements for integrating Auth0 into your Android application. This upgrade contains breaking changes. Please review this guide to understand the changes required when migrating to v2.

v2 requires Android API version 21 or later and Java 8+.

Here’s what you need in build.gradle to target Java 8 byte code for Android and Kotlin plugins respectively:

android {
  compileOptions {
      sourceCompatibility JavaVersion.VERSION_1_8
      targetCompatibility JavaVersion.VERSION_1_8
  }

  kotlinOptions {
      jvmTarget = '1.8'
  }
}

v2 only supports OIDC-Conformant applications. When using this SDK to authenticate users, only the current Auth0 authentication pipeline and endpoints will be used. We removed the setOIDCConformant(boolean value) method from the Auth0 class.

Learn more about the OpenID Connect Protocol.

v2 only supports the Authorization Code with Proof Key for Code Exchange (PKCE) flow. We removed the withResponseType(@ResponseType int type) method on WebAuthProvider.Builder.

We removed the deprecated ability to authenticate using a WebView component. External browser applications will always be used instead for increased security and user trust.

We removed methods and classes specific to calling any authentication APIs categorized as Legacy. See the complete list in the Classes and interfaces removed section below.

The com.auth0.android.request package defines the top-level interfaces for building and executing HTTP requests. Historically, a common issue has been the inability to add custom headers and request parameters to all request types. We've refactored the request interfaces to enable any request to be customized with additional headers and request parameters. Note that these parameters now need to be of type String.

The top-level Request interface now specifies these methods:

• public fun addParameters(parameters: Map<String, String>): Request<T, U>

• public fun addParameter(name: String, value: String): Request<T, U>

• public fun addHeader(name: String, value: String): Request<T, U>

We removed these interfaces:

• ParameterizableRequest

• AuthRequest

AuthenticationAPIClient contains many changes to the return type of methods as a result. These are some examples:

• Any methods that returned ParameterizableRequest, TokenRequest, or DatabaseConnectionRequest, now return a Request

• Any method that returned AuthRequest now returns AuthenticationRequest

If you are using the return type of any of these methods directly, you must change your code to expect the type as documented above. If you are chaining a call to start or execute to make the request, no changes are required.

The AuthenticationRequest interface no longer has a setAccessToken("{ACCESS-TOKEN}") method. This method was for setting the token to the request made to the /oauth/access_token Authentication API legacy endpoint, disabled as of June 2017. If you need to send a parameter with this name, please use addParameter("access_token", "{ACCESS-TOKEN}").

Any classes that implemented ParameterizableRequest or AuthRequest have been updated to accommodate these changes.

See the complete list in the Classes and interfaces removed section below.

v2 improves the ability to customize the way this library makes HTTP requests. A new interface, NetworkingClient, defines the contract for executing HTTP requests. You can configure Auth0 class with an instance of NetworkingClient. This lets you provide your own implementation for complete control over the networking client. Additionally, the default networking client provided by this library supports several sample customization points to enable easy configuration of common customization points.

// Before
val account = Auth0("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")

account.connectTimeoutInSeconds = 30
account.readTimeoutInSeconds = 30

val authAPI = AuthenticationAPIClient(account)

// After
val netClient = DefaultClient(
    connectTimeout = 30,
    readTimeout = 30
)

val account = Auth0("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
account.networkingClient = netClient

// Before
val account = Auth0("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
account.isLoggingEnabled = true

val authAPI = AuthenticationAPIClent(account)

// After
val netClient = DefaultClient(
    enableLogging = true
)

val account = Auth0("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
account.networkingClient = netClient

• We moved the com.auth0.android.authentication.request.ProfileRequest class to com.auth0.android.request.ProfileRequest.

• We moved the com.auth0.android.authentication.request.SignUpRequest class to com.auth0.android.request.SignUpRequest.

The previous version of this library exposed a few classes in the com.auth0.android.request.internal package. These were never meant to be part of the library's Public API; Java documentation discouraged their direct use. Since the codebase had migrated to Kotlin, we now take advantage of the internal modifier and use it where necessary. These classes might appear as public classes for Java projects, but do not use them. They are still not part of this library's Public API.

We will not provide support for these classes. We will change these as required without notice.

• The com.auth0.android.util.Base64 class has been removed. Use android.util.Base64 instead.

• The com.auth0.android.request.ParameterizableRequest interface has been removed. We moved the ability to add request headers and parameters to the com.auth0.android.request.Request interface.

• The com.auth0.android.request.AuthRequest interface has been removed. Use the com.auth0.android.request.AuthenticationRequest interface instead.

• The com.auth0.android.provider.WebAuthActivity class has been removed. External browser applications will always be used for authentication.

• The com.auth0.android.result.Delegation class has been removed. This was used as the result of the request to the Authentication API legacy endpoint, disabled as of June 2017.

• The com.auth0.android.authentication.request.DelegationRequest class has been removed. This was used to represent the request to the legacy Authentication API endpoint, disabled as of June 2017.

• The com.auth0.android.util.Telemetry class has been renamed to com.auth0.android.util.Auth0UserAgent.

• The com.auth0.android.request.AuthorizableRequest class has been removed. You can achieve the same result using addHeader("Authorization", "Bearer {TOKEN_VALUE}").

• The com.auth0.android.authentication.request.TokenRequest class has been removed. We moved the ability to set a Code Verifier and any request headers and parameters to the com.auth0.android.request.Request interface.

• The com.auth0.android.authentication.request.DatabaseConnectionRequest class has been removed. We moved the ability to set any request headers and parameters to the com.auth0.android.request.Request interface.

• The com.auth0.android.provider.VoidCallback class has been removed. We replaced the ability to use a callback that doesn't take an argument with Callback<Void, AuthenticationException>.

• The com.auth0.android.request.ErrorBuilder interface has been removed.

• The com.auth0.android.RequestBodyBuildException class has been removed.

• The com.auth0.android.util.CheckHelper class has been removed.

• The com.auth0.android.util.JsonRequired interface has been removed.

• The com.auth0.android.util.JsonRequiredTypeAdapterFactory class has been removed.

• ParameterBuilder.GRANT_TYPE_JWT has been removed.

• ParameterBuilder.ID_TOKEN_KEY has been removed.

• ParameterBuilder.DEVICE_KEY has been removed.

• ParameterBuilder.ACCESS_TOKEN_KEY has been removed.

• ResponseType.CODE, ResponseType.ID_TOKEN, and ResponseType.ACCESS_TOKEN have been removed.

• SignupRequest now implements AuthenticationRequest instead of the now-removed AuthRequest

• AuthorizableRequest now extends Request instead of the now-removed ParameterizableRequest

• BaseCallback has been deprecated; use Callback instead.

• You can no longer construct AuthenticationAPIClient from a Context. Use AuthenticationAPIClient(auth0: Auth0)instead. You can create an instance of Auth0 using a Context.

• You can no longer construct UsersAPIClient from a Context. Use UsersAPIClient(auth0: Auth0, token: String) instead. You can create an instance of Auth0 using a Context.

• SignupRequest now requires the second parameter to be an AuthenticationRequest.

• ProfileRequest now requires an AuthenticationRequest and a Request<UserProfile, AuthenticationException>.

• You can no longer construct Credentials with an "expires in" value. Give the date of expiration or "expires at" instead. You typically won't construct Credentials on your own.

• setOIDCConformant(boolean enabled) and isOIDCConformant() have been removed. The SDK now only supports OIDC-Conformant applications.

• doNotSendTelemetry() has been removed. There is no replacement.

• setWriteTimeoutInSeconds(seconds) and getWriteTimeoutInSeconds(seconds) have been removed. There is no replacement.

• setReadTimeoutInSeconds(seconds) and getReadTimeoutInSeconds(seconds) have been removed. You can customize the read timeout directly on the DefaultClient class. Use DefaultClient(readTimeout = 123).

• setConnectTimeoutInSeconds(seconds) and getConnectTimeoutInSeconds(seconds)have been removed. You can customize the connect timeout directly on the DefaultClient class. Use DefaultClient(connectTimeout = 123).

• setLoggingEnabled(boolean enabled) and isLoggingEnabled() have been removed. You can enable the network traffic logger directly on the DefaultClient class. Use DefaultClient(enableLogging = true). Use it for debugging purposes and never enable it on production environments.

• setTLS12Enforced() and isTLS12Enforced() have been removed. The SDK now supports modern TLS by default.

• setUserAgent(String) has been removed. You can set headers to be sent directly on each Request instance using the addHeader("{NAME}", "{VALUE}") method or globally to the networking client instance via DefaultClient(defaultHeaders = mapOf()) constructor parameter.

Methods and classes specific to calling any Authentication APIs categorized as Legacy have been removed in v2. We removed these methods:

• delegation(), delegationWithIdToken("{ID-TOKEN}"), delegationWithRefreshToken("{REFRESH-TOKEN}"), and delegationWithIdToken("{ID-TOKEN}", "{API-TYPE}}"). Support for Legacy Authentication API endpoints have been removed.

• loginWithOAuthAccessToken("{TOKEN}", {CONNECTION}). For selected social providers, you can use loginWithNativeSocialToken("{TOKEN}", "{TOKEN-TYPE}") instead.

• tokenInfo("{ID-TOKEN}"). Use userInfo("{ACCESS-TOKEN}") instead.

Methods that returned a ParameterizableRequest now return a Request:

• userInfo("{ACCESS-TOKEN}")

• revokeToken("{REFRESH-TOKEN}")

• renewAuth("{REFRESH-TOKEN}")

• passwordlessWithEmail("{EMAIL}", PasswordlessType, "{CONNECTION}")

• passwordlessWithSMS("{PHONE-NUNBER}", PasswordlessType, "{CONNECTION}")

• fetchJsonWebKeys()

Methods that returned an AuthRequest now return an AuthenticationRequest:

• login("{USERNAME-OR-EMAIL}", "{PASSWORD}", "{REALM-OR-CONNECTION}")

• login("{USERNAME-OR-EMAIL}", "{PASSWORD}")

• loginWithOTP("{MFA-TOKEN}", "{OTP}")

• loginWithNativeSocialToken("{TOKEN}", "{TOKEN-TYPE}")

• loginWithPhoneNumber("{PHONE-NUMBER}", "{VERIFICATION-CODE}", "{REALM-OR-CONNECTION}")

• loginWithEmail("{EMAIL}", "{VERIFICATION-CODE}", "{REALM-OR-CONNECTION}")

Methods that returned a DatabaseConnectionRequest now return a Request:

• createUser("{EMAIL}", "{PASSWORD}", "{USERNAME}", "{CONNECTION}")

• resetPassword("{EMAIL}","{CONNECTION}")

Methods that returned a TokenRequest now return a Request:

• token("{AUTHORIZATION-CODE}", "{CODE-VERIFIER}", "{REDIRECT-URI}")

• addAuthenticationParameters(parameters) has been removed. Use addParameters(parameters) instead.

• setDevice("{DEVICE}"). Use addParameter("device", "{VALUE}") instead.

• useCodeGrant(boolean useCodeGrant). There is no replacement; only Code + PKCE flow supported in v2.

• useBrowser(boolean useBrowser). There is no replacement; this library no longer supports WebView authentication.

• useFullscreen(boolean useFullscreen). There is no replacement; this library no longer supports WebView authentication.

• withResponseType(@ResponseType int type). There is no replacement; only Code + PKCE flow are supported in v2.

• start(activity: Activity, callback: AuthCallback, requestCode: Int) has been removed. Use start(activity: Activity, callback: Callback<Credentials, AuthenticationException>) instead.

• start(context: Context, callback: VoidCallback). Use start(context: Context, callback: Callback<Void, AuthenticationException>) instead.

• init(account: Auth0) has been removed. Use login(account: Auth0) instead.

• init(context: Context) has been removed. Use login(account: Auth0) instead.

• resume(requestCode: Int, resultCode: Int, intent: Intent) has been removed. Use resume(intent: Intent) instead.

• init(account: Auth0) has been removed. Use login(account: Auth0) instead.

• setDevice("{DEVICE}") has been removed. Use set("device", "{VALUE}") instead.

• setUserAgent(String) has been removed. You can set headers to be sent directly on each Request instance using the addHeader("{NAME}", "{VALUE}") method or globally to the networking client instance via DefaultClient(defaultHeaders = mapOf()) constructor parameter.

Methods that returned a ParameterizableRequest now return a Request:

• link("{PRIMARY-USER-ID}", "{SECONDARY-TOKEN}")

• unlink("{PRIMARY-USER-ID}", "{SECONDARY-USER-ID}", "{SECONDARY-PROVIDER}")

• updateMetadata("{USER-ID}", userMetadata)

• getProfile("{USER-ID}")

The RequestFactory class contains methods to facilitate making HTTP requests, including the serialization and deserialization of the JSON request body and response. As part of the com.auth0.android.request.internal package, it is not intended for public use, but as a public type, the summary of changes is described below.

• All request methods have been refactored to be decoupled from a specific HTTP request library (for example, OkHttp)

• All request methods now return a Request.

• All request methods are now lowercase (for example, POST() -> post()).

• The authenticationPOST method was removed without a replacement, as all Request instances can be parameterized with any headers as needed.

• The addParameters method now requires the value to be Map of String to String, instead of String to Object (addParameters(mapOf("key" to "val")))

Methods that set parameters now require the value to be a Map of String to String, instead of String to Object:

• addAuthenticationParameters(mapOf("key" to "val"))

• addSignupParameters(mapOf("key" to "val"))

• addParameters(mapOf("key" to "val"))

Additionally, setDevice("device") was removed. Use addParameter("device", "{VALUE}") instead.