Tutorial: OAuth2

Android OAuth2

Webcom SDK for Android makes it very simple to authenticate users with a third-party OAuth2-compliant identity provider, such as Google, Facebook (for public applications) or Orange Connect (for corporate applications). In addition, the provided implementation follows up-to-date security recommendations for mobile native apps, which you consequently haven't to care about explicitly:

  • The interaction with the end user relies on the default browser of the device through Custom Tabs: it provides a convenient way to share the user's sessions stored on her·his browser, while staying completely hermetic wrt. your Android app,
  • The call-flow between the Android device and the Webcom back end is based on Proof Key for Code Exchange: it prevents CSRF and authorization code injection attacks
  • The OAuth2 call-flow orchestrated by the Webcom back end uses the Authorization Code grant: it avoids storing any credentials or secret on the Android device.

Configure your OAuth2 provider

The first step consists in provisioning your OAuth2 provider settings (essentially “client-id” and “client-secret”) within the Webcom developer console (see the “OAuth2.0 login” chapter for complete details).

You will also have to register the application id of your Android app within the authorized domains cartridge.

Invoke the OAuth2 API

The single entry point of the Webcom SDK for Android is the OAuth2Method.authenticate. The OAuth2Method instance can be retrieved by passing the required OAuth2 third-party provider to the AuthenticationService.getOAuth2Method method:

val myApp = WebcomApplication.default
val authenticator = myApp.authenticationService
// assume 'this' refers to the Android Activity from which the authentication screen is launched
authenticator.getOAuth2Method(Provider.Google, this).authenticate { // it: WebcomResult<AuthenticationDetails>
    if (it is WebcomResult.Success) {
        runOnUiThread { // we are not on the main thread and cannot update UI directly from the callback function
            binding.userNameTextView.text = it.result.displayName // optional, but provided by most OAuth2 providers
            binding.userUidTextView.text = it.result.uid // stable unique identifier for the user generated by Webcom
        }
    }
}

Keep in mind that the callback function passed to the authenticate method will be run asynchronously on a dedicated thread! Hence, UI widgets must be invoked through runOnUiThread from within the callback function.

Customize the look & feel

The getOAuth2Method() method accepts an options parameter that makes it possible to customize the actual Custom Tab used to make the user interact with the authorize-endpoint of the targeted OAuth2 provider. Actually, you can set up a callback function, which is called with the CustomTabsIntent.Builder that opens the authorize page. For example:

val myApp = WebcomApplication.default
val authenticator = myApp.authenticationService
val options = OAuth2Method.Options().withCustomTabsBuilder { // it: CustomTabsIntent.Builder
  val defaultColorBuilder = CustomTabColorSchemeParams.Builder()
  defaultColorBuilder.setToolbarColor(ContextCompat.getColor(this,android.R.color.holo_red_dark))
  it.setDefaultColorSchemeParams(defaultColorBuilder.build())
}
authenticator.getOAuth2Method(Provider.Google, this, options).authenticate { // it: WebcomResult<AuthenticationDetails>
    // ...
}

Referring to a CustomTabsIntent.Builder instance normally requires to import the androidx.browser:browser dependency within the module. As the com.orange.webcom:sdk-android library already imports it, it is not necessary to add it explicitly to your build.gradle file.

The complete Webcom authentication features are described in the “Serverless Authentication” chapter.

↑ ↑