From b9aff8f94cc0956d38939e02c99502811e1d2106 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 16 Jan 2023 12:04:58 +0000 Subject: [PATCH 1/8] Add docs for FedCM API --- files/en-us/glossary/challenge/index.md | 2 +- files/en-us/glossary/replay_attack/index.md | 14 + files/en-us/web/api/credential/index.md | 7 +- .../web/api/credentialscontainer/get/index.md | 48 ++- files/en-us/web/api/fedcm_api/index.md | 307 ++++++++++++++++++ .../web/api/federatedcredential/index.md | 2 + .../en-us/web/api/identitycredential/index.md | 59 ++++ .../web/api/identitycredential/token/index.md | 57 ++++ files/jsondata/GroupData.json | 7 + 9 files changed, 490 insertions(+), 13 deletions(-) create mode 100644 files/en-us/glossary/replay_attack/index.md create mode 100644 files/en-us/web/api/fedcm_api/index.md create mode 100644 files/en-us/web/api/identitycredential/index.md create mode 100644 files/en-us/web/api/identitycredential/token/index.md diff --git a/files/en-us/glossary/challenge/index.md b/files/en-us/glossary/challenge/index.md index 026036bd89e948f..9bb43e8ff8880b4 100644 --- a/files/en-us/glossary/challenge/index.md +++ b/files/en-us/glossary/challenge/index.md @@ -5,7 +5,7 @@ tags: - Security --- -In security protocols, a _challenge_ is some data sent to the client by the server in order to generate a different response each time. Challenge-response protocols are one way to fight against [replay attacks](https://en.wikipedia.org/wiki/Replay_attack) where an attacker listens to the previous messages and resends them at a later time to get the same credentials as the original message. +In security protocols, a _challenge_ is some data sent to the client by the server in order to generate a different response each time. Challenge-response protocols are one way to fight against {{glossary("replay attack", "replay attacks")}} where an attacker listens to the previous messages and resends them at a later time to get the same credentials as the original message. The [HTTP authentication protocol](/en-US/docs/Web/HTTP/Authentication) is challenge-response based, though the "Basic" protocol isn't using a real challenge (the realm is always the same). diff --git a/files/en-us/glossary/replay_attack/index.md b/files/en-us/glossary/replay_attack/index.md new file mode 100644 index 000000000000000..26d90d856b16bfa --- /dev/null +++ b/files/en-us/glossary/replay_attack/index.md @@ -0,0 +1,14 @@ +--- +title: Replay attack +slug: Glossary/Replay_attack +tags: + - Security +--- + +In web security, a _replay attack_ is when an attacker intercepts a previously-sent message and resends it at a later time to get the same credentials as the original message, potentially with a different payload or instruction. + +Replay attacks can be prevented by including a unique, single-use identifier with each message that can be used by the receiver to verify the authenticity of the transmission. This can take the form of a session token or "number used only once" ("nonce"). + +## See also + +- [Replay attack](https://en.wikipedia.org/wiki/Replay_attack) on Wikipedia. diff --git a/files/en-us/web/api/credential/index.md b/files/en-us/web/api/credential/index.md index 4c7467640bc3d14..13a0ce61da375e8 100644 --- a/files/en-us/web/api/credential/index.md +++ b/files/en-us/web/api/credential/index.md @@ -14,13 +14,14 @@ browser-compat: api.Credential {{APIRef("Credential Management API")}}{{securecontext_header}} -The **`Credential`** interface of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) provides information about an entity (usually a user) as a prerequisite to a trust decision. +The **`Credential`** interface of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) provides information about an entity (usually a user) normally as a prerequisite to a trust decision. -`Credential` objects may be of 3 different types: +`Credential` objects may be of four different types: +- {{domxref("FederatedCredential")}} +- {{domxref("IdentityCredential")}} - {{domxref("PasswordCredential")}} - {{domxref("PublicKeyCredential")}} -- {{domxref("FederatedCredential")}} ## Instance properties diff --git a/files/en-us/web/api/credentialscontainer/get/index.md b/files/en-us/web/api/credentialscontainer/get/index.md index e8601e3ec0bbef1..3577c053ae1b483 100644 --- a/files/en-us/web/api/credentialscontainer/get/index.md +++ b/files/en-us/web/api/credentialscontainer/get/index.md @@ -50,11 +50,11 @@ get(options) to have, and options for interacting with the user. It can contain the following properties: - - `password` + - `password` {{optional_inline}} - : a boolean value indicating that returned {{domxref("Credential")}} instances should include user (as opposed to federated) credentials. - - `federated` + - `federated` {{optional_inline}} - : An object containing requirements for returned federated credentials. The available options are: @@ -62,11 +62,19 @@ get(options) - `providers` - : An array of string instances of identity providers to search for. - - `protocols` - - : An array of string instances of - federation protocols to search for. - - `publicKey` + - `identity` {{optional_inline}} + + - : An object containing details of federated identity providers (IdPs) that a relying party (RP) website can use to sign users in. Causes a `get()` call to initiate a request for a user to sign in to a RP with an IdP (see [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API)). `identity` can contain a single property, `providers`, which contains an array of objects each specifying the details of a separate IdP: + + - `configURL` + - : A string specifying the URL of the IdP's config file. See [Provide a config file](/en-US/docs/Web/API/FedCM_API#provide_a_config_file) for more information. + - `clientId` + - : A string specifying the the RP's client identifier, issued by the IdP to the RP in a completely separate process specific to the IdP. + - `nonce` {{optional_inline}} + - : A random string that can be included to ensure the response is issued for this specific request, and prevent {{glossary("replay attack", "replay attacks")}}. + + - `publicKey` {{optional_inline}} - : An object containing requirements for returned [WebAuthn](/en-US/docs/Web/API/Web_Authentication_API) credentials. The available options are: - `challenge` - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, or a {{jsxref("DataView")}} emitted by the relying party's server and used as a [cryptographic challenge](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication). This value will be signed by the authenticator and the signature will be sent back as part of {{domxref("AuthenticatorAssertionResponse.signature")}}. @@ -80,15 +88,15 @@ get(options) - : A string qualifying how the user verification should be part of the authentication process. - `extensions` {{optional_inline}} - : An object with several client extensions' inputs. Those extensions are used to request additional processing (e.g. dealing with legacy FIDO APIs credentials, prompting a specific text on the authenticator, etc.). - - `mediation` + - `mediation` {{optional_inline}} - : A {{jsxref("String")}} indicating whether the user will be required to log on for every visit to the website. Valid values are `"silent"`, `"optional"`, `"conditional"`, or `"required"`. - - `unmediated` {{deprecated_inline}} + - `unmediated` {{optional_inline}} {{deprecated_inline}} - : A boolean value indicating the returned {{domxref("Credential")}} instance should not require user mediation. - - `signal` + - `signal` {{optional_inline}} - : An instance of {{domxref("AbortSignal")}} that can indicate that an ongoing `get()` operation should be halted. An aborted operation may complete normally (generally if the abort was received after the @@ -106,6 +114,28 @@ obtained, the Promise will resolve to null. - `SecurityError` {{domxref("DOMException")}} - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +## Examples + +### Relying party sign-in using the FedCM API + +Relying parties (RPs) can call `navigator.credentials.get()` with the `identity` option to make a request for users to sign in to the RP via an identity provider (IdP), using identity federation. A typical request would look like this: + +```js +async function signIn() { + const identityCredential = await navigator.credentials.get({ + identity: { + providers: [{ + configURL: 'https://accounts.idp.example/config.json', + clientId: '********', + nonce: '******' + }] + } + }); +} +``` + +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). + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/fedcm_api/index.md b/files/en-us/web/api/fedcm_api/index.md new file mode 100644 index 000000000000000..6828f9a62bf1fc4 --- /dev/null +++ b/files/en-us/web/api/fedcm_api/index.md @@ -0,0 +1,307 @@ +--- +title: Federated Credential Management API (FedCM) +slug: Web/API/FedCM_API +page-type: web-api-overview +tags: + - API + - Experimental + - Overview + - Reference +browser-compat: + - api.IdentityCredential +--- + +{{SeeCompatTable}}{{DefaultAPISidebar("FedCM API")}} + +The Federated Credential Management API (FedCM) API provides a standard mechanism for identity providers to enable identity federation services in a privacy-preserving way, without relying on third-party cookies and redirects, and a JavaScript API for sites that rely on those services for sign-in functionality to make use of them. + +## FedCM concepts + +Identity federation is the delegation of user authentication from a website that requires user sign-in such as an e-commerce or social networking site (also known as a relying party or RP) to a trusted third party identity provider (IdP). Users will sign up an account with the IdP, which can then be used to sign-in to one or more RPs. Identity federation via a small set of dedicated identity providers has improved web authentication in terms of security, consumer confidence, and user experience, versus having every site handling their own sign-in needs with a separate username and password. + +The problem is that traditional identity federation relies on {{htmlelement("iframe")}}s, redirects, and third-party cookies, which are also used for third-party tracking. Browsers are limiting the usage of these features in an effort to preserve user privacy, but a side effect is that this makes valid, non-tracking uses more difficult to implement, and this includes identity federation. + +Affected identity federation use cases that rely on third-party cookies: + +- [OIDC front-channel logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html): This flow requires the IDP to embed several RP ` +``` + +## Interfaces + +- {{domxref("IdentityCredential")}} + - : Represents a user identity credential arising from a successful federated sign-in. A successful {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call that includes an `identity` option fulfills with an {{domxref("IdentityCredential")}} instance. + +## Extensions to other interfaces + +- {{domxref("CredentialsContainer.get()")}}, the `identity` option. + - : `identity` is an object containing details of federated identity providers (IdPs) that a relying party (RP) website can use to sign users in. Causes a `get()` call to initiate a request for a user to sign in to a RP with an IdP. + +## Examples + +- [FedCM sign-in example](https://fedcm-rp-demo.glitch.me/) + - [RP source code](https://glitch.com/edit/#!/fedcm-rp-demo?path=server.js%3A1%3A0) + - [IdP source code](https://glitch.com/edit/#!/fedcm-idp-demo?path=server.js%3A1%3A0) +- [FedCM ` ``` +The availability of FedCM within ` + ``` The availability of FedCM within `