v2 of the Auth0 Android SDK includes a number of improvements to integrating Auth0 into your Android application, and contains breaking changes. Please review this guide to understand the changes required when migrating to v2.
v2 requires Android API version 21 or later.
v2 only supports OIDC-Conformant applications. When using this SDK to authenticate users, only the current Auth0 authentication pipeline and endpoints will be used.
As a result, the setOIDCConformant(boolean value)
method has been removed from the Auth0
class.
You can learn more about the OpenID Connect Protocol here.
Version 2 only supports the Authorization Code with Proof Key for Code Exchange (PKCE) flow. Accordingly, the withResponseType(@ResponseType int type)
method on WebAuthProvider.Builder
has been removed.
The deprecated ability to authenticate using a WebView
component has been removed. External browser applications will always be used instead for increased security and user trust. Please refer to this blog post for additional information.
Methods and classes specific to calling any Authentication APIs categorized as Legacy have been removed in v2. The detailed listing of the removals are documented 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 the following 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>
As a result, the following interfaces have been removed:
ParameterizableRequest
AuthRequest
AuthenticationAPIClient
contains many changes to the return type of methods as a result. The full changes can be found below, but in summary:
- Any methods that returned a
ParameterizableRequest
,TokenRequest
, orDatabaseConnectionRequest
, now return aRequest
. - Any method that returned a
AuthRequest
now returns anAuthenticationRequest
.
If you are using the return type of any of these methods directly, you will need to 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}")
.
Additionally, any classes that implemented ParameterizableRequest
or AuthRequest
have been updated to accommodate these changes, and are called out in the detailed changes listed below.
v2 provides an improved ability to customize the way this library makes HTTP requests. A new interface, NetworkingClient
, defines the contract for executing HTTP requests.
The Auth0
class can be configured with an instance of NetworkingClient
, making it possible to provide your own implementation for complete control over the networking client.
Additionally, the default networking client provided by this library supports several simple 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
- The
com.auth0.android.authentication.request.ProfileRequest
class was moved tocom.auth0.android.request.ProfileRequest
- The
com.auth0.android.authentication.request.SignUpRequest
class was moved tocom.auth0.android.request.SignUpRequest
The previous version of this library used to expose a few classes in the com.auth0.android.request.internal
package. These were never meant to be part of the library's Public API, and the direct usage of them was discouraged on the Javadocs. Since the codebase had migrated to Kotlin, we now take advantage of the internal
modifier and use it were necessary. These classes might appear as public
classes for Java projects but should still not be used, as they are still not part of this library's Public API.
We will not provide support and will change these as required without any previous notice.
- The
com.auth0.android.util.Base64
class has been removed. Useandroid.util.Base64
instead. - The
com.auth0.android.request.ParameterizableRequest
interface has been removed. The ability to add request headers and parameters has been moved to thecom.auth0.android.request.Request
interface. - The
com.auth0.android.request.AuthRequest
interface has been removed. Thecom.auth0.android.request.AuthenticationRequest
interface can be used 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 /delegation 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 /delegation endpoint, disabled as of June 2017. - The
com.auth0.android.util.Telemetry
class has been renamed tocom.auth0.android.util.Auth0UserAgent
. - The
com.auth0.android.request.AuthorizableRequest
class has been removed. You can achieve the same result usingaddHeader("Authorization", "Bearer {TOKEN_VALUE}")
. - The
com.auth0.android.authentication.request.TokenRequest
class has been removed. The ability to set a Code Verifier, and any request headers and parameters has been moved to thecom.auth0.android.request.Request
interface. - The
com.auth0.android.authentication.request.DatabaseConnectionRequest
class has been removed. The ability to set any request headers and parameters has been moved to thecom.auth0.android.request.Request
interface. - The
com.auth0.android.provider.VoidCallback
class has been removed. The ability to use a callback that doesn't take an argument can be replaced withCallback<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.
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
, andResponseType.ACCESS_TOKEN
have been removed.
SignupRequest
now implementsAuthenticationRequest
instead of the now-removedAuthRequest
AuthorizableRequest
now extendsRequest
instead of the now-removedParameterizableRequest
BaseCallback
has been deprecated; useCallback
instead.
AuthenticationAPIClient
can no longer be constructed from aContext
. UseAuthenticationAPIClient(auth0: Auth0)
instead. You can create an instance ofAuth0
using aContext
.UsersAPIClient
can no longer be constructed from aContext
. UseUsersAPIClient(auth0: Auth0, token: String)
instead. You can create an instance ofAuth0
using aContext
.SignupRequest
now requires the second parameter to be anAuthenticationRequest
.ProfileRequest
now requires anAuthenticationRequest
and aRequest<UserProfile, AuthenticationException>
.Credentials
can no longer be constructed with an "expires in" value. The date of expiration or "expires at" should be given instead. You typically won't be constructing Credentials on your own.
setOIDCConformant(boolean enabled)
andisOIDCConformant()
have been removed. The SDK now only supports OIDC-Conformant applications.doNotSendTelemetry()
has been removed. There is no replacement.setWriteTimeoutInSeconds(seconds)
andgetWriteTimeoutInSeconds(seconds)
have been removed. There is no replacement.setReadTimeoutInSeconds(seconds)
andgetReadTimeoutInSeconds(seconds)
have been removed. You can customize the read timeout directly on theDefaultClient
class. UseDefaultClient(readTimeout = 123)
.setConnectTimeoutInSeconds(seconds)
andgetConnectTimeoutInSeconds(seconds)
have been removed. You can customize the connect timeout directly on theDefaultClient
class. UseDefaultClient(connectTimeout = 123)
.setLoggingEnabled(boolean enabled)
andisLoggingEnabled()
have been removed. You can enable the network traffic logger directly on theDefaultClient
class. UseDefaultClient(enableLogging = true)
. Use it for debugging purposes and never enable it on production environments.setTLS12Enforced()
andisTLS12Enforced()
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 theaddHeader("{NAME}", "{VALUE}")
method or globally to the networking client instance viaDefaultClient(defaultHeaders = mapOf())
constructor parameter.
Methods and classes specific to calling any Authentication APIs categorized as Legacy have been removed in v2. The following methods have been removed:
delegation()
,delegationWithIdToken("{ID-TOKEN}")
,delegationWithRefreshToken("{REFRESH-TOKEN}")
, anddelegationWithIdToken("{ID-TOKEN}", "{API-TYPE}}")
. Support for Legacy Authentication API endpoints have been removed.loginWithOAuthAccessToken("{TOKEN}", {CONNECTION})
. For selected social providers, you can useloginWithNativeSocialToken("{TOKEN}", "{TOKEN-TYPE}")
instead.tokenInfo("{ID-TOKEN}")
. UseuserInfo("{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. UseaddParameters(parameters)
instead.setDevice("{DEVICE}")
. UseaddParameter("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 supported in v2.start(activity: Activity, callback: AuthCallback, requestCode: Int)
has been removed. Usestart(activity: Activity, callback: Callback<Credentials, AuthenticationException>)
instead.
start(context: Context, callback: VoidCallback)
. Usestart(context: Context, callback: Callback<Void, AuthenticationException>)
instead.
init(account: Auth0)
has been removed. Uselogin(account: Auth0)
instead.init(context: Context)
has been removed. Uselogin(account: Auth0)
instead.resume(requestCode: Int, resultCode: Int, intent: Intent)
has been removed. Useresume(intent: Intent)
instead.init(account: Auth0)
has been removed. Uselogin(account: Auth0)
instead.
setDevice("{DEVICE}")
has been removed. Useset("device", "{VALUE}")
instead.
setUserAgent(String)
has been removed. You can set headers to be sent directly on each Request instance using theaddHeader("{NAME}", "{VALUE}")
method or globally to the networking client instance viaDefaultClient(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 are documented below.
- All request methods have been refactored to be decoupled from a specific HTTP request library (e.g.,
OkHttp
) - All request methods now return a
Request
. - All request methods are now lower-cased (e.g.,
POST()
->post()
). - The
authenticationPOST
method was removed without a replacement, as allRequest
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 requires 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.