RemoteAuthClient

public final class RemoteAuthClient implements 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
public abstract class RemoteAuthClient.Callback

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

Constants
static final int

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

Indicates 3p authentication isn't supported by Wear OS
static final int

Indicates 3p authentication is finished without error
static final int

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

Indicates that remote auth is temporarily unavailable.
static final int

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

The remote auth's availability is unknown.

Public methods
void

Frees any resources used by the client, dropping any outstanding requests.
static final @NonNull RemoteAuthClient

Return a client that can be used to make async remote authorization requests
final @NonNull Flow<@NonNull Integer>

Returns status indicating whether remote auth operation (such as sendAuthorizationRequest) is available.
final void
@UiThread
sendAuthorizationRequest(
    @NonNull OAuthRequest request,
    @NonNull Executor executor,
    @NonNull RemoteAuthClient.Callback clientCallback
)

Send a remote auth request.

Protected methods
final void

Check that the explicit termination method 'close' is called

Constants

ERROR_PHONE_UNAVAILABLE

public static final int ERROR_PHONE_UNAVAILABLE = 1

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

ERROR_UNSUPPORTED

public static final int ERROR_UNSUPPORTED = 0

Indicates 3p authentication isn't supported by Wear OS

NO_ERROR

public static final int NO_ERROR

Indicates 3p authentication is finished without error

STATUS_AVAILABLE

public static final int STATUS_AVAILABLE = 3

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

STATUS_TEMPORARILY_UNAVAILABLE

public static final int STATUS_TEMPORARILY_UNAVAILABLE = 2

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

public static final int STATUS_UNAVAILABLE = 1

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

STATUS_UNKNOWN

public static final int STATUS_UNKNOWN = 0

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 methods

close

Added in 1.0.0
@UiThread
public void close()

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

create

Added in 1.0.0
public static final @NonNull RemoteAuthClient create(@NonNull Context context)

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

getAvailabilityStatus

Added in 1.1.0-alpha05
public final @NonNull Flow<@NonNull Integer> getAvailabilityStatus()

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
@NonNull Flow<@NonNull Integer>

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

sendAuthorizationRequest

Added in 1.0.0
@UiThread
public final void sendAuthorizationRequest(
    @NonNull OAuthRequest request,
    @NonNull Executor executor,
    @NonNull RemoteAuthClient.Callback clientCallback
)

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
@NonNull OAuthRequest request

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

The executor that callback will called on.
@NonNull RemoteAuthClient.Callback clientCallback

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

if the service has error to open the request

Protected methods

finalize

Added in 1.0.0
protected final void finalize()

Check that the explicit termination method 'close' is called

Throws
kotlin.RuntimeException

if the 'close' method was not called