From 40e989765417c1d5de4a8152d622c7f5bc68ef46 Mon Sep 17 00:00:00 2001
From: yi-gu <yigu@google.com>
Date: Mon, 25 Mar 2024 14:25:14 -0400
Subject: [PATCH] Update HOWTO-chrome.md with button flow dev trial instruction
 (#551)

* Update HOWTO-chrome.md with button flow dev trial instruction

* Apply suggestions from code review

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

* Update HOWTO-chrome.md

* Address comments

---------

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
---
 explorations/HOWTO-chrome.md | 61 ++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md
index 1ee0a9efc..d5534897d 100644
--- a/explorations/HOWTO-chrome.md
+++ b/explorations/HOWTO-chrome.md
@@ -333,3 +333,64 @@ IdP fails by either returning some network error or saying that the disconnectio
 was unsuccessful, or if the `account_id` is nowhere to be found, the browser will
 remove from local storage all of the federated accounts associated with the (RP,
 IDP).
+
+### Button Flow
+The button flow differs from the widget flow in several ways. The most significant
+difference is that the button flow requires a user gesture such as clicking on a
+sign-in button. This means that a user must be able to successfully sign in with a
+federated account using this flow. In contrast, the widget flow is an optimized
+flow that can reduce sign-in friction. This means that if the widget flow is
+unavailable, a user can still click a "Sign in with IdP" button to continue. See
+illustrative [mocks here](https://docs.google.com/presentation/d/1iURrPakaHgBfQ6mAefKijjxToiTTgBSPz1rtaV0od98/edit?usp=sharing).
+
+#### Button Mode API
+To use the Button Mode API:
+* Enable the experimental feature `FedCmButtonMode` in `chrome://flags`.
+* Make sure to invoke the API behind [transient user activation](https://html.spec.whatwg.org/multipage/interaction.html#transient-activation).
+* Invoke the API with the `mode` parameter like so:
+  ```js
+    return await navigator.credentials.get({
+        identity: {
+          providers: [{
+            configURL: "https://idp.example/config.json",
+            clientId: "123",
+            nonce: nonce
+          }],
+          mode: "button"
+        }
+    });
+  ```
+
+The browser will send a new parameter to the IdP representing the request type by including
+`mode=button` in the request sent to the ID assersion endpoint:
+```
+POST /fedcm_assertion_endpoint HTTP/1.1
+Host: idp.example
+Origin: https://rp.example/
+Content-Type: application/x-www-form-urlencoded
+Cookie: 0x23223
+Sec-Fetch-Dest: webidentity
+
+account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=false
+&mode=button
+```
+Note that we currently only include the new parameter in the button flow. Other flow
+types such as "widget" (name TBD) will be added when Chrome ships this feature.
+
+#### Use Other Account API
+This API allows users to use other accounts in the account chooser when, for example, IdPs
+support multiple accounts or replacing the existing account.
+
+To use the Use Other Account API:
+* Enable the experimental feature `FedCmUseOtherAccount` in `chrome://flags`.
+* IdP specifies the following in the FedCM config file:
+```
+{
+  "accounts_endpoint" : ...,
+  "modes: {
+    "button": {
+      "supports_use_other_account": true|false,
+    }
+  }
+}
+```