From c665d3bea3f8bf9e90ad27de6916e306c5f88808 Mon Sep 17 00:00:00 2001 From: yi-gu Date: Tue, 3 Oct 2023 09:41:29 -0400 Subject: [PATCH 1/8] Update HOWTO-chrome.md with Error API and AccountAutoSelected API --- explorations/HOWTO-chrome.md | 42 ++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index 764104bf9..7921ae422 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -158,3 +158,45 @@ In order to use the IdP Sign-in Status API: 5. The browser is going load the `signin_url` when the user is signed-out of the IdP. 6. Call `IdentityProvider.close()` when the user is done logging-in to the IdP. +### Error API + +In order to use the Error API: + +* Enable the experimental feature `FedCmError` in `chrome://flags`. +* Provide an `error` in the id assertion endpoint instead of a `token`: +``` +{ + "error" : { + "code" : "access_denied", + "url" : "https://idp.example/error?type=foo" + } +} +``` +Note that the `error` field in the response including both `code` and `url` is optional. As long as the flag is enabled, the browser will render an error UI when the token request is failed. The `error` field is used to customize the flow when an error happens. The browser will show a customized UI with proper error message if the code is one of "invalid_request", "unauthorized_client", "access_denied", "server_error", and "temporarily_unavailable". If a `url` field is provided, the browser will add an affordance for users to open a new page (e.g. via pop-up window) with that URL to learn more about the error on that page. + +### AccountAutoSelectedFlag API + +In order to use the AccountAutoSelectedFlag API: +* Enable the experimental feature `FedCmAccountAutoSelectedFlag` in `chrome://flags`. + +The browser will send a new boolean to represent whether auto re-authentication was triggered such that the account was auto selected by the browser in the flow to both the IdP and the API caller. + +For IdP, the browser will include the boolean `is_account_auto_selected` 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 + +is_account_auto_selected=true&account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true +``` + +For the API caller, the browser will include the boolean `isAccountAutoSelected` when resolving the promise with the token: +``` +{ + "token": "eyJC...J9.eyJzdWTE2...MjM5MDIyfQ.SflV_adQssw....5c", + "isAccountAutoSelected": true +} +``` From 7807b0353f95f20254eeb7d1f6351353598ebeb7 Mon Sep 17 00:00:00 2001 From: Yi Gu Date: Tue, 3 Oct 2023 15:38:51 -0400 Subject: [PATCH 2/8] Address comments --- explorations/HOWTO-chrome.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index 7921ae422..18051c393 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -24,7 +24,7 @@ includes the time when the sign-up status was set. ## Experimental functionality -In order to test experimental functionality: +To test experimental functionality: 1. Download Google Chrome Canary. It is best to experiment with the latest build possible to get the most up-to-date implementation. @@ -67,7 +67,7 @@ succeeded or failed. ### LoginHint -In order to use the LoginHint API: +To use the LoginHint API: * Enable the experimental feature `FedCmLoginHint` in `chrome://flags`. * Add an array of `hints` to the accounts described in the accounts endpoint: @@ -102,7 +102,7 @@ Now, only accounts with the "hint" provided will show in the chooser. ### UserInfo -In order to use the UserInfo API: +To use the UserInfo API: * Enable the experimental feature `FedCmLoginHint` in `chrome://flags`. * The RP must embed an IDP iframe, which will perform the query. @@ -128,7 +128,7 @@ user_info.forEach( info => { ### RP Context -In order to use the RP Context API: +To use the RP Context API: * Enable the experimental feature `FedCmRpContext` in `chrome://flags`. * Provide the `context` value in JS, like so: @@ -149,7 +149,7 @@ Now, the browser UI will be different based on the value provided. ### IdP Sign-in Status API -In order to use the IdP Sign-in Status API: +To use the IdP Sign-in Status API: 1. Enable the experimental feature `FedCM with FedCM IDP sign-in status` in `chrome://flags`. 2. When the user logs-in to the IdP, use the following HTTP header `IdP-SignIn-Status: action=signin`. @@ -160,7 +160,7 @@ In order to use the IdP Sign-in Status API: ### Error API -In order to use the Error API: +To use the Error API: * Enable the experimental feature `FedCmError` in `chrome://flags`. * Provide an `error` in the id assertion endpoint instead of a `token`: @@ -172,11 +172,18 @@ In order to use the Error API: } } ``` -Note that the `error` field in the response including both `code` and `url` is optional. As long as the flag is enabled, the browser will render an error UI when the token request is failed. The `error` field is used to customize the flow when an error happens. The browser will show a customized UI with proper error message if the code is one of "invalid_request", "unauthorized_client", "access_denied", "server_error", and "temporarily_unavailable". If a `url` field is provided, the browser will add an affordance for users to open a new page (e.g. via pop-up window) with that URL to learn more about the error on that page. - -### AccountAutoSelectedFlag API - -In order to use the AccountAutoSelectedFlag API: +Note that the `error` field in the response including both `code` and `url` is +optional. As long as the flag is enabled, Chrome will render an error UI when +the token request fails. The `error` field is used to customize the flow when an +error happens. Chrome will show a customized UI with proper error message if the +code is "invalid_request", "unauthorized_client", "access_denied", "server_error", +or "temporarily_unavailable". If a `url` field is provided, Chrome will add an +affordance for users to open a new page (e.g., via pop-up window) with that URL +to learn more about the error on that page. + +### `AccountAutoSelectedFlag` API + +To use the AccountAutoSelectedFlag API: * Enable the experimental feature `FedCmAccountAutoSelectedFlag` in `chrome://flags`. The browser will send a new boolean to represent whether auto re-authentication was triggered such that the account was auto selected by the browser in the flow to both the IdP and the API caller. @@ -190,7 +197,7 @@ Content-Type: application/x-www-form-urlencoded Cookie: 0x23223 Sec-Fetch-Dest: webidentity -is_account_auto_selected=true&account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true +account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_account_auto_selected=true ``` For the API caller, the browser will include the boolean `isAccountAutoSelected` when resolving the promise with the token: From 35db075b9f26ea6136f94ce490dd09aa77bb3ef3 Mon Sep 17 00:00:00 2001 From: yi-gu Date: Tue, 3 Oct 2023 20:02:54 -0400 Subject: [PATCH 3/8] Update explorations/HOWTO-chrome.md Co-authored-by: Kyle Den Hartog --- explorations/HOWTO-chrome.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index 18051c393..f3ab6dd31 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -188,7 +188,7 @@ To use the AccountAutoSelectedFlag API: The browser will send a new boolean to represent whether auto re-authentication was triggered such that the account was auto selected by the browser in the flow to both the IdP and the API caller. -For IdP, the browser will include the boolean `is_account_auto_selected` in the request sent to the id assersion endpoint: +For IdP, the browser will include the boolean `is_account_auto_selected` in the request sent to the id assertion endpoint: ``` POST /fedcm_assertion_endpoint HTTP/1.1 Host: idp.example From 671b1165183b7f45d66d842ae9e1142435004695 Mon Sep 17 00:00:00 2001 From: Yi Gu Date: Thu, 12 Oct 2023 14:02:18 -0400 Subject: [PATCH 4/8] Rename the API for extensibility --- explorations/HOWTO-chrome.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index f3ab6dd31..fc7aba8d1 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -177,18 +177,23 @@ optional. As long as the flag is enabled, Chrome will render an error UI when the token request fails. The `error` field is used to customize the flow when an error happens. Chrome will show a customized UI with proper error message if the code is "invalid_request", "unauthorized_client", "access_denied", "server_error", -or "temporarily_unavailable". If a `url` field is provided, Chrome will add an -affordance for users to open a new page (e.g., via pop-up window) with that URL -to learn more about the error on that page. +or "temporarily_unavailable". If a `url` field is provided and same-site with +the IdP's `configURL`, Chrome will add an affordance for users to open a new +page (e.g., via pop-up window) with that URL to learn more about the error on +that page. -### `AccountAutoSelectedFlag` API +### `IdentityCredentialAutoSelectedFlag` API -To use the AccountAutoSelectedFlag API: -* Enable the experimental feature `FedCmAccountAutoSelectedFlag` in `chrome://flags`. +To use the IdentityCredentialAutoSelectedFlag API: +* Enable the experimental feature `FedCmIdentityCredentialAutoSelectedFlag` +in `chrome://flags`. -The browser will send a new boolean to represent whether auto re-authentication was triggered such that the account was auto selected by the browser in the flow to both the IdP and the API caller. +The browser will send a new boolean to represent whether auto re-authentication +was triggered such that the account was auto selected by the browser in the flow +to both the IdP and the API caller. -For IdP, the browser will include the boolean `is_account_auto_selected` in the request sent to the id assertion endpoint: +For IdP, the browser will include `is_identity_credential_auto_selected` in the +request sent to the id assersion endpoint: ``` POST /fedcm_assertion_endpoint HTTP/1.1 Host: idp.example @@ -197,13 +202,14 @@ 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_account_auto_selected=true +account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_identity_credential_auto_selected=true ``` -For the API caller, the browser will include the boolean `isAccountAutoSelected` when resolving the promise with the token: +For the API caller, the browser will include the boolean +`isIdentityCredentialAutoSelected` when resolving the promise with the token: ``` { "token": "eyJC...J9.eyJzdWTE2...MjM5MDIyfQ.SflV_adQssw....5c", - "isAccountAutoSelected": true + "isIdentityCredentialAutoSelected": true } ``` From 013a93a09cab119e34a002df32d32504326c01c4 Mon Sep 17 00:00:00 2001 From: Yi Gu Date: Tue, 17 Oct 2023 09:35:47 -0400 Subject: [PATCH 5/8] change lower case id --- explorations/HOWTO-chrome.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index fc7aba8d1..5be275a22 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -163,7 +163,7 @@ To use the IdP Sign-in Status API: To use the Error API: * Enable the experimental feature `FedCmError` in `chrome://flags`. -* Provide an `error` in the id assertion endpoint instead of a `token`: +* Provide an `error` in the ID assertion endpoint instead of a `token`: ``` { "error" : { @@ -182,7 +182,7 @@ the IdP's `configURL`, Chrome will add an affordance for users to open a new page (e.g., via pop-up window) with that URL to learn more about the error on that page. -### `IdentityCredentialAutoSelectedFlag` API +### IdentityCredentialAutoSelectedFlag API To use the IdentityCredentialAutoSelectedFlag API: * Enable the experimental feature `FedCmIdentityCredentialAutoSelectedFlag` @@ -193,7 +193,7 @@ was triggered such that the account was auto selected by the browser in the flow to both the IdP and the API caller. For IdP, the browser will include `is_identity_credential_auto_selected` in the -request sent to the id assersion endpoint: +request sent to the ID assersion endpoint: ``` POST /fedcm_assertion_endpoint HTTP/1.1 Host: idp.example From 3ccbb07a235816f8affe5b31fccefae032423d07 Mon Sep 17 00:00:00 2001 From: Yi Gu Date: Tue, 17 Oct 2023 10:29:56 -0400 Subject: [PATCH 6/8] Update JS snippet --- explorations/HOWTO-chrome.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index 5be275a22..5efd51c58 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -205,11 +205,20 @@ Sec-Fetch-Dest: webidentity account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_identity_credential_auto_selected=true ``` -For the API caller, the browser will include the boolean -`isIdentityCredentialAutoSelected` when resolving the promise with the token: +For the API caller, the browser will include a boolean when resolving the +promise for it to parse: ``` -{ - "token": "eyJC...J9.eyJzdWTE2...MjM5MDIyfQ.SflV_adQssw....5c", - "isIdentityCredentialAutoSelected": true +const cred = await navigator.credentials.get({ + identity: { + providers: [{ + configURL: "https://idp.example/manifest.json", + clientId: "1234" + }] + } +}); + +const token = cred.token; +if (cred.isIdentityCredentialAutoSelected !== undefined) { + const isAutoSelected = cred.isIdentityCredentialAutoSelected; } ``` From 8a6684e63cb4c19ed5caf3c28b5d00fcc790f65d Mon Sep 17 00:00:00 2001 From: Yi Gu Date: Tue, 17 Oct 2023 11:42:48 -0400 Subject: [PATCH 7/8] nit --- explorations/HOWTO-chrome.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index 5efd51c58..511c55333 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -206,7 +206,7 @@ account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_i ``` For the API caller, the browser will include a boolean when resolving the -promise for it to parse: +promise: ``` const cred = await navigator.credentials.get({ identity: { From a0f208fbadaf7c14b50e6f6b4ba695702302d80c Mon Sep 17 00:00:00 2001 From: Yi Gu Date: Tue, 17 Oct 2023 12:34:47 -0400 Subject: [PATCH 8/8] remove flag for shipped feature --- explorations/HOWTO-chrome.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/explorations/HOWTO-chrome.md b/explorations/HOWTO-chrome.md index 511c55333..c800e835f 100644 --- a/explorations/HOWTO-chrome.md +++ b/explorations/HOWTO-chrome.md @@ -69,7 +69,6 @@ succeeded or failed. To use the LoginHint API: -* Enable the experimental feature `FedCmLoginHint` in `chrome://flags`. * Add an array of `hints` to the accounts described in the accounts endpoint: ``` @@ -104,7 +103,6 @@ Now, only accounts with the "hint" provided will show in the chooser. To use the UserInfo API: -* Enable the experimental feature `FedCmLoginHint` in `chrome://flags`. * The RP must embed an IDP iframe, which will perform the query. * The embedded iframe must receive permissions to invoke FedCM (via Permissions Policy). * The user first needs to go through the FedCM flow once before invoking UserInfo. @@ -130,7 +128,6 @@ user_info.forEach( info => { To use the RP Context API: -* Enable the experimental feature `FedCmRpContext` in `chrome://flags`. * Provide the `context` value in JS, like so: ```js