android-components/components/service/firefox-accounts/README.md

# [Android Components](../../../README.md) > Service > Firefox Accounts (FxA)

A library for integrating with Firefox Accounts.

## Motivation

The **Firefox Accounts Android Component** provides both low and high level accounts functionality.

At a low level, there is direct interaction with the accounts system:
* Obtain scoped OAuth tokens that can be used to access the user's data in Mozilla-hosted services like Firefox Sync
* Fetch client-side scoped keys needed for end-to-end encryption of that data
* Fetch a user's profile to personalize the application

At a high level, there is an Account Manager:
* Handles account state management and persistence
* Abstracts away OAuth details, handling scopes, token caching, recovery, etc. Application can still specify custom scopes if needed
* Integrates with FxA device management, automatically creating and destroying device records as appropriate
* (optionally) Provides Send Tab integration - allows sending and receiving tabs within the Firefox Account ecosystem
* (optionally) Provides Firefox Sync integration

Sample applications:
* [accounts sample app](https://github.com/mozilla-mobile/android-components/tree/main/samples/firefox-accounts), demonstrates how to use low level APIs
* [sync app](https://github.com/mozilla-mobile/android-components/tree/main/samples/sync), demonstrates a high level accounts integration, complete with syncing multiple data stores

Useful companion components:
* [feature-accounts](https://github.com/mozilla-mobile/android-components/tree/main/components/feature/accounts), provides a `tabs` integration on top of `FxaAccountManager`, to handle display of web sign-in UI.
* [browser-storage-sync](https://github.com/mozilla-mobile/android-components/tree/main/components/browser/storage-sync), provides data storage layers compatible with Firefox Sync.

## Before using this component
Products sending telemetry and using this component *must request* a data-review following [this process](https://wiki.mozilla.org/Firefox/Data_Collection).
This component provides data collection using the [Glean SDK](https://mozilla.github.io/glean/book/index.html).
The list of metrics being collected is available in the [metrics documentation](../../support/sync-telemetry/docs/metrics.md).

## Usage
### Setting up the dependency

Use Gradle to download the library from [maven.mozilla.org](https://maven.mozilla.org/) ([Setup repository](../../../README.md#maven-repository)):

```Groovy
implementation "org.mozilla.components:service-firefox-accounts:{latest-version}"
```

### High level APIs, recommended for most applications

Below is an example of how to integrate most of the common functionality exposed by `FxaAccountManager`.
Additionally, see `feature-accounts`

```kotlin
// Make the two "syncable" stores accessible to account manager's sync machinery.
GlobalSyncableStoreProvider.configureStore(SyncEngine.History to historyStorage)
GlobalSyncableStoreProvider.configureStore(SyncEngine.Bookmarks to bookmarksStorage)

val accountManager = FxaAccountManager(
    context = this,
    serverConfig = ServerConfig.release(CLIENT_ID, REDIRECT_URL),
    deviceConfig = DeviceConfig(
        name = "Sample app",
        type = DeviceType.MOBILE,
        capabilities = setOf(DeviceCapability.SEND_TAB)
    ),
    syncConfig = SyncConfig(setOf(SyncEngine.History, SyncEngine.Bookmarks), syncPeriodInMinutes = 15L)
)

// Observe changes to the account and profile.
accountManager.register(accountObserver, owner = this, autoPause = true)

// Observe sync state changes.
accountManager.registerForSyncEvents(syncObserver, owner = this, autoPause = true)

// Observe incoming account events (e.g. when another device connects or
// disconnects to/from the account, SEND_TAB commands from other devices, etc).
// Note that since the device is configured with a SEND_TAB capability, device constellation will be
// automatically updated during any account initialization flow (restore, login, sign-up, recovery).
// It is up to the application to keep it up-to-date beyond that.
// See `account.deviceConstellation().refreshDeviceStateAsync()`.
accountManager.registerForAccountEvents(accountEventsObserver, owner = this, autoPause = true)

// Now that all of the observers we care about are registered, kick off the account manager.
// If we're already authenticated
launch { accountManager.initAsync().await() }

// 'Sync Now' button binding.
findViewById<View>(R.id.buttonSync).setOnClickListener {
    accountManager.syncNowAsync(SyncReason.User)
}

// 'Sign-in' button binding.
findViewById<View>(R.id.buttonSignIn).setOnClickListener {
    launch {
        val authUrl = accountManager.beginAuthenticationAsync().await()
        authUrl?.let { openWebView(it) }
    }
}

// 'Sign-out' button binding
findViewById<View>(R.id.buttonLogout).setOnClickListener {
    launch {
        accountManager.logoutAsync().await()
    }
}

// 'Disable periodic sync' button binding
findViewById<View>(R.id.disablePeriodicSync).setOnClickListener {
    launch {
        accountManager.setSyncConfigAsync(
            SyncConfig(setOf(SyncReason.History, SyncReason.Bookmarks)
        ).await()
    }
}

// 'Enable periodic sync' button binding
findViewById<View>(R.id.enablePeriodicSync).setOnClickListener {
    launch {
        accountManager.setSyncConfigAsync(
            SyncConfig(setOf(SyncReason.History, SyncReason.Bookmarks), syncPeriodInMinutes = 60L)
        ).await()
    }
}

// Globally disabled syncing an engine - this affects all Firefox Sync clients.
findViewById<View>(R.id.globallyDisableHistoryEngine).setOnClickListener {
    SyncEnginesStorage.setStatus(SyncEngine.History, false)
    accountManager.syncNowAsync(SyncReason.EngineChange)
}

// Get current status of SyncEngines. Note that this may change after every sync, as other Firefox Sync clients can change it.
val engineStatusMap = SyncEnginesStorage.getStatus() // type is: Map<SyncEngine, Boolean>

// This is expected to be called from the webview/geckoview integration, which intercepts page loads and gets
// 'code' and 'state' out of the 'successful sign-in redirect' url.
fun onLoginComplete(code: String, state: String) {
    launch {
        accountManager.finishAuthenticationAsync(code, state).await()
    }
}

// Observe changes to account state.
val accountObserver = object : AccountObserver {
    override fun onLoggedOut() = launch {
        // handle logging-out in the UI
    }

    override fun onAuthenticationProblems() = launch {
        // prompt user to re-authenticate
    }

    override fun onAuthenticated(account: OAuthAccount) = launch {
        // logged-in successfully; display account details
    }

    override fun onProfileUpdated(profile: Profile) {
        // display ${profile.displayName} and ${profile.email} if desired
    }
}

// Observe changes to sync state.
val syncObserver = object : SyncStatusObserver {
    override fun onStarted() = launch {
        // sync started running; update some UI to indicate this
    }

    override fun onIdle() = launch {
        // sync stopped running; update some UI to indicate this
    }

    override fun onError(error: Exception?) = launch {
        // sync encountered an error; optionally indicate this in the UI
    }
}

// Observe incoming account events.
val accountEventsObserver = object : AccountEventsObserver {
    override fun onEvents(event: List<AccountEvent>) {
        // device received some commands; for example, here's how you can process incoming Send Tab commands:
        commands
            .filter { it is AccountEvent.CommandReceived }
            .map { it.command }
            .filter { it is DeviceCommandIncoming.TabReceived }
            .forEach {
                val tabReceivedCommand = it as DeviceCommandIncoming.TabReceived
                val fromDeviceName = tabReceivedCommand.from?.displayName
                showNotification("Tab ${tab.title}, received from: ${fromDisplayName}", tab.url)
            }
            // (although note the SendTabFeature makes dealing with these commands
            // easier still.)
    }
}
```

### Low level APIs

First you need some OAuth information. Generate a `client_id`, `redirectUrl` and find out the scopes for your application.
See the [Firefox Account documentation](https://mozilla.github.io/application-services/docs/accounts/welcome.html)
for that.

Once you have the OAuth info, you can start adding `FxAClient` to your Android project.
As part of the OAuth flow your application will be opening up a WebView or a Custom Tab.
Currently the SDK does not provide the WebView, you have to write it yourself.

Create a global `account` object:

```kotlin
var account: FirefoxAccount? = null
```

You will need to save state for FxA in your app, this example just uses `SharedPreferences`. We suggest using the [Android Keystore]( https://developer.android.com/training/articles/keystore) for this data.
Define variables to help save state for FxA:

```kotlin
val STATE_PREFS_KEY = "fxaAppState"
val STATE_KEY = "fxaState"
```

Then you can write the following:

```kotlin

account = getAuthenticatedAccount()
if (account == null) {
  // Start authentication flow
  val config = Config(CONFIG_URL, CLIENT_ID, REDIRECT_URL)
  // Some helpers such as Config.release(CLIENT_ID, REDIRECT_URL)
  // are also provided for well-known Firefox Accounts servers.
  account = FirefoxAccount(config)
}

fun getAuthenticatedAccount(): FirefoxAccount? {
    val savedJSON = getSharedPreferences(FXA_STATE_PREFS_KEY, Context.MODE_PRIVATE).getString(FXA_STATE_KEY, "")
    return savedJSON?.let {
        try {
            FirefoxAccount.fromJSONString(it)
        } catch (e: FxaException) {
            null
        }
    } ?: null
}
```

The code above checks if you have some existing state for FxA, otherwise it configures it. All asynchronous methods on `FirefoxAccount` are executed on `Dispatchers.IO`'s dedicated thread pool. They return `Deferred` which is Kotlin's non-blocking cancellable Future type.

Once the configuration is available and an account instance was created, the authentication flow can be started:

```kotlin
launch {
    val url = account.beginOAuthFlow(scopes).await()
    openWebView(url)
}
```

When spawning the WebView, be sure to override the `OnPageStarted` function to intercept the redirect url and fetch the code + state parameters:

```kotlin
override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
    if (url != null && url.startsWith(redirectUrl)) {
        val uri = Uri.parse(url)
        val mCode = uri.getQueryParameter("code")
        val mState = uri.getQueryParameter("state")
        if (mCode != null && mState != null) {
            // Pass the code and state parameters back to your main activity
            listener?.onLoginComplete(mCode, mState, this@LoginFragment)
        }
    }

    super.onPageStarted(view, url, favicon)
}
```

Finally, complete the OAuth flow, retrieve the profile information, then save your login state once you've gotten valid profile information:

```kotlin
launch {
    // Complete authentication flow
    account.completeOAuthFlow(code, state).await()

    // Display profile information
    val profile = account.getProfile().await()
    txtView.txt = profile.displayName

    // Persist login state
    val json = account.toJSONString()
    getSharedPreferences(FXA_STATE_PREFS_KEY, Context.MODE_PRIVATE).edit()
        .putString(FXA_STATE_KEY, json).apply()
}
```

## Automatic sign-in via trusted on-device FxA Auth providers

If there are trusted FxA auth providers available on the device, and they're signed-in, it's possible
to automatically sign-in into the same account, gaining access to the same data they have access to (e.g. Firefox Sync).

Currently supported FxA auth providers are:
- Firefox for Android (release, beta and nightly channels)

`AccountSharing` provides facilities to securely query auth providers for available accounts. It may be used
directly in concert with a low-level `FirefoxAccount.migrateFromSessionTokenAsync`, or via the high-level `FxaAccountManager`:

```kotlin
val availableAccounts = accountManager.shareableAccounts(context)
// Display a list of accounts to the user, identified by account.email and account.sourcePackage
// Or, pick the first available account. They're sorted in an order of internal preference (release, beta, nightly).
val selectedAccount = availableAccounts[0]
launch {
    val result = accountManager.signInWithShareableAccountAsync(selectedAccount).await()
    if (result) {
        // Successfully signed-into an account.
        // accountManager.authenticatedAccount() is the new account.
    } else {
        // Failed to sign-into an account, either due to bad credentials or networking issues.
    }
}
```

## License

    This Source Code Form is subject to the terms of the Mozilla Public
    License, v. 2.0. If a copy of the MPL was not distributed with this
    file, You can obtain one at http://mozilla.org/MPL/2.0/