Add fedcm docs #23675

chrisdavidmills · 2023-01-16T12:14:18Z

Description

This PR adds content for the FedCM API.

See my research document for more information on the exact changes required for this addition.

Motivation

Additional details

Related issues and pull requests

github-actions · 2023-01-16T12:16:10Z

Preview URLs (10 pages)

Flaws (1)

Note! 9 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTTP/Headers/Permissions-Policy
Title: Permissions-Policy
Flaw count: 1

broken_links:
- No need for the pathname in anchor links if it's the same page

External URLs (10)

URL: /en-US/docs/Web/API/IdentityCredential
Title: IdentityCredential

https://developer.chrome.com/docs/privacy-sandbox/fedcm/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/IdentityCredential/token
Title: IdentityCredential.token

https://developer.chrome.com/docs/privacy-sandbox/fedcm/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/FedCM_API
Title: Federated Credential Management API (FedCM)

https://developer.chrome.com/docs/privacy-sandbox/fedcm/ (2 times) (Note! This may be a new URL 👀)
https://fedcm-main-frame.glitch.me/ (1 time) (Note! This may be a new URL 👀)
https://fedcm-rp-demo.glitch.me/ (1 time) (Note! This may be a new URL 👀)
User identity associated with the RP should not be sent to the IDP before explicit consent is gathered w3c-fedid/FedCM#230 (1 time) (Note! This may be a new URL 👀)
https://glitch.com/edit/ (4 times) (Note! This may be a new URL 👀)
https://openid.net/specs/openid-connect-frontchannel-1_0.html (1 time) (Note! This may be a new URL 👀)
https://web.dev/same-site-same-origin/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Glossary/Replay_attack
Title: Replay attack

https://en.wikipedia.org/wiki/Replay_attack (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-03-22 07:40:13)

agektmr

LGTM % nits

agektmr · 2023-02-06T08:26:30Z

files/en-us/web/api/fedcm_api/index.md

+
+The well-known file must be served from the [eTLD+1](https://web.dev/same-site-same-origin/#site) of the IdP at `/.well-known/web-identity`.
+
+For example, if the IdP endpoints are served under `https://accounts.idp.example/`, they must serve a well-known file at `https://idp.example/.well-known/web-identity`. The well-known file's content should look have the following JSON structure:


Is "should look have" a valid English expression I'm not familiar with?

Heh ... no, it's a typo ;-)

I've updated it to "should have" in my next commit.

agektmr · 2023-02-06T09:07:30Z

files/en-us/web/api/fedcm_api/index.md

+
+The browser requests the IdP config file and carries out the sign-in flow detailed below. For more information on the kind of interaction a user might expect from the browser-supplied UI, see [Sign in to the relying party with the identity provider](https://developer.chrome.com/docs/privacy-sandbox/fedcm/#sign-into-rp).
+
+### FedCM sign-in flow


I like how this section is separated from endpoint description and describes expected HTTP headers from RP point of view!

I like it too. I've basically copied the sign-in flow structure from one of your articles but added more details on what happens at each stage.

agektmr · 2023-02-06T09:50:59Z

files/en-us/web/api/credentialscontainer/get/index.md


 ### Exceptions

+- `NetworkError` {{domxref("DOMException")}}
+  - : In the case of a `get()` call with an `identity` option, this exception is thrown if the IdP does not respond within 60 seconds, or if the provided credentials are not valid/found.


I'm curious, publicKey type accepts timeout value. What happens if more than 60 seconds is specified to the timeout?

Good question. I've had a look through all the related specs, and can't find an answer. I'm guessing nothing, as the WebAuthn spec doesn't specify any kind of network/timeout error, and the timeout value is a hint indicating the time the caller is willing to wait, rather than a set value after which something will happen. Also, the two types don't seem to have any interplay at all.

OK, I noticed the concept of timeout is not part of Credential Management API and it's rather of PublicKeyCredential or IdentityCredential. So there's no contradiction. There might be a need to clarify what would happen when they are used together, but it's too early to worry about that. Please ignore this comment.

chrisdavidmills · 2023-02-07T07:36:26Z

Thanks for the review @agektmr ! I've made updates according to your comments and provided responses above. Let me know if there is anything else you think these docs need.

files/en-us/glossary/replay_attack/index.md

files/en-us/web/api/fedcm_api/index.md

Co-authored-by: Jean-Yves Perrier <[email protected]>

chrisdavidmills · 2023-02-07T15:52:11Z

Thanks @teoli2003 ; committed.

agektmr

Added one change request. Otherwise it's ready go.

files/en-us/web/api/fedcm_api/index.md

agektmr · 2023-03-06T02:32:06Z

files/en-us/web/api/credentialscontainer/get/index.md


 ### Exceptions

+- `NetworkError` {{domxref("DOMException")}}
+  - : In the case of a `get()` call with an `identity` option, this exception is thrown if the IdP does not respond within 60 seconds, or if the provided credentials are not valid/found.


OK, I noticed the concept of timeout is not part of Credential Management API and it's rather of PublicKeyCredential or IdentityCredential. So there's no contradiction. There might be a need to clarify what would happen when they are used together, but it's too early to worry about that. Please ignore this comment.

chrisdavidmills · 2023-03-06T07:19:29Z

It looks like this one is ready to go. All reviewed, and updates made.

@teoli2003 you've already looked at this one. Can you approve and merge?

teoli2003

A few details, then it is good to go for me.

teoli2003 · 2023-03-21T17:13:13Z

files/en-us/glossary/replay_attack/index.md

+  - Security
+---
+
+In web security, a _replay attack_ is when an attacker intercepts a previously-sent message and resends it later to get the same credentials as the original message, potentially with a different payload or instruction.


nit

Suggested change

In web security, a _replay attack_ is when an attacker intercepts a previously-sent message and resends it later to get the same credentials as the original message, potentially with a different payload or instruction.

In web security, a _replay attack_ happens when an attacker intercepts a previously-sent message and resends it later to get the same credentials as the original message, potentially with a different payload or instruction.

Updated in my next commit.

teoli2003 · 2023-03-21T17:15:18Z

files/en-us/web/api/credentialscontainer/get/index.md

+}
+```
+
+Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow) for more details on how this works. This call will start off the sign-in flow described in [FedCM sign-in flow](http://localhost:5042/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow).


The 2nd link is wrong here:

The first one was also wrong ;-) Should have pointed to the top of the FedCM page. I've fixed them both now.

teoli2003 · 2023-03-21T17:17:36Z

files/en-us/web/api/federatedcredential/index.md

@@ -11,6 +11,8 @@ browser-compat: api.FederatedCredential

 The **`FederatedCredential`** interface of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) provides information about credentials from a federated identity provider. A federated identity provider is an entity that a website trusts to correctly authenticate a user, and that provides an API for that purpose. [OpenID Connect](https://openid.net/developers/specs/) is an example of a federated identity provider framework.

+> **Note:** The newer [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) provides a more complete solution for handling identity federation in the browser, and uses the {{domxref("IdentityCredential")}} type.


Does it means FederatedCredential is deprecated: if not, maybe remove newer.

Suggested change

> **Note:** The newer [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) provides a more complete solution for handling identity federation in the browser, and uses the {{domxref("IdentityCredential")}} type.

> **Note:** The [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) provides a more complete solution for handling identity federation in the browser, and uses the {{domxref("IdentityCredential")}} type.

Sure; removed. I seem to remember that it is marked for deprecation, but not officially at this time.

teoli2003 · 2023-03-21T17:18:09Z

files/en-us/web/api/identitycredential/index.md

+
+A successful {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call that includes an `identity` option fulfills with an `IdentityCredential` instance.
+
+Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow) for more details on how this works. This call will start off the sign-in flow described in [FedCM sign-in flow](http://localhost:5042/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow).


D'oh, schoolboy error! Again, I've fixed them both.

teoli2003 · 2023-03-21T17:18:21Z

files/en-us/web/api/identitycredential/token/index.md

+
+A successful {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call that includes an `identity` option fulfills with an `IdentityCredential` instance, which can be used to access the token used to validate the sign-in.
+
+Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow) for more details on how this works. This call will start off the sign-in flow described in [FedCM sign-in flow](http://localhost:5042/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow).


localhost...

And fixed again ;-)

chrisdavidmills · 2023-03-22T07:38:59Z

@teoli2003 thanks for the review. Fixes made as requested.

teoli2003

👍

We should raise a flow for https://localhost URLs as links.

chrisdavidmills added 2 commits January 16, 2023 12:04

Add docs for FedCM API

b9aff8f

Add docs for FedCM API

f100d68

chrisdavidmills requested review from a team as code owners January 16, 2023 12:14

chrisdavidmills requested review from sideshowbarker and bsmth and removed request for a team January 16, 2023 12:14

github-actions bot added Content:Glossary Glossary entries Content:WebAPI Web API docs labels Jan 16, 2023

Merge branch 'main' into add-fedcm-docs

d513e95

chrisdavidmills marked this pull request as draft January 16, 2023 12:17

Add identity-credentials-get Permissions-Policy info

f850830

github-actions bot added the Content:HTTP HTTP docs label Jan 16, 2023

Merge branch 'main' into add-fedcm-docs

2dcf5b7

chrisdavidmills marked this pull request as ready for review January 16, 2023 13:59

chrisdavidmills requested a review from a team as a code owner January 16, 2023 13:59

chrisdavidmills requested review from teoli2003 and removed request for a team January 16, 2023 13:59

Merge branch 'main' into add-fedcm-docs

3792ab2

agektmr reviewed Feb 6, 2023

View reviewed changes

chrisdavidmills added 3 commits February 7, 2023 07:07

Merge branch 'main' into add-fedcm-docs

0c2b152

Making fixes for agektmr comments

6c0f076

Merge branch 'main' into add-fedcm-docs

2881a69

teoli2003 reviewed Feb 7, 2023

View reviewed changes

files/en-us/glossary/replay_attack/index.md Outdated Show resolved Hide resolved

teoli2003 reviewed Feb 7, 2023

View reviewed changes

files/en-us/web/api/fedcm_api/index.md Outdated Show resolved Hide resolved

Update files/en-us/glossary/replay_attack/index.md

09e7c0a

Co-authored-by: Jean-Yves Perrier <[email protected]>

Update files/en-us/web/api/fedcm_api/index.md

3f3f78c

Co-authored-by: Jean-Yves Perrier <[email protected]>

jsmrcaga mentioned this pull request Feb 23, 2023

WebAuthN Docs: add descriptions and details for PublicKey credential creation #24813

Merged

agektmr reviewed Mar 6, 2023

View reviewed changes

chrisdavidmills added 2 commits March 6, 2023 07:09

Merge branch 'main' into add-fedcm-docs

56004f8

Change Referer header references to to Origin

00d7c82

teoli2003 suggested changes Mar 21, 2023

View reviewed changes

Making fixes for teoli2003 comments

3729ae0

teoli2003 approved these changes Mar 22, 2023

View reviewed changes

teoli2003 merged commit 1ac70b3 into mdn:main Mar 22, 2023

teoli2003 mentioned this pull request Mar 22, 2023

Forbid links to localhost with Markdownlint #25542

Closed

3 tasks

chrisdavidmills deleted the add-fedcm-docs branch March 22, 2023 10:16

Josh-Cena mentioned this pull request Jul 3, 2023

Intent to document: Fed CM #23484

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add fedcm docs #23675

Add fedcm docs #23675

chrisdavidmills commented Jan 16, 2023

github-actions bot commented Jan 16, 2023 •

edited

Loading

agektmr left a comment

agektmr Feb 6, 2023

chrisdavidmills Feb 7, 2023

agektmr Feb 6, 2023

chrisdavidmills Feb 7, 2023

agektmr Feb 6, 2023

chrisdavidmills Feb 7, 2023

agektmr Mar 6, 2023

chrisdavidmills commented Feb 7, 2023

chrisdavidmills commented Feb 7, 2023

agektmr left a comment

agektmr Mar 6, 2023

chrisdavidmills commented Mar 6, 2023

teoli2003 left a comment

teoli2003 Mar 21, 2023

chrisdavidmills Mar 22, 2023

teoli2003 Mar 21, 2023 •

edited

Loading

chrisdavidmills Mar 22, 2023

teoli2003 Mar 21, 2023 •

edited

Loading

chrisdavidmills Mar 22, 2023

teoli2003 Mar 21, 2023

chrisdavidmills Mar 22, 2023

teoli2003 Mar 21, 2023

chrisdavidmills Mar 22, 2023

chrisdavidmills commented Mar 22, 2023

teoli2003 left a comment


		The well-known file must be served from the [eTLD+1](https://web.dev/same-site-same-origin/#site) of the IdP at `/.well-known/web-identity`.

		For example, if the IdP endpoints are served under `https://accounts.idp.example/`, they must serve a well-known file at `https://idp.example/.well-known/web-identity`. The well-known file's content should look have the following JSON structure:


		The browser requests the IdP config file and carries out the sign-in flow detailed below. For more information on the kind of interaction a user might expect from the browser-supplied UI, see [Sign in to the relying party with the identity provider](https://developer.chrome.com/docs/privacy-sandbox/fedcm/#sign-into-rp).

		### FedCM sign-in flow

	In web security, a _replay attack_ is when an attacker intercepts a previously-sent message and resends it later to get the same credentials as the original message, potentially with a different payload or instruction.
	In web security, a _replay attack_ happens when an attacker intercepts a previously-sent message and resends it later to get the same credentials as the original message, potentially with a different payload or instruction.

		@@ -11,6 +11,8 @@ browser-compat: api.FederatedCredential

		The `FederatedCredential` interface of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) provides information about credentials from a federated identity provider. A federated identity provider is an entity that a website trusts to correctly authenticate a user, and that provides an API for that purpose. [OpenID Connect](https://openid.net/developers/specs/) is an example of a federated identity provider framework.

		> Note: The newer [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) provides a more complete solution for handling identity federation in the browser, and uses the {{domxref("IdentityCredential")}} type.

	> Note: The newer [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) provides a more complete solution for handling identity federation in the browser, and uses the {{domxref("IdentityCredential")}} type.
	> Note: The [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) provides a more complete solution for handling identity federation in the browser, and uses the {{domxref("IdentityCredential")}} type.


		A successful {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call that includes an `identity` option fulfills with an `IdentityCredential` instance.

		Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow) for more details on how this works. This call will start off the sign-in flow described in [FedCM sign-in flow](http://localhost:5042/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow).

Add fedcm docs #23675

Add fedcm docs #23675

Conversation

chrisdavidmills commented Jan 16, 2023

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Jan 16, 2023 • edited Loading

agektmr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills commented Feb 7, 2023

chrisdavidmills commented Feb 7, 2023

agektmr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills commented Mar 6, 2023

teoli2003 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

teoli2003 Mar 21, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

teoli2003 Mar 21, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills commented Mar 22, 2023

teoli2003 left a comment

Choose a reason for hiding this comment

github-actions bot commented Jan 16, 2023 •

edited

Loading

teoli2003 Mar 21, 2023 •

edited

Loading

teoli2003 Mar 21, 2023 •

edited

Loading