The core public API surfaces for interacting with Google identity. Header files
in this directory are allowed to depend only on the following other parts of the
signin component:

//components/signin/public/base
//components/signin/public/webdata

Implementation files in this directory, however, are additionally allowed to
depend on //components/signin/internal/identity_manager.

Here we take a quick guide through the core concepts (note: Documentation on
specific IdentityManager and IdentityManager::Observer methods can be found as
method-level comments in identity_manager.h; this guide defines the core
concepts themselves and gives a high-level mapping between these core concepts
and the relevant IdentityManager(::Observer) API surfaces).

# Accounts
- "Account" always refers to a Gaia account.
- An account has three core pieces of information, which are collected together
  in the CoreAccountInfo struct and are available for the duration of the
  account being visible to IdentityManager:
  - The email address.
  - The Gaia ID.
  - The account ID. This is an opaque Chrome-specific identifier for the
    account.
- The AccountInfo struct contains extra "extended" information about the account
  that may become available only asynchronously after the account is first added
  to Chrome. To interact with the extended account info, use the IdentityManager
  methods with "ExtendedAccountInfo" in their names. To observe changes in the
  state of the extended account info for one or more accounts, observe
  IdentityManager and override one or more of the IdentityManager::Observer
  methods with "ExtendedAccountInfo" in their names.

# The Primary Account
- "Primary account" in IdentityManager refers to the account that has been
  blessed for sync by the user (what in Chromium historically was often referred
  to as the "authenticated account").
- "Unconsented primary account" is intuitively the browsing identity of the user
  that we display to the user; the user may or may not have blessed this account
  for sync. In particular, whenever a primary account exists, the unconsented
  primary account equals to the primary account. On desktop platforms (excl.
  ChromeOS), if no primary account exists and there exist any content-area
  accounts, the unconsented primary account equals to the first signed-in content-
  area account. In all other cases there is no unconsented primary account.
  NOTE: This name is still subject to finalization. The problem with
  "unconsented" in this context is that it means "did not consent"; really, this
  account is the "possibly unconsented, possibly primary, default account", which
  is a mouthful :).
- To interact with the primary account and/or unconsented primary account, use
  the IdentityManager methods with "PrimaryAccount" in their names. To observe
  changes in the presence of either of these accounts, observe IdentityManager
  and override one or more of the methods with "PrimaryAccount" in their names
  as desired.
- PrimaryAccountTokenFetcher is the primary client-side interface for obtaining
  OAuth2 access tokens for the primary account (see the next section for the
  discussion of OAuth2 tokens). In particular, it can handle the common use case
  of "wait until the primary account is available and then fetch an access token
  for it" transparently on behalf of the client. See
  primary_account_access_token_fetcher.h for usage explanation and examples.

# OAuth2 Access and Refresh Tokens
- "OAuth2 tokens" are tokens related to the OAuth2 client-server authorization
  protocol. "OAuth2 refresh tokens" or just "refresh tokens" are long-lived
  tokens that the browser obtains via the user explicitly adding an account.
  Clients of IdentityManager do not explicitly see refresh tokens, but rather use
  IdentityManager to obtain "OAuth2 access tokens" or just "access tokens".
  Access tokens are short-lived tokens with given scopes that can be used to make
  authorized requests to Gaia endpoints.
- "The accounts with refresh tokens" refer to the accounts that are visible to
  IdentityManager with OAuth2 refresh tokens present (e.g., because the user has
    signed in to the browser and embedder-level code then added the account to
    IdentityManager, or because the user has added an account at the
    system level that embedder-level code then made visible to IdentityManager).
  To interact with these accounts, use the IdentityManager methods with
  "RefreshToken" in their name. To observe changes in the state of one or more
  of these accounts, observe IdentityManager and override one or more of the
  IdentityManager::Observer methods with "RefreshToken" in their name.
- AccessTokenFetcher is the client-side interface for obtaining access tokens
  for arbitrary accounts; see access_token_fetcher.h for usage explanation and
  examples.

# The Gaia Cookie
- "The Gaia cookie" refers to the cookie that contains the information of the
  user's Gaia accounts that are available on the web.
- "The accounts in the Gaia cookie" and "the accounts in the cookie jar" refer to
  the set of accounts in this cookie. To interact with these accounts, use the
  IdentityManager methods with "Cookie" in their name. To observe changes in the
  state of one or more of these accounts, observe IdentityManager and override
  one or more of the IdentityManager::Observer methods with "Cookie" in their
  name. Note that as the information that Chrome has about these accounts is
  fundamentally different than that which Chrome has about the user's accounts
  with OAuth2 refresh tokens, the struct encoding this information is also
  distinct: see accounts_in_cookie_jar_info.h.

# Interacting with IdentityManager and Friends in Tests
- IdentityTestEnvironment is the preferred test infrastructure for unittests
  of production code that interacts with IdentityManager. It is suitable for
  use in cases where neither the production code nor the unittest is interacting
  with Profile.
- identity_test_utils.h provides lower-level test facilities for interacting
  explicitly with IdentityManager. These facilities are the way to interact with
  IdentityManager in testing contexts where the production code and/or the
  unittest are interacting with Profile (in particular, where the
  IdentityManager instance with which the test is interacting must be
  IdentityManagerFactory::GetForProfile(profile)). Examples include integration
  tests and Profile-based unittests (in the latter case, consider migrating the
  test and production code away from using Profile directly and using
  IdentityTestEnvironment).

# Mutation of Account State
- Various mutators of account state are available through IdentityManager (e.g.,
  PrimaryAccountMutator). These should in general be used only as part of larger
  embedder-specific flows for mutating the user's account state in ways that are
  in line with product specifications. If you are a consumer of
  //components/identity/public/identity_manager and you believe that you have a
  new use case for one of these API surfaces, you should first contact the
  OWNERS of //components/signin to discuss this use case and how best to realize
  it. With these caveats, here are the details of how various operations are
  supported on the various platforms on which Chrome runs:
  * Mutating the primary account: Setting the primary account is done via
    PrimaryAccountMutator::SetPrimaryAccount(); see the comments on the
    declaration of that method for the conditions required for the setting of
    the primary account to succeed. On all platforms other than ChromeOS, the
    primary account can be cleared via
    PrimaryAccountMutator::ClearPrimaryAccount() (on ChromeOS, the primary
    account cannot be cleared as there is no user-level flow to sign out of
    the browser).
  * Updating the state of the accounts in the Gaia cookie: This is supported via
    AccountsCookieMutator.
  * Mutating the set of accounts with refresh tokens: The ways in which this
    occurs are platform-specific due to the differences in underlying platform
    account management (or lack thereof). We detail these below:
    - Windows/Mac/Linux: Chrome manages the user's OAuth2 refresh tokens
      internally. Adding and removing accounts with refresh tokens is done via
      AccountsMutator.
    - ChromeOS: Chrome is backed by ChromeOS' platform-level AccountManager.
      Chrome's view of the accounts with refresh tokens is synchronized with
      the platform-level state by observing that platform-level AccountManager
      internally.
    - Android: Chrome is backed by Android's platform-level AccountManager (in
      Java). Chrome's view of the accounts with refresh tokens is synchronized
      with the platform-level state via IdentityMutator.java.
    - iOS: Chrome is backed by Google's iOS SSO library for supporting shared
      identities between Google's various iOS applications. Chrome's view of the
      accounts with refresh tokens is synchronized with the platform-level state
      via DeviceAccountsSynchronizer.

# Mental Mapping from Chromium's Historical API Surfaces for Signin
Documentation on the mapping between usage of legacy signin
classes (notably PrimaryAccountManager and ProfileOAuth2TokenService) and usage
of IdentityManager is available here:

https://docs.google.com/document/d/14f3qqkDM9IE4Ff_l6wuXvCMeHfSC9TxKezXTCyeaPUY/edit#