RemoteAuthClient

class RemoteAuthClient : AutoCloseable

Provides a client for supporting remote authentication on Wear. The authentication session will be opened on the user's paired phone.

  • The following example triggers an authorization session to open on the phone.

// PKCE (Proof Key for Code Exchange) is required for the auth
private var codeVerifier: CodeVerifier
// Late initialization in place where it's used, or to be initialized in onCreate()
private var lateinit authClient: RemoteAuthClient

override public fun onDestroy() {
  authClient.close();
  super.onDestroy();
}

public fun startAuthFlow() {
   // PKCE (Proof Key for Code Exchange) is required, store this code verifier here .
   // To access the resource later, both the auth token and code verifier are needed.
   codeVerifier = CodeVerifier()

  // Construct your auth request.
  authClient = RemoteAuthClient.create(this);
  authClient.sendAuthorizationRequest(
     OAuthRequest.Builder(this.applicationContext)
         .setAuthProviderUrl(Uri.parse("https://...."))
         .setCodeChallenge(CodeChallenge(codeVerifier))
         .build(),
     Executors.newSingleThreadExecutor(),
     new MyAuthCallback()
  );
}

private  class MyAuthCallback: RemoteAuthClient.Callback {
  override public fun onAuthorizationResponse(
     request: OAuthRequest,
     response: OAuthResponse
   ) {
    // Parse the result token out of the response and store it, e.g. in SharedPreferences,
    // so you can use it later (Note, use together with code verifier from version R)
    // You'll also want to display a success UI.
    ...
  }

  override fun onAuthorizationError(request: OAuthRequest, errorCode: Int) {
    // Compare against codes available in RemoteAuthClient.ErrorCode
    // You'll also want to display an error UI.
    ...
  }
}

Summary

Nested types

This callback is notified when an async remote authentication request completes.

Constants
const Int

Indicates no phone is connected, or the phone connected doesn't support 3p auth
const Int

Indicates 3p authentication isn't supported by Wear OS
const Int

Indicates 3p authentication is finished without error
const Int

Indicates that remote auth is available with a connected device capable to handle the remote interaction.
const Int

Indicates that remote auth is temporarily unavailable.
const Int

Indicates that remote auth is unavailable because there is no paired device capable of handling the remote interaction.
const Int

The remote auth's availability is unknown.

Public companion functions
RemoteAuthClient
create(context: Context)

Return a client that can be used to make async remote authorization requests

Public functions
open Unit

Frees any resources used by the client, dropping any outstanding requests.
Unit
@UiThread
sendAuthorizationRequest(
    request: OAuthRequest,
    executor: Executor,
    clientCallback: RemoteAuthClient.Callback
)

Send a remote auth request.

Protected functions
Unit

Check that the explicit termination method 'close' is called

Public properties
Flow<Int>

Returns status indicating whether remote auth operation (such as sendAuthorizationRequest) is available.

Constants

ERROR_PHONE_UNAVAILABLE

const val ERROR_PHONE_UNAVAILABLE = 1: Int

Indicates no phone is connected, or the phone connected doesn't support 3p auth

ERROR_UNSUPPORTED

const val ERROR_UNSUPPORTED = 0: Int

Indicates 3p authentication isn't supported by Wear OS

NO_ERROR

const val NO_ERROR: Int

Indicates 3p authentication is finished without error

STATUS_AVAILABLE

const val STATUS_AVAILABLE = 3: Int

Indicates that remote auth is available with a connected device capable to handle the remote interaction.

STATUS_TEMPORARILY_UNAVAILABLE

const val STATUS_TEMPORARILY_UNAVAILABLE = 2: Int

Indicates that remote auth is temporarily unavailable.

There is a known paired device, but it is not currently connected or reachable to handle the remote interaction.

STATUS_UNAVAILABLE

const val STATUS_UNAVAILABLE = 1: Int

Indicates that remote auth is unavailable because there is no paired device capable of handling the remote interaction.

STATUS_UNKNOWN

const val STATUS_UNKNOWN = 0: Int

The remote auth's availability is unknown.

On older devices, STATUS_UNKNOWN is returned as we can not determine the availability states. To preserve compatibility with existing devices behavior, try sendAuthorizationRequest and handle error codes accordingly.

Public companion functions

create

Added in 1.0.0
fun create(context: Context): RemoteAuthClient

Return a client that can be used to make async remote authorization requests

Public functions

close

Added in 1.0.0
@UiThread
open fun close(): Unit

Frees any resources used by the client, dropping any outstanding requests. The client cannot be used to make requests thereafter.

sendAuthorizationRequest

Added in 1.0.0
@UiThread
fun sendAuthorizationRequest(
    request: OAuthRequest,
    executor: Executor,
    clientCallback: RemoteAuthClient.Callback
): Unit

Send a remote auth request. This will cause an authorization UI to be presented on the user's phone. This request is asynchronous; the callback provided will be be notified when the request completes.

Parameters
request: OAuthRequest

Request that will be sent to the phone. The auth response should redirect to the Wear OS companion. See OAuthRequest.WEAR_REDIRECT_URL_PREFIX
executor: Executor

The executor that callback will called on.
clientCallback: RemoteAuthClient.Callback

The callback that will be notified when request is completed.
Throws
kotlin.RuntimeException

if the service has error to open the request

Protected functions

finalize

Added in 1.0.0
protected fun finalize(): Unit

Check that the explicit termination method 'close' is called

Throws
kotlin.RuntimeException

if the 'close' method was not called

Public properties

availabilityStatus

Added in 1.1.0-alpha05
val availabilityStatus: Flow<Int>

Returns status indicating whether remote auth operation (such as sendAuthorizationRequest) is available.

In scenarios of restricted connection or temporary disconnection with a paired device, remote auth operations will not be available. Please check status before sendAuthorizationRequest to provide better experience for the user.

On older wear devices which do not support availability status, it will always return STATUS_UNKNOWN. Wear devices start to support determining the availability status from Wear Sdk WEAR_TIRAMISU_4.

import androidx.wear.phone.interactions.authentication.RemoteAuthClient

remoteAuthClient.availabilityStatus.collect {
    status -> when (status) {
        RemoteAuthClient.STATUS_UNAVAILABLE ->
            TODO("Present alternative flow as remote auth is not available")
        RemoteAuthClient.STATUS_TEMPORARILY_UNAVAILABLE ->
            TODO("Present education to user to connect devices or bring to proximity.")
        RemoteAuthClient.STATUS_AVAILABLE, RemoteAuthClient.STATUS_UNKNOWN ->
            // Present normal auth flow when we don't know (old devices)
            // or when we know it is available.
            remoteAuthClient.sendAuthorizationRequest(
                oAuthRequest,
                Runnable::run,
                myAuthCallback)
    } }
Returns
Flow<Int>

a Flow with a stream of status updates that could be one of STATUS_UNKNOWN, STATUS_UNAVAILABLE, STATUS_TEMPORARILY_UNAVAILABLE, STATUS_AVAILABLE.