dom/docs/fedcm.rst

   1 ===============================
   2 Federated Credential Management
   3 ===============================
   4
   5 FedCM, as it is abbreviated, is a platform feature that requires a full-stack implementation.
   6 As such, its code is scattered throughout the codebase and it can be hard to follow the flow of execution.
   7 This documentation aims to make those two points easier.
   8
   9 Code sites
  10 ==========
  11
  12 Code relevant to it can be found in all of the following places.
  13
  14 The webidl for this spec lives in ``dom/webidl/IdentityCredential.webidl``
  15
  16 Core spec algorithm logic and the implementation of the ``IdentityCredential`` live in ``dom/credentialmanagement/identity/IdentityCredential.{cpp,h}``. The static functions of ``IdentityCredential`` are the spec algorithm logic. Helpers for managing the ``IdentityCredential.webidl`` objects are in the other files in ``dom/credentialmanagement/identity/``. The IPC is defined on the WindowGlobal in ``dom/ipc/PWindowGlobal.ipdl`` and ``dom/ipc/WindowGlobalParent.cpp``, and is a very thin layer.
  17
  18 The service for managing state associated with IdentityCredentials is ``IdentityCredentialStorageService`` and the service for managing the UI prompts associated with IdentityCredentials is ``IdentityCredentialPromptService``. Both definitions and implementations are in ``toolkit/components/credentialmanagement``.
  19
  20 The UI panel is spread around a little. The actual DOM elements are in the HTML subtree with root at ``#identity-credential-notification`` in ``browser/base/content/popup-notifications.inc``. But the CSS describing it is spread through ``browser/themes/shared/customizableui/panelUI-shared.css``, ``browser/themes/shared/identity-credential-notification.css``, and ``browser/themes/shared/notification-icons.css``. Generally speaking, search for ``identity-credential`` in those files to find the relevant ids and classes.
  21
  22 Content strings: ``browser/locales/en-US/browser/identityCredentialNotification.ftl``.
  23
  24 All of this is entered from the ``navigator.credentials`` object, implemented in ``dom/credentialmanagement/CredentialsContainer.{cpp,h}``.
  25
  26 Flow of Execution
  27 =================
  28
  29 This is the general flow through code relevant to the core spec algorithms, which happens to be the complicated parts imo.
  30
  31 A few notes:
  32
  33 - All functions without a class specified are in ``IdentityCredential``.
  34 - Functions in ``IdentityCredentialPromptService`` mutate the Chrome DOM
  35 - FetchT functions send network requests via ``mozilla::dom::FetchJSONStructure<T>``.
  36 - A call to ``IdentityCredentialStorageService`` is made in ``PromptUserWithPolicy``
  37
  38 .. graphviz::
  39
  40   digraph fedcm {
  41     "RP (visited page) calls ``navigator.credentials.get()``" -> "CredentialsContainer::Get"
  42     "CredentialsContainer::Get" -> "DiscoverFromExternalSource"
  43     "DiscoverFromExternalSource" -> "DiscoverFromExternalSourceInMainProcess" [label="IPC via WindowGlobal's DiscoverIdentityCredentialFromExternalSource"]
  44     "DiscoverFromExternalSourceInMainProcess" -> "anonymous timeout callback" -> "CloseUserInterface" -> "IdentityCredentialPromptService::Close"
  45     "DiscoverFromExternalSourceInMainProcess" -> "CheckRootManifest A"
  46     "CheckRootManifest A" -> "FetchInternalManifest A" [label="via promise chain in DiscoverFromExternalSourceInMainProcess"]
  47     "FetchInternalManifest A" -> "DiscoverFromExternalSourceInMainProcess inline anonymous callback (Promise::All)"
  48     "DiscoverFromExternalSourceInMainProcess" -> "CheckRootManifest N"
  49     "CheckRootManifest N" -> "FetchInternalManifest N" [label="via promise chain in DiscoverFromExternalSourceInMainProcess"]
  50     "FetchInternalManifest N" -> "DiscoverFromExternalSourceInMainProcess inline anonymous callback (Promise::All)"
  51     "DiscoverFromExternalSourceInMainProcess inline anonymous callback (Promise::All)" -> "PromptUserToSelectProvider"
  52     "PromptUserToSelectProvider" -> "IdentityCredentialPromptService::ShowProviderPrompt"
  53     "IdentityCredentialPromptService::ShowProviderPrompt" -> "CreateCredential" [label="via promise chain in DiscoverFromExternalSourceInMainProcess"]
  54     "CreateCredential" -> "FetchAccountList" [label="via promise chain in CreateCredential"]
  55     "FetchAccountList" -> "PromptUserToSelectAccount" [label="via promise chain in CreateCredential"]
  56     "PromptUserToSelectAccount" -> "IdentityCredentialPromptService::ShowAccountListPrompt"
  57     "IdentityCredentialPromptService::ShowAccountListPrompt" -> "PromptUserWithPolicy" [label="via promise chain in CreateCredential"]
  58     "PromptUserWithPolicy" -> "FetchMetadata"
  59     "FetchMetadata" -> "IdentityCredentialPromptService::ShowPolicyPrompt" [label="via promise chain in PromptUserWithPolicy"]
  60     "IdentityCredentialPromptService::ShowPolicyPrompt" -> "FetchToken" [label="via promise chain in CreateCredential"]
  61     "FetchToken" -> "cancel anonymous timeout callback"
  62     "FetchToken" -> "CreateCredential inline anonymous callback"
  63     "CreateCredential inline anonymous callback" -> "DiscoverFromExternalSourceInMainProcess inline anonymous callback"
  64     "DiscoverFromExternalSourceInMainProcess inline anonymous callback" -> "DiscoverFromExternalSource inline anonymous callback" [label="Resolving IPC via WindowGlobal's DiscoverIdentityCredentialFromExternalSource"]
  65     "DiscoverFromExternalSource inline anonymous callback" -> "CredentialsContainer::Get inline anonymous callback"
  66     "CredentialsContainer::Get inline anonymous callback" -> "RP (visited page) gets the credential"
  67   }