Federated Credential Management API

W3C First Public Working Draft,

More details about this document
This version:
https://www.w3.org/TR/2024/WD-fedcm-1-20240820/
Latest published version:
https://www.w3.org/TR/fedcm/
Editor's Draft:
https://w3c-fedid.github.io/FedCM/
History:
https://www.w3.org/standards/history/fedcm-1/
Test Suite:
https://github.com/web-platform-tests/wpt/tree/master/fedcm
Feedback:
GitHub
Inline In Spec
Editor:
(Google Inc.)
Former Editor:
(Google Inc.)

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

A Web Platform API that allows users to login to websites with their federated accounts in a privacy preserving manner.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Federated Identity Working Group as a First Public Working Draft using the Recommendation track. This document is intended to become a W3C Recommendation.

The (archived) public mailing list [email protected] (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “fedcm” in the subject, preferably like this: “[fedcm] …summary of comment…”

This document is a First Public Working Draft.

Publication as a First Public Working Draft does not imply endorsement by W3C and its Members. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by the Federated Identity Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

This section is non-normative.

As the web has evolved there have been ongoing privacy-oriented changes (e.g Safari, Firefox, Chrome) and changes to the underlying privacy principles (e.g. Privacy Model).

With this evolution, fundamental assumptions of the web platform are being redefined or removed. Access to cookies in a third-party context are one of those assumptions. While overall good for the web, the third-party cookie deprecation removes a fundamental building block used by certain designs of federated identity.

The Federated Credential Management API aims to bridge the gap for the federated identity designs which relied on third-party cookies. The API provides the primitives needed to support federated identity when/where it depends on third-party cookies, from sign-in to sign-out and revocation.

In order to provide the federated identity primitives without the use of third-party cookies the API places the user agent as a mediator between a RP (website that requests user information for federated sign in) and an IDP (website that provides user information for federated sign in). This mediation requires user permission before allowing the RPs and IDPs to know about their connection to the user.

The specification leans heavily on changes in the user agent and IDP and minimally on the RP. The FedCM API provides a way to authenticate and fetch tokens.

Example showing how a website allowing for a single logged in account could be implemented. 
<html>
<head>
  <title>Welcome to my Website</title>
</head>
<body>
  <button onclick="login()">Login with idp.example</button>

  <script>
  let nonce;
  async function login() {
    try {
      // Assume there is a method returning a random number. Store the value in a variable which can
      // later be used to check against the value in the token returned.
      nonce = random();
      // Prompt the user to select an account from the IDP to use for
      // federated login within the RP. If resolved successfully, the Promise
      // returns an IdentityCredential object from which the |token| can be
      // extracted. This is an opaque string passed from the IDP to the RP.
      let token = await navigator.credentials.get({
        identity: {
          providers: [{
            configURL: "https://idp.example/manifest.json",
            clientId: "123",
            nonce: nonce,
          }]
        }
      });
    } catch(e) {
      // The FedCM call was not successful.
    }
  }
  </script>
</body>
</html>

At a high level, the Federated Credential Management API works by the intermediation of cooperating IDPs and RPs.

The § 3 Identity Provider HTTP API defines a set of HTTP APIs that IDPs expose as well as the entry points in the § 2 The Browser API that they can use.

The user agent intermediates in such a matter that makes it impractical for the API to be used for tracking purposes, while preserving the functionality of identity federation.

2. The Browser API

The Browser API exposes APIs to RPs and IDPs to call and intermediates the exchange of the user’s identity.

The Sign-up/Sign-in API is used by the RPs to ask the browser to intermediate the relationship with the IDP and the provisioning of a token.

NOTE: The RP makes no delineation between Sign-up and Sign-in, but rather calls the same API indistinguishably.

If all goes well, the Relying Party receives back an IdentityCredential which contains a token it can use to authenticate the user.

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
    }]
  }
});

For fetches that are sent with cookies, unpartitioned cookies are included, as if the resource was loaded as a same-origin request, e.g. regardless of the SameSite value (which is used when a resource loaded as a third-party, not first-party). This makes it easy for an IDP to adopt the FedCM API. It doesn’t introduce security issues on the API because the RP cannot inspect the results from the fetches in any way.

2.1. The Login Status API

2.1.1. Login Status Map

Each user agent keeps a global, persistent Login Status map, an initially empty map. The keys in this map are origin (of IDPs), and the values are enums that can be one of "unknown", "logged-in", and "logged-out".

To get the login status for an origin origin:

  1. If Login Status map[origin] exists, return it.

  2. Otherwise, return unknown.

To set the login status for an origin origin to value value:

  1. Assert that value is one of logged-in or logged-out.

  2. Set Login Status map[origin] to value.

2.1.2. Infrastructure algorithm

An environment settings object (settings) is same-site with its ancestors if the following algorithm returns true:

  1. If settings’s relevant global object has no associated Document, return false.

  2. Let document be settings’ relevant global object's associated Document.

  3. If document has no browsing context, return false.

  4. Let origin be settings’ origin.

  5. Let navigable be document’s node navigable.

  6. While navigable has a non-null parent:

    1. Set navigable to navigable’s parent.

    2. If navigable’s active document's origin is not same site with origin, return false.

  7. Return true.

2.1.3. HTTP header API

IDPs can set the login status using an HTTP response header as follows.

The HTTP header checking should move into the Fetch spec, since it affects all resource loads.

For each http-redirect fetch and http fetch's response, let value be the result of get a structured field value from the response’s header list with name "Set-Login" and type "item". If value is not null, process this header as follows:

  1. Let origin be the response’s URL's origin.

  2. Let client be the request's client.

  3. If the request’s destination is not "document":

    1. If client is null, return.

    2. If origin is not same site with the request's origin, return.

    3. If client is not same-site with its ancestors, return.

  4. Assert that value is a tuple.

  5. Let token be the first entry of value.

  6. If token is "logged-in", set the login status for origin to logged-in.

  7. If token is "logged-out", set the login status for origin to logged-out.

2.1.4. JavaScript API

IDPs can also use a JavaScript API to update the stored login status:

enum LoginStatus {
  "logged-in",
  "logged-out",
};

[Exposed=Window, SecureContext] 
interface NavigatorLogin {
  Promise<undefined> setStatus(LoginStatus status);
};

partial interface Navigator {
  [SecureContext] readonly attribute NavigatorLogin login;
};
When setStatus() is called with argument status:

  1. If the current settings object is not same-site with its ancestors, throw a SecurityError DOMException.

  2. Let origin be the current settings object's origin.

  3. Let value be logged-in if status is "logged-in" or logged-out if status is "logged-out".

  4. Set the login status for origin to value.

2.1.5. Clearing the Login Status Map data

User agents MUST also clear the Login Status map data when:

the user clears all cookies or site settings data

The user agent MUST clear the entire map.

the user clears all cookies or all site data for a specific origin

The user agent MUST remove all entries that would be affected by the deleted cookies, that is, any entry with an origin to which a deleted cookie could be sent to.

Note: For example, domain cookies may affect subdomains of the deleted origin, e.g. clearing cookies for google.com should also reset the login status for accounts.google.com, since it may rely on a domain cookie for google.com.

the user deletes individual cookies (if allowed by the user agent)

the behavior is user agent-defined.

Note: The user agent MAY want to reset the state to unknown, since is impossible to know whether this cookie affects authorization state.

the user agent receives a Clear-Site-Data header with a value of "cookies" or "*", and the request's client is not null, and the client’s origin is same origin with the top-level origin

while clearing cookies for origin it MUST remove any entries in the Login Status Map where the key is the input origin.

Once Clear-Site-Data supports partitioned cookies, this wording should be updated.

Note: Other website-initiated cookie changes should not affect this map. When IDP login state changes, it should send an explicit Set-Login header. RP state should not affect this map since it only reflects IDP state.

2.2. The connected accounts set

Each user agent has a global connected accounts set, an initially empty ordered set. Its items are triples of the form (rp, idp, account) where rp is the origin of the RP, idp is the origin of the IDP, and account is a string representing an account identifier. It represents the set of triples such that the user has used FedCM to login to the rp via the idp account.

the connected accounts set should be double keyed in the RP (i.e., it should include both the requester and the embedder, or in other words the iframe and the top-level). Otherwise the top-level’s state could be used and modified by the embedder, which introduces leaks and unwanted cross-origin communication.

If a user clears browsing data for an origin (cookies, localStorage, etc.), the user agent MUST remove all triples with an origin matching the origin from connected accounts set.

To compute the connected account key given an IdentityProviderConfig provider, an IdentityProviderAccount account, and a globalObject, run the following steps. It returns a triple of the form (rp, idp, account).

  1. Let configUrl be the result of running parse url with provider’s configURL and globalObject.

  2. Let idpOrigin be the origin corresponding to configUrl.

  3. Let rpOrigin be globalObject’s associated Document's origin.

  4. Let accountId be account’s id.

  5. Return (rpOrigin, idpOrigin, accountId).

When asked whether an IdentityProviderAccount account is eligible for auto reauthentication given an IdentityProviderConfig provider and a globalObject, run the following steps. This returns a boolean.

  1. If account contains approved_clients and account’s approved_clients does not contain provider’s clientId, return false.

  2. Let triple be the result of running compute the connected account key given provider, account, and globalObject.

  3. Return whether connected accounts set contains triple.

When asked to compute the connection status given an IdentityProviderAccount account, an IdentityProviderConfig provider and a globalObject, run the following steps. This returns connected or disconnected.

  1. If account contains approved_clients:

    1. If account’s approved_clients containsprovider’s clientId, return connected.

    2. Return disconnected.

  2. Let triple be the result of running compute the connected account key given provider, account, and globalObject.

  3. If connected accounts set contains triple, return connected.

  4. Return disconnected.

To create a connection between the RP and the IdP account given an IdentityProviderConfig provider, an IdentityProviderAccount account, and a globalObject (the RP's), run the following steps:

  1. Let configUrl be the result of running parse url with provider’s configURL and globalObject.

  2. Let idpOrigin be the origin corresponding to configUrl.

  3. Let rpOrigin be globalObject’s associated Document's origin.

  4. Let accountId be account’s id.

  5. Let triple be (rpOrigin, idpOrigin, accountId).

  6. Append triple to connected accounts set.

To remove a connection: given accountId, rpOrigin, and idpOrigin, run the following steps. It returns whether the accountId connection was successfully removed.

  1. Let triple be (rpOrigin, idpOrigin, accountId).

  2. If connected accounts set contains triple:

    1. Remove triple from the connected accounts set.

    2. Return true.

  3. Return false.

To remove all connections: given rpOrigin and idpOrigin, run the following steps:

  1. For every (rp, idp, accountId) triple in the connected accounts set:

    1. If rp equals rpOrigin and idp equals idpOrigin, remove triple from the connected accounts set.

2.3. The IdentityCredential Interface

This specification introduces a new type of Credential, called an IdentityCredential:

dictionary IdentityCredentialDisconnectOptions : IdentityProviderConfig {
  required USVString accountHint;
};

[Exposed=Window, SecureContext]
interface IdentityCredential : Credential {
  static Promise<undefined> disconnect(optional IdentityCredentialDisconnectOptions options = {});
  readonly attribute USVString? token;
  readonly attribute boolean isAutoSelected;
};
id

The id's attribute getter returns the empty string.

token

The token's attribute getter returns the value it is set to. It represents the minted token provided by the IDP.

isAutoSelected

isAutoSelected's attribute getter returns the value it is set to. It represents whether the user’s identity credential was automatically selected when going through the UI flow which resulted in this IdentityCredential.

[[type]]

The IdentityCredential's [[type]]'s value is "identity".

[[discovery]]

The IdentityCredential's [[discovery]]'s value is remote.

The main entrypoint in this specification is through the entrypoints exposed by the Credential Management API.

2.3.1. The disconnect method

When the static disconnect method is invoked, given an IdentityCredentialDisconnectOptions options, perform the following steps:

  1. Let globalObject be the current global object.

  2. Let document be globalObject’s associated Document.

  3. If document is not allowed to use the identity-credentials-get policy-controlled feature, throw a "NotAllowedError" DOMException.

  4. Let promise be a new Promise.

  5. In parallel, attempt to disconnect given options, promise, and globalObject.

  6. Return promise.

When asked to attempt to disconnect given an IdentityCredentialDisconnectOptions options, a Promise promise, and a globalObject, perform the following steps:

  1. Assert: these steps are running in parallel.

  2. Let configUrl be the result of running parse url with options’s configURL and globalObject.

  3. If configUrl is failure, reject promise with an "InvalidStateError" DOMException.

  4. Run a Content Security Policy Level 3 check with a connect-src directive on the URL passed as configUrl. If it fails, reject promise with a "NetworkError" DOMException.

  5. If there is another pending disconnect call for this globalObject (e.g., it has not yet thrown an exception or its associated Promise has not yet been resolved), reject promise with a "NetworkError" DOMException.

  6. If configUrl is not a potentially trustworthy origin, reject promise with a "NetworkError" DOMException.

  7. If the user has disabled the FedCM API on the globalObject, reject promise with a "NetworkError" DOMException.

  8. If there does not exist an account account such that connected accounts set contains the result of compute the connected account key given account, options, and globalObject, then reject promise with a "NetworkError" DOMException. This check can be performed by iterating over the connected accounts set or by keeping a separate data structure to make this lookup fast.

  9. Let config be the result of running fetch the config file with provider and globalObject.

  10. If config is failure, reject promise with a "NetworkError" DOMException.

  11. Let disconnectUrl be the result of computing the manifest URL given provider, config.disconnect_endpoint, and globalObject.

  12. If disconnectUrl is failure, reject promise with a "NetworkError" DOMException.

  13. Send a disconnect request with disconnectUrl, options, and globalObject, and let result be the result.

  14. Let idpOrigin be the origin corresponding to configUrl.

  15. Let rpOrigin be globalObject’s associated Document's origin.

  16. If result is failure:

    1. Remove all connections given rpOrigin and idpOrigin.

    2. Reject promise with a "NetworkError" DOMException.

    3. Return.

  17. Let accountId be result (note that it is not failure).

  18. Remove a connection using accountId, rpOrigin, and idpOrigin, and let wasAccountRemoved be the result.

  19. If wasAccountRemoved is false, remove all connections given rpOrigin and idpOrigin.

  20. Resolve promise.

2.3.1.1. Disconnect request

The send a disconnect request algorithm sends a request to disconnect an account that has previously been used for federated login in the RP.

When asked to send a disconnect request, given a URL disconnectUrl, and IdentityCredentialDisconnectOptions options, and a globalObject, perform the following steps. This returns an USVString or failure.

  1. Let requestBody be the result of running urlencoded serializer with a list containing:

    1. ("client_id", options’s clientId)

    2. ("account_hint", options’s accountHint)

  2. Let request be a new request as follows:

    url

    disconnectUrl

    method

    "POST"

    body

    the UTF-8 encode of requestBody

    redirect mode

    "error"

    client

    null

    window

    "no-window"

    service-workers mode

    "none"

    destination

    "webidentity"

    origin

    globalObject’s associated document's origin

    header list

    a list containing a single header with name set to Accept and value set to application/x-www-form-urlencoded

    credentials mode

    "include"

    mode

    "cors"

  3. Let accountId be null.

  4. Fetch request with request and globalObject, and with processResponseConsumeBody set to the following steps given a response response and responseBody:

    1. Let json be the result of extract the JSON fetch response from response and responseBody.

    2. Convert json to a DisconnectedAccount, account.

    3. If one of the previous two steps threw an exception, set accountId to failure and return.

    4. Set accountId to account’s account_id.

  5. Wait for accountId to be set.

  6. Return accountId.

dictionary DisconnectedAccount {
  required USVString account_id;
};

2.3.2. The CredentialRequestOptions

This section defines the dictionaries passed into the JavaScript call:

const credential = await navigator.credentials.get({
  identity: { // IdentityCredentialRequestOptions
    providers: [{  // sequence<IdentityCredentialRequestOptions>
      configURL: "https://idp.example/manifest.json", // IdentityProviderConfig.configURL
      clientId: "123", // IdentityProviderConfig.clientId
      nonce: "nonce" // IdentityProviderConfig.nonce
    }]
  }
});

This specification introduces an extension to the CredentialRequestOptions object:

partial dictionary CredentialRequestOptions {
  IdentityCredentialRequestOptions identity;
};

The IdentityCredentialRequestOptions contains a list of IdentityProviderConfigs that the RP supports and has pre-registered with (i.e. the IDP has given the RP a clientId). The IdentityCredentialRequestOptions also contains a IdentityCredentialRequestOptionsContext which the user agent can use to provide a more meaningful dialog to users.

enum IdentityCredentialRequestOptionsContext {
  "signin",
  "signup",
  "use",
  "continue"
};

dictionary IdentityCredentialRequestOptions {
  required sequence<IdentityProviderRequestOptions> providers;
  IdentityCredentialRequestOptionsContext context = "signin";
};

Each IdentityProviderConfig represents an IDP that the RP supports (e.g. that it has a pre-registration agreement with).

dictionary IdentityProviderConfig {
  required USVString configURL;
  required USVString clientId;
};

dictionary IdentityProviderRequestOptions : IdentityProviderConfig {
  USVString nonce;
  DOMString loginHint;
  DOMString domainHint;
};
configURL

The URL of the configuration file for the identity provider.

clientId

The client_id provided to the RP out of band by the IDP

nonce

A random number of the choice of the RP. It is generally used to associate a client session with a token and to mitigate replay attacks. Therefore, this value should have sufficient entropy such that it would be hard to guess.

loginHint

A string representing the login hint corresponding to an account which the RP wants the user agent to show to the user. If provided, the user agent will not show accounts which do not match this login hint value. It generally matches some attribute from the desired IdentityProviderAccount.

domainHint

A string representing the domain hint corresponding to a domain which the RP is interested in, or "any" if the RP wants any account associated with at least one domain hint. If provided, the user agent will not show accounts which do not match the domain hint value.

2.3.3. The [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method

The [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) algorithm runs in parallel inside Credential Management 1 § 2.5.1 Request a Credential to request credentials and returns an IdentityCredential or an error.

This internal method accepts three arguments:

origin

This argument is the relevant settings object's origin, as determined by the calling get() implementation, i.e., CredentialsContainer's Request a Credential abstract operation.

options

This argument is a CredentialRequestOptions object whose identity member exists.

sameOriginWithAncestors

This argument is a Boolean value which is true if and only if the caller’s environment settings object is same-origin with its ancestors. It is false if caller is cross-origin.

Note: Invocation of this internal method indicates that it was allowed by permissions policy, which is evaluated at the Credential Management Level 1 level. See § 4 Permissions Policy Integration. As such, sameOriginWithAncestors is unused.

The options.signal is used as an abort signal for the requests.

When the IdentityCredential's [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) algorithm is invoked, the user agent MUST execute the following steps. This returns an IdentityCredential (or throws an error to the caller).

  1. Assert: These steps are running in parallel.

  2. If the size of options["identity"]["providers"] is not equal to 1, queue a global task on the DOM manipulation task source given globalObject to throw a new "NetworkError" DOMException

    Note: The globalObject is not currently passed onto the [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) algorithm. See issue.

    Support choosing accounts from multiple IDPs, as described here.

  3. The user agent can decide when to continue with the next steps.

    Note: For example, user agents may show an identity provider selector before making network requests, or provide a button in the URL bar and wait for user input before continuing.

  4. Let provider be options["identity"]["providers"][0].

  5. Let credential be the result of running create an IdentityCredential with provider, options, and globalObject.

  6. If credential is a pair:

    1. Let throwImmediately be the value of the second element of the pair.

    2. The user agent SHOULD wait a random amount of time before the next step if all of the following conditions hold:

      • throwImmediately is false

      • The promise rejection delay was not disabled by user agent automation

      • The user agent has not implemented another way to prevent exposing to the RP whether the user has an account logged in to the RP

      Note: The intention here is as follows. If the the promise was resolved immediately, then an RP could infer that no dialog was shown because the promise was resolved quickly, after just the network delay. A shown dialog implies that the user is logged in to one or more accounts of the IDP. To prevent this information leakage, especially without user confirmation, this delay is specified. However, UAs may have different UI approaches here and prevent it in a different way.

    3. Queue a global task on the DOM manipulation task source to throw a new "NetworkError" DOMException.

  7. Otherwise, return credential.

2.3.4. Create an IdentityCredential

The create an IdentityCredential algorithm invokes the various FedCM fetches, shows the user agent UI, and creates the IdentityCredential that is then returned to the RP.

To create an IdentityCredential given an IdentityProviderRequestOptions provider, a CredentialRequestOptions options, and a globalObject, run the following steps. This returns an IdentityCredential or a pair (failure, bool), where the bool indicates whether to skip delaying the exception thrown.

  1. Assert: These steps are running in parallel.

  2. Let loginStatus be the result of get the login status with the origin of provider’s configURL.

  3. If loginStatus is unknown, a user agent MAY set it to logged-out.

  4. If loginStatus is logged-out, the user agent MUST do one of the following:

    • Return (failure, false).

    • Prompt the user whether to continue. If the user continues, the user agent SHOULD set loginStatus to unknown. This MAY include an affordance to show an IDP login dialog.

      • If the user cancels this dialog, return (failure, true).

      • If the user triggers this affordance:

        1. Let config be the result of running fetch the config file with provider and globalObject.

        2. If config is failure, return (failure, true).

        3. Show an IDP login dialog with config and provider.

        4. If that algorithm returns failure, return (failure, true).

    We should perhaps provide a way to let the RP request that the second option is provided, possibly gated on a user gesture. See this issue for discussion.

  5. Let requiresUserMediation be provider’s configURL's origin's requires user mediation.

  6. Let mediation be options’s mediation.

  7. If requiresUserMediation is true and mediation is "silent", return (failure, true).

  8. Let config be the result of running fetch the config file with provider and globalObject.

  9. If config is failure, return (failure, false).

  10. Fetch accounts step: Let accountsList be the result of fetch the accounts with config, provider, and globalObject.

  11. If accountsList is failure, or the size of accountsList is 0:

    1. Set the login status for the origin of the configURL to logged-out. A user agent may decide to skip this step if no credentials were sent to server.

      Note: For example, if the fetch failed due to a DNS error, no credentials were sent and therefore the IDP did not learn the user’s identity. In this situation, we do not know whether the user is signed in or not and so we may not want to reset the status.

    2. Mismatch dialog step: If loginStatus is logged-in, show a dialog to the user. The contents of this dialog are defined by the user agent. This dialog SHOULD provide an affordance for the user to trigger the show an IDP login dialog algorithm with config and provider; this dialog is the confirm IDP login dialog.

      Note: This situation happens when the browser expects the user to be signed in, but the accounts fetch indicated that the user is signed out.

      Note: This dialog ensures that silent tracking of the user is impossible by always showing UI of some kind when credentials were sent to the server.

      1. Wait until one of the following occurs:

        • If the user closes the dialog, return (failure, true).

        • If the show an IDP login dialog algorithm was triggered:

          1. Let result be the result of that algorithm.

          2. If result is failure, return (failure, true). The user agent MAY show a dialog to the user before or after returning failure indicating this failure.

          3. Otherwise, go back to the fetch accounts step.

  12. Assert: accountsList is not failure and the size of accountsList is not 0.

  13. Set the login status for the origin of the configURL to logged-in.

  14. If provider’s loginHint is not empty:

    1. For every account in accountList, remove account from accountList if account’s login_hints does not contain provider’s loginHint.

    2. If accountList is now empty, go to the mismatch dialog step.

  15. If provider’s domainHint is not empty:

    1. For every account in accountList:

      1. If domainHint is "any":

        1. If account’s domain_hints is empty, remove account from accountList.

      2. Otherwise, remove account from accountList if account’s domain_hints does not contain provider’s domainHint.

    2. If accountList is now empty, go to the mismatch dialog step.

  16. For each acc in accountsList:

    1. If acc["picture"] is present, fetch the account picture with acc and globalObject.

    Note: The user agent may choose to show UI which does not initially require fetching the account pictures. In these cases, the user agent may delay these fetches until they are needed. Because errors from these fetches are ignored, they can happen in any order.

  17. Let registeredAccount, numRegisteredAccounts be null and 0, respectively.

  18. Let account be null.

  19. For each acc in accountsList:

    1. If acc is eligible for auto reauthentication given provider, and globalObject, set registeredAccount to acc and increase numRegisteredAccounts by 1.

  20. Let permission, disclosureTextShown, and isAutoSelected be set to false.

  21. If mediation is not "required", requiresUserMediation is false, and numRegisteredAccounts is equal to 1:

    1. Set account to registeredAccount and permission to true. When doing this, the user agent MAY show some UI to the user indicating that they are being auto-reauthenticated.

    2. Set isAutoSelected to true.

  22. Otherwise, if mediation is "silent", return (failure, true).

  23. Otherwise, if accountsList’s size is 1:

    1. Set account to accountsList[0].

    2. If compute the connection status of account, provider and globalObject returns connected, show a dialog to request user permission to sign in via account, and set the result in permission. The user agent MAY use options’s context to customize the dialog.

    3. Otherwise, let permission be the result of running request permission to sign-up algorithm with account, config, provider, and globalObject. Also set disclosureTextShown to true.

  24. Otherwise:

    1. Set account to the result of running the select an account from the accountsList.

    2. If account is failure, return (failure, true).

    3. If compute the connection status of account, provider and globalObject is connected, set permission to true.

    4. Otherwise:

      1. Let permission be the result of running the request permission to sign-up algorithm with account, config, provider, and globalObject.

      2. Set disclosureTextShown to true.

  25. Wait until the user agent's dialogs requesting for user choice or permission to be closed, if any are created in the previous steps.

  26. Assert: account is not null.

  27. If permission is false, then return (failure, true).

  28. Let credential be the result of running the fetch an identity assertion algorithm with account’s id, disclosureTextShown, isAutoSelected, provider, config, and globalObject.

  29. Return credential.

2.3.5. Fetch the config file

The fetch the config file algorithm fetches both the well-known file and the config file from the IDP, checks that the config file is mentioned in the well-known file, and returns the config.

To fetch the config file given an IdentityProviderRequestOptions provider and globalObject, run the following steps. This returns an IdentityProviderAPIConfig or failure.

  1. Let configUrl be the result of running parse url with provider’s configURL and globalObject.

  2. If configUrl is failure, return failure.

  3. Run a Content Security Policy Level 3 check with a connect-src directive on the URL passed as configUrl. If it fails, return failure.

  4. If configUrl is not a potentially trustworthy URL, return failure.

  5. Let rootUrl be a new URL.

  6. Set rootUrl’s scheme to configUrl’s scheme.

  7. Set rootUrl’s host to configUrl’s host's registrable domain.

  8. Set rootUrl’s path to the list «".well-known", "web-identity"».

  9. Let config, configInWellKnown both be null.

  10. Let rpOrigin be globalObject’s associated Document's origin.

  11. If rpOrigin is not an opaque origin, and rootUrl’s host is equal to rpOrigin’s registrable domain, and rootUrl’s scheme is equal to rpOrigin’s scheme, set configInWellKnown to true.

    Note: Because domain cookies are valid across an entire site, there is no privacy benefit from doing the well-known check if the RP and IDP are in the same site.

  12. Otherwise:

    1. Let wellKnownRequest be a new request as follows:

      URL

      rootUrl

      client

      null

      window

      "no-window"

      service-workers mode

      "none"

      destination

      "webidentity"

      origin

      a unique opaque origin

      header list

      a list containing a single header with name set to Accept and value set to application/json

      referrer policy

      "no-referrer"

      credentials mode

      "omit"

      mode

      "no-cors"

      The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details.

    2. Fetch request with wellKnownRequest and globalObject, and with processResponseConsumeBody set to the following steps given a response response and responseBody:

      1. Let json be the result of extract the JSON fetch response from response and responseBody.

      2. Convert json to an IdentityProviderWellKnown, discovery.

      3. If one of the previous two steps threw an exception, or if the size of discovery["provider_urls"] is greater than 1, set configInWellKnown to false.

        relax the size of the provider_urls array.

      4. Otherwise, set to configInWellKnown to true if discovery["provider_urls"][0] is equal to provider’s configURL, and to false otherwise.

  13. Let configRequest be a new request as follows:

    url

    configUrl

    redirect mode

    "error"

    client

    null

    window

    "no-window"

    service-workers mode

    "none"

    destination

    "webidentity"

    origin

    a unique opaque origin

    header list

    a list containing a single header with name set to Accept and value set to application/json

    referrer policy

    "no-referrer"

    credentials mode

    "omit"

    mode

    "no-cors"

    The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details.

  14. Fetch request with configRequest and globalObject, and with processResponseConsumeBody set to the following steps given a response response and responseBody:

    1. Let json be the result of extract the JSON fetch response from response and responseBody.

    2. Convert json to an IdentityProviderAPIConfig stored in config.

    3. If one of the previous two steps threw an exception, set config to failure.

    4. Set config.login_url to the result of computing the manifest URL with provider, config and globalObject.

    5. If config.login_url is null, return failure.

  15. Wait for both config and configInWellKnown to be set.

  16. If configInWellKnown is true, return config. Otherwise, return failure.

NOTE: a two-tier file system is used in order to prevent the IDP from easily determining the RP that a user is visiting by encoding the information in the config file path. This issue is solved by requiring a well-known file to be on the root of the IDP. The config file itself can be anywhere, but it will not be used if the user agent does not find it in the well-known file. This allows the IDP to keep their actual config files on an arbitary path while allowing the user agent to prevent config file path manipulation to fingerprint (for instance, by including the RP in the path). See § 7.3.1 Manifest Fingerprinting.

dictionary IdentityProviderWellKnown {
  required sequence<USVString> provider_urls;
};

dictionary IdentityProviderIcon {
  required USVString url;
  unsigned long size;
};

dictionary IdentityProviderBranding {
  USVString background_color;
  USVString color;
  sequence<IdentityProviderIcon> icons;
  USVString name;
};

dictionary IdentityProviderAPIConfig {
  required USVString accounts_endpoint;
  required USVString client_metadata_endpoint;
  required USVString id_assertion_endpoint;
  required USVString login_url;
  USVString disconnect_endpoint;
  IdentityProviderBranding branding;
};

2.3.6. Fetch the accounts

The fetch the accounts algorithm fetches the accounts endpoint to determine the list of IDP accounts that the user is signed in to, so that the user agent can later show the FedCM UI to the user.

To fetch the accounts given an IdentityProviderAPIConfig config, an IdentityProviderRequestOptions provider, and globalObject, run the following steps. This returns an IdentityProviderAccountList.

  1. Let accountsUrl be the result of computing the manifest URL given provider, config["accounts_endpoint"], and globalObject.

  2. If accountsUrl is failure, return an empty list.

  3. Let request be a new request as follows:

    url

    accountsUrl

    redirect mode

    "error"

    client

    null

    window

    "no-window"

    service-workers mode

    "none"

    destination

    "webidentity"

    origin

    a unique opaque origin

    header list

    a list containing a single header with name set to Accept and value set to application/json

    referrer policy

    "no-referrer"

    credentials mode

    "include"

    mode

    "no-cors"

    The credentialed fetch in this algorithm can lead to a timing attack that leaks the user’s identities before the user grants permission. This is an active area of investigation that is being explored here.

    The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details.

  4. Let accountsList be null.

  5. Fetch request with request and globalObject, and with processResponseConsumeBody set to the following steps given a response response and responseBody:

    1. Let json be the result of extract the JSON fetch response from response and responseBody.

    2. Convert json to an IdentityProviderAccountList, and store the result in accountsList.

    3. If one of the previous two steps threw an exception, set accountsList to failure.

    the accounts list returned here should be validated for repeated ids, as described here.

  6. Wait for accountsList to be set.

  7. Return accountsList.

dictionary IdentityProviderAccount {
  required USVString id;
  required USVString name;
  required USVString email;
  USVString given_name;
  USVString picture;
  sequence<USVString> approved_clients;
  sequence<DOMString> login_hints;
  sequence<DOMString> domain_hints;
};
dictionary IdentityProviderAccountList {
  sequence<IdentityProviderAccount> accounts;
};
To fetch the account picture given an IdentityProviderAccount account and a globalObject, run the following steps:

  1. Let pictureUrl be the result of running parse url with account["picture"] and globalObject.

  2. If pictureUrl is failure, abort these steps. The user agent may use a placeholder image.

  3. Let pictureRequest be a new request as follows:

    url

    pictureUrl

    client

    null

    window

    "no-window"

    service-workers mode

    "none"

    destination

    "image"

    origin

    a unique opaque origin

    referrer policy

    "no-referrer"

    credentials mode

    "omit"

    mode

    "no-cors"

    The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details.

  4. Fetch request with pictureRequest and globalObject, and with processResponseConsumeBody set to the following steps given a response and a responseBody:

    1. If responseBody is null or failure, the user agent may choose an arbitrary placeholder image and associate it with the account.

    2. Otherwise, decode responseBody into an image, and associate it with account if successful. This allows the user agent to use the decoded image in a dialog displaying account.

2.3.7. Fetch an identity assertion

The fetch an identity assertion algorithm is invoked after the user has granted permission to use FedCM with a specific IDP account. It fetches the identity assertion endpoint to obtain the token that will be provided to the RP.

To fetch an identity assertion given a USVString accountId, a boolean disclosureTextShown, a boolean isAutoSelected, an IdentityProviderRequestOptions provider, an IdentityProviderAPIConfig config, and globalObject, run the following steps. This returns an IdentityCredential or failure.

  1. Let tokenUrl be the result of computing the manifest URL given provider, config["id_assertion_endpoint"], and globalObject.

  2. If tokenUrl is failure, return failure.

  3. Let requestBody be the result of running urlencoded serializer with a list containing:

    1. ("client_id", provider’s clientId)

    2. ("nonce", provider’s nonce)

    3. ("account_id", accountId)

    4. ("disclosure_text_shown", disclosureTextShown)

    5. ("is_auto_selected", isAutoSelected)

  4. Let request be a new request as follows:

    url

    tokenUrl

    method

    "POST"

    body

    the UTF-8 encode of requestBody

    redirect mode

    "error"

    client

    null

    window

    "no-window"

    service-workers mode

    "none"

    destination

    "webidentity"

    origin

    globalObject’s associated document's origin

    header list

    a list containing a single header with name set to Accept and value set to application/x-www-form-urlencoded

    credentials mode

    "include"

    mode

    "cors"

  5. Let credential be null.

  6. Fetch request with request and globalObject, and with processResponseConsumeBody set to the following steps given a response response and responseBody:

    1. Let json be the result of extract the JSON fetch response from response and responseBody.

    2. Convert json to an IdentityProviderToken, token.

    3. If one of the previous two steps threw an exception, set credential to failure and return.

    4. Let credential be a new IdentityCredential given globalObject’s realm.

    5. Set credential’s token to token.

    6. Set credential’s isAutoSelected to isAutoSelected.

  7. Wait for credential to be set.

  8. Return credential.

dictionary IdentityProviderToken {
  required USVString token;
};

2.3.8. Request permission to sign-up

To select an account given an accountsList, run the following steps. This returns an IdentityProviderAccount or failure.

  1. Assert accountsList’s size is greater than 1.

  2. Display an account chooser displaying the options from accountsList.

  3. Let account be the IdentityProviderAccount of the account that the user manually selects from the accounts chooser, or failure if no account is selected.

  4. Return account.

The request permission to sign-up algorithm fetches the client metadata endpoint of the RP, waits for the user to grant permission to use the given account, and returns whether the user granted permission or not.

To request permission to sign-up the user with a given an IdentityProviderAccount account, an IdentityProviderAPIConfig config, an IdentityProviderRequestOptions provider, and a globalObject, run the following steps. This returns a boolean.

  1. Assert: These steps are running in parallel.

  2. Let metadata be the result of running fetch the client metadata with config, provider, and globalObject.

  3. Prompt the user to gather explicit intent to create an account. The user agent MAY use the IdentityProviderBranding to inform the style choices of its UI. Additionally:

    1. If metadata is not failure, metadata["privacy_policy_url"] is defined and the provider’s clientId is not in the list of account["approved_clients"], then the user agent MUST display the metadata["privacy_policy_url"] link.

    2. If metadata is not failure, metadata["terms_of_service_url"] is defined, and the provider’s clientId is not in the list of account["approved_clients"], then the user agent MUST display the metadata["terms_of_service_url"] link.

    3. The user agent MAY use the context to customize the dialog shown.

  4. If the user does not grant permission, return false.

  5. Create a connection between the RP and the IdP account with provider, account, and globalObject.

  6. Return true.

To fetch the client metadata given an IdentityProviderAPIConfig config and an IdentityProviderRequestOptions provider, run the following steps. This returns an IdentityProviderClientMetadata or failure.

  1. Let clientMetadataUrl be the result of computing the manifest URL given provider, config["client_metadata_endpoint"], and globalObject.

  2. If clientMetadataUrl is failure, return failure.

  3. Let request be a new request as follows:

    url

    clientMetadataUrl

    redirect mode

    "error"

    client

    null

    window

    "no-window"

    service-workers mode

    "none"

    destination

    "webidentity"

    origin

    globalObject’s associated document's origin

    header list

    a list containing a single header with name set to Accept and value set to application/json

    credentials mode

    "omit"

    mode

    "no-cors"

    The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details.

  4. Let metadata be null.

  5. Fetch request with request and globalObject, and with processResponseConsumeBody set to the following steps given a response response and responseBody:

    1. Let json be the result of extract the JSON fetch response from response and responseBody.

    2. Convert json to an IdentityProviderClientMetadata, and store the result in metadata.

    3. If one of the previous two steps threw an exception, set metadata to failure.

  6. Wait until metadata is set.

  7. Return metadata.

dictionary IdentityProviderClientMetadata {
  USVString privacy_policy_url;
  USVString terms_of_service_url;
};

2.3.9. Helper algorithms

The following helper algorithms are used during the FedCM flow.

To parse url given a USVString stringUrl, a globalObject, and an optional baseUrl (default null), run the following steps. This returns a URL or failure.

  1. Let configUrl be null.

  2. Queue a global task on the DOM manipulation task source given globalObject to set configUrl to the result of running url parser with stringUrl and baseUrl.

    Note: a task is queued since the url parser needs to be run within a task, not in parallel.

  3. Wait for configUrl to be set.

  4. Return configUrl.

To fetch request given a request request, globalObject, and an algorithm processResponseConsumeBody, run the following steps:

  1. Queue a global task on the network task source given globalObject to:

    1. Fetch request with processResponseConsumeBody set to processResponseConsumeBody.

Note: a task is queued since the fetch needs to be run within a task, not in parallel.

When computing the manifest URL given an IdentityProviderRequestOptions provider, a string manifestString, and globalObject, perform the following steps. This returns a URL or failure.

  1. Let configUrl be the result of running parse url with provider’s configURL and globalObject.

  2. Let manifestUrl be the result of running parse url given manifestString (the relative URL), globalObject, and configUrl (the base URL).

  3. Wait until manifestUrl is set.

    Note: This means that passing the manifest string as either an absolute or relative URL is allowed.

  4. If manifestUrl is failure, return failure.

  5. If manifestUrl is not same origin with configUrl, return failure.

  6. If manifestUrl is not a potentially trustworthy URL, return failure.

  7. Return manifestUrl.

To extract the JSON fetch response given a response response and a responseBody, run the following steps. This returns an ordered map.

  1. Assert: These steps are running on the networking task source.

  2. If response is a network error or its status is not an ok status, throw a new "NetworkError" DOMException.

  3. Let mimeType be the result of extracting a MIME TYPE from response’s header list.

  4. If mimeType is failure or is not a JSON MIME Type, throw a new "NetworkError" DOMException.

  5. Let json be the result of parse JSON bytes to a JavaScript value passing responseBody.

  6. If json is a parsing exception, throw a new "NetworkError" DOMException.

  7. Return json.

To show an IDP login dialog given an IdentityProviderAPIConfig config, an IdentityProviderConfig provider, and a globalObject, run the following steps. This returns success or failure.

  1. Assert: these steps are running in parallel.

  2. Let loginUrl be null.

  3. Queue a global task on the DOM manipulation task source given globalObject to set loginUrl to the result of running url parser with config.login_url.

  4. Wait until loginUrl is not null.

  5. Assert: loginUrl is not failure (the user agent has previously checked that config.login_url is a valid URL).

  6. Let queryList be a new list.

  7. If provider’s loginHint is not empty, append ("login_hint", loginHint) to queryList.

  8. If provider’s domainHint is not empty, append ("domain_hint", domainHint) to queryList.

  9. If queryList is not empty:

    1. Let queryParameters be the result of the urlencoded serializer with queryList.

    2. If loginUrl’s query is not null or empty, prepend "&" to queryParameters.

    3. Append queryParameters to loginUrl’s query.

  10. Create a fresh top-level traversable with loginUrl.

  11. The user agent MAY set up browsing context features or otherwise affect the presentation of this traversable in an implementation-defined way.

  12. Wait for one of the following conditions:

    • The user closes the browsing context: return failure.

    • IdentityProvider.close is called in the context of this new traversable:

      1. Close the traversable.

      2. Let loginStatus be the result of get the login status with the origin of the login_url.

        Note: The IDP login flow may set this value to logged-in using either the JavaScript or HTTP header API during the login flow. It is also possible that this change happened in a different browsing context.

      3. If loginStatus is logged-in, return success.

      4. Otherwise, return failure.

2.4. The IdentityProvider Interface

This specification introduces the IdentityUserInfo dictionary as well as the IdentityProvider interface:

dictionary IdentityUserInfo {
  USVString email;
  USVString name;
  USVString givenName;
  USVString picture;
};

[Exposed=Window, SecureContext] interface IdentityProvider {
    static undefined close();
    static Promise<sequence<IdentityUserInfo>> getUserInfo(IdentityProviderConfig config);
};

Decide whether IdentityProvider is the correct location for the getUserInfo() method.

A close function is provided to signal to the browser that the login flow is finished. The reason for this function in addition to the header is that even when the user is already logged in, the login flow may not be finished yet; for example, an IDP may want to prompt the user to verify their phone number. To allow for such flows, the IDP must call close when the flow is fully done.

See the show an IDP login dialog algorithm for more details.

An IdentityUserInfo represents user account information from a user. This information is exposed to the IDP once the user has already used the FedCM API to login in the RP. That is, it is exposed when there exists an account account such that the connected accounts set contains the triple (RP, IDP, account). The information matches what is received from the accounts endpoint. The IDP can obtain this information by invoking the getUserInfo() static method from an iframe matching the origin of its configURL.

const userInfo = await IdentityProvider.getUserInfo({
    configUrl: "https://idp.example/fedcm.json",
    clientId: "client1234"
});

if (userInfo.length > 0) {
  // It’s up to the IDP regarding how to display the returned accounts.
  const name = userInfo[0].name;
  const givenName = userInfo[0].givenName;
  const displayName = givenName ? givenName : name;
  const picture = userInfo[0].picture;
  const email = userInfo[0].email;
}
When invoking the getUserInfo() method given an IdentityProviderConfig provider, perform the following steps:

  1. Let globalObject be the current global object.

  2. Let document be globalObject’s associated Document.

  3. If document is not allowed to use the identity-credentials-get policy-controlled feature, throw a "NotAllowedError" DOMException.

  4. If there does not exist an account account such that connected accounts set contains the result of compute the connected account key given account, provider, and globalObject, then reject promise with a "NetworkError" DOMException. This check can be performed by iterating over the connected accounts set or by keeping a separate data structure to make this lookup fast.

  5. Let configUrl be the result of running parse url with provider’s configURL and globalObject.

  6. If configUrl is failure, throw an "InvalidStateError" DOMException.

  7. If document’s origin is not same origin as configUrl’s origin, throw an "InvalidStateError" DOMException.

  8. Run a Content Security Policy Level 3 check with a connect-src directive on the URL passed as configUrl. If it fails, throw a new "NetworkError" DOMException.

  9. If globalObject’s navigable is a top-level traversable, throw a new "NetworkError" DOMException.

  10. If the user has disabled the FedCM API on the globalObject’s navigable's top-level traversable, throw a new "NetworkError" DOMException.

  11. Let promise be a new Promise.

  12. Perform the following steps in parallel:

    1. Let config be the result of running fetch the config file with provider and globalObject.

    2. If config is failure, reject promise with a new "NetworkError" DOMException.

    3. Let accountsList be the result of fetch the accounts with config, provider, and globalObject.

    4. Let hasAccountEligibleForAutoReauthentication be false.

    5. For each account in accountsList:

      1. If account["approved_clients"] is not empty and it does not contain provider’s clientId, continue.

        Note: this allows the IDP to override whether an account is a returning account. This could be useful for instance in cases where the user has disconnected the account out of band.

      2. If account is eligible for auto reauthentication given provider and globalObject, set hasAccountEligibleForAutoReauthentication to true.

    6. If hasAccountEligibleForAutoReauthentication is false, reject promise with a new "NetworkError" DOMException.

    7. Let userInfoList be a new list.

    8. For each account in accountsList:

      1. Append an IdentityUserInfo to userInfoList with the following values:

        email

        account["email"]

        name

        account["name"]

        givenName

        account["given_name"]

        picture

        account["picture"]

    9. Resolve a new Promise with userInfoList.

3. Identity Provider HTTP API

This section is non-normative.

The IDP exposes a series of HTTP endpoints:

  1. § 3.1 The Well-Known File that points to a Manifest

  2. A § 3.2 The config file in an agreed upon location that points to

  3. An § 3.3 Accounts endpoint endpoint

  4. A § 3.4 Client Metadata endpoint

  5. An § 3.5 Identity assertion endpoint endpoint

  6. An § 3.6 Disconnect endpoint endpoint if it supports disconnect.

The FedCM API introduces the ability for a site to ask the browser to execute a few different network requests. It is important for the browser to execute these in such a way that it does not allow the user to be tracked (by an attacker impersonating an IDP) on to the site using FedCM. The following table has information about the network requests performed:

Endpoint cookies client_id origin
manifests no no no
accounts_endpoint yes no no
client_metadata_endpoint no yes yes
id_assertion_endpoint yes yes yes
disconnect_endpoint yes yes yes

3.1. The Well-Known File

NOTE: The browser uses the well-known file to prevent § 7.3.1 Manifest Fingerprinting.

The IDP exposes a well-known file in a pre-defined location, specifically at the "web-identity" file at the IDPs's path ".well-known".

The well-known file is fetched in the fetch the config file algorithm:

(a) without cookies, (b) with the Sec-Fetch-Dest header set to webidentity, and (c) without revealing the RP in the Origin or Referer headers.

For example:

GET /.well-known/web-identity HTTP/1.1
Host: idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

The file is parsed expecting a IdentityProviderWellKnown JSON object.

The IdentityProviderWellKnown JSON object has the following semantics:

provider_urls (required), of type sequence<USVString>

A list of URLs that points to valid § 3.2 The config files.

3.2. The config file

The config file serves as a discovery device to other endpoints provided by the IDP.

The config file is fetched in the fetch the config file algorithm:

(a) without cookies, (b) with the Sec-Fetch-Dest header set to webidentity, (c) without revealing the RP in the Origin or Referer headers, and (d) without following HTTP redirects.

For example:

GET /config.json HTTP/1.1
Host: idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

The response body must be a JSON object that can be converted to an IdentityProviderAPIConfig without an exception.

The IdentityProviderAPIConfig object’s members have the following semantics:

accounts_endpoint, of type USVString

A URL that points to an HTTP API that complies with the § 3.3 Accounts endpoint API.

client_metadata_endpoint, of type USVString

A URL that points to an HTTP API that complies with the § 3.4 Client Metadata API.

id_assertion_endpoint, of type USVString

A URL that points to an HTTP API that complies with the § 3.5 Identity assertion endpoint API.

disconnect_endpoint, of type USVString

A URL that points to an HTTP API that complies with the § 3.6 Disconnect endpoint API.

branding, of type IdentityProviderBranding

A set of IdentityProviderBranding options.

The IdentityProviderBranding enables an IDP to express their branding preferences, which may be used by user agents to customize the permission prompt.

Note: The branding preferences are deliberately designed to be high level / abstract (rather than opinionated about a specific UI structure), to enable different user agents to offer different UI experiences and for them to evolve independently over time.

Its members have the following semantics:

background_color, of type USVString

Background color for IDP-branded widgets such as buttons.

color, of type USVString

color for text on IDP branded widgets.

icons, of type sequence<IdentityProviderIcon>

A list of IdentityProviderIcon objects.

name, of type USVString

A user-recognizable name for the IDP.

Note: The branding preferences are deliberately designed to be high level / abstract (rather than opinionated about a specific UI structure), to enable different user agents to offer different UI experiences and for them to evolve independently over time.

The IdentityProviderIcon has members with the following semantics:

url, of type USVString

The url pointing to the icon image, which must be square and single resolution (not a multi-resolution .ico). The icon needs to comply with the maskable specification.

size, of type unsigned long

The width/height of the square icon. The size may be omitted if the icon is in a vector graphic format (like SVG).

Note: the user agent reserves a square size for the icons provided by the developer. If the developer provides an icon that is not square, the user agent may choose to not display it at all, trim the icon and show a square portion of it, or even transform it into a square icon and show that.

The color is a subset of CSS <color> syntax, namely <hex-color>s, hsl()s, rgb()s and <named-color>.

For example:

{
  "accounts_endpoint": "/accounts",
  "client_metadata_endpoint": "/metadata",
  "id_assertion_endpoint": "/assertion",
  "disconnect_endpoint": "/disconnect",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }],
    "name": "IDP Example"
  }
}

3.3. Accounts endpoint

The accounts endpoint provides the list of accounts the user has at the IDP.

The accounts endpoint is fetched in the fetch the accounts algorithm:

(a) with IDP cookies, (b) with the Sec-Fetch-Dest header set to webidentity, (c) without revealing the RP in the Origin or Referer headers, and (d) without following HTTP redirects.

For example:

GET /accounts_list HTTP/1.1
Host: idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

The response body must be a JSON object that can be converted to an IdentityProviderAccountList without an exception.

Every IdentityProviderAccount is expected to have members with the following semantics:

id, of type USVString

The account unique identifier.

name, of type USVString

The user’s full name.

email, of type USVString

The user’s email address.

given_name, of type USVString

The user’s given name.

picture, of type USVString

URL for the account’s picture.

approved_clients, of type sequence<USVString>

A list of RPs (that gets matched against the requesting clientId) this account is already registered with. Used in the request permission to sign-up to allow the IDP to control whether to show the Privacy Policy and the Terms of Service.

login_hints, of type sequence<DOMString>

A list of strings which correspond to all of the login hints which match with this account. An RP can use the loginHint to request that only an account matching a given value is shown to the user.

domain_hints, of type sequence<DOMString>

A list of strings which correspond to all of the domain hints which match with this account. An RP can use the domainHint to request that only an account matching a given value or containing some domain hint is shown to the user.

For example:

{
 "accounts": [{
   "id": "1234",
   "given_name": "John",
   "name": "John Doe",
   "email": "[email protected]",
   "picture": "https://idp.example/profile/123",
   "approved_clients": ["123", "456", "789"],
   "login_hints": ["john_doe"],
   "domain_hints": ["idp.example"],
  }, {
   "id": "5678",
   "given_name": "Johnny",
   "name": "Johnny",
   "email": "[email protected]",
   "picture": "https://idp.example/profile/456",
   "approved_clients": ["abc", "def", "ghi"],
   "login_hints": ["[email protected]", "id=5678"],
   "domain_hints": ["idp.example"],
  }]
}

Clarify the IDP API response when the user is not signed in.

3.4. Client Metadata

The client metadata endpoint provides metadata about RPs.

The client metadata endpoint is fetched in the fetch the client metadata algorithm:

(a) without cookies, (b) with the Sec-Fetch-Dest header set to webidentity, (c) with the RP's origin in the Origin header, and (d) without following HTTP redirects.

The user agent also passes the client_id.

For example:

GET /client_medata?client_id=1234 HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

The response body must be a JSON object that can be converted to an IdentityProviderClientMetadata without an exception.

The IdentityProviderClientMetadata object’s members have the following semantics:

privacy_policy_url, of type USVString

A link to the RP's Privacy Policy.

terms_of_service_url, of type USVString

A link to the RP's Terms of Service.

For example:

{
  "privacy_policy_url": "https://rp.example/clientmetadata/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/clientmetadata/terms_of_service.html"
}

3.5. Identity assertion endpoint

The identity assertion endpoint is responsible for minting a new token that contains signed assertions about the user.

The identity assertion endpoint is fetched in the fetch an identity assertion algorithm:

(a) as a POST request, (b) with IDP cookies, (c) with the RP's origin in the Origin header, and (d) with the Sec-Fetch-Dest header set to webidentity, (e) without following HTTP redirects.

It will also contain the following parameters in the request body application/x-www-form-urlencoded:

client_id

The RP's unique identifier from the IDP

nonce

The request nonce

account_id

The account identifier that was selected.

disclosure_text_shown

Whether the user agent has explicitly shown to the user what specific information the IDP intends to share with the RP (e.g. "idp.example will share your name, email... with rp.example"), used by the request permission to sign-up algorithm for new users. It is used as an assurance by the user agent to the IDP that it has indeed shown the terms of service and privacy policy to the user in the cases where it is required to do so.

For example:

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
An IDP MUST check the Origin header to ensure that a malicious RP does not receive an ID token corresponding to another RP. In other words, the IDP MUST check that the Origin header value is represented by the clientId. As the clientId are IDP-specific, the user agent cannot perform this check.

The response body must be a JSON object that can be converted to an IdentityProviderToken without an exception.

Every IdentityProviderToken is expected to have members with the following semantics:

token, of type USVString

The resulting token.

The content of the token is opaque to the user agent and can contain anything that the IDP would like to pass to the RP to facilitate the login. For this reason the RP is expected to be the party responsible for validating the token passed along from the IDP using the appropriate token validation algorithms defined. One example of how this might be done is defined in OIDC Connect Core § IDTokenValidation.

NOTE: For IDPs, it is worth considering how portable accounts are. Portability is left entirely up to IDPs, who can choose between a variety of different mechanisms to accomplish it (e.g. OIDC’s Account Porting).

For example:

{
  "token" : "eyJC...J9.eyJzdWTE2...MjM5MDIyfQ.SflV_adQssw....5c"
}

3.6. Disconnect endpoint

The disconnect endpoint is responsible for disconnecting a previously made federated login connection between an RP and an IDP account, and returning the account’s id so that the user agent can remove it from the connected accounts set.

The disconnect endpoint is fetched when invoking the disconnect method:

(a) as a POST request, (b) with IDP cookies, (c) with the RP's origin in the Origin header, (d) with the Sec-Fetch-Dest header set to webidentity, (e) without following HTTP redirects, and (f) in "cors" mode.

It will also contain the following in the request body application/x-www-form-urlencoded:

client_id

The RP's unique identifier from the IDP

account_hint

An account hint for the IDP account being disconnected from the RP.

For example:

POST /fedcm_disconnect_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
client_id=client1234&account_hint=hint12

If the disconnection is unsuccessful, the IDP may respond with an error. If it is successful, the response body must be a JSON object that can be converted to an DisconnectedAccount without an exception.

account_id, of type USVString

The id of the account that was successfully disconnected.

The IDP must return the account_id since it may be different from the account_hint, and the ID is the one which allows the user agent to disconnect the account from the connected accounts set. If the IDP returns an error or the user agent does not find the account with the ID provided by the IDP, then all accounts associated with the relevant (RP, IDP) are removed from the connected accounts set.

4. Permissions Policy Integration

FedCM defines a policy-controlled feature identified by the string "identity-credentials-get". Its default allowlist is "self".

A Document’s permissions policy determines whether any content in that document is allowed to obtain a credential object using the Browser API. Attempting to invoke navigator.credentials.get({identity:..., ...}) in documents that are not allowed to use the identity-credentials-get feature will result in a promise rejected with a "NotAllowedError" DOMException.

This restriction can be controlled using the mechanisms described in Permissions Policy.

Note: Algorithms specified in Credential Management Level 1 perform the actual permissions policy evaluation. This is because such policy evaluation needs to occur when there is access to the current settings object. The internal methods modified by this specification do not have such access since they are invoked in parallel by CredentialsContainer's Request a Credential abstract operation.

5. User Agent Automation

For the purposes of user agent automation and website testing, this document defines the below WebDriver extension commands to interact with any active FedCM dialogs.

5.1. Extension capability

In order to advertise the availability of the extension commands defined below, a new extension capability is defined.

Capability Key Value Type Description
Federated Credential Management Support "fedcm:accounts" boolean Indicates whether the endpoint node supports all Federated Credential Management commands.

When validating capabilities, the extension-specific substeps to validate "fedcm:accounts" with value are the following:

  1. If value is not a boolean return a WebDriver Error with error code invalid argument.

  2. Otherwise, let deserialized be set to value.

When matching capabilities, the extension-specific steps to match "fedcm:accounts" with value are the following:

  1. If value is true and the endpoint node does not support any of the Federated Credential Management commands, the match is unsuccessful.

  2. Otherwise, the match is successful.

5.2. Cancel dialog

HTTP Method URI Template
POST /session/{session id}/fedcm/canceldialog

The remote end steps are:

  1. If no FedCM dialog is currently open, return a WebDriver error with error code no such alert.

  2. Close the dialog and continue the create an IdentityCredential algorithm as if the user had canceled the dialog without choosing an account.

  3. Return success with data null.

5.3. Select account

HTTP Method URI Template
POST /session/{session id}/fedcm/selectaccount

The remote end steps are:

  1. If parameters is not a JSON Object, return a WebDriver error with error code invalid argument.

  2. If no FedCM dialog is currently open, return a WebDriver error with error code no such alert.

  3. Let accountIndex be the result of getting a property named "accountIndex" from parameters.

  4. If accountIndex is undefined or is less than 0 or greater than or equal to the number of accounts that the user can choose from in the current flow, return a WebDriver error with error code invalid argument.

  5. Close the dialog and continue the create an IdentityCredential algorithm as if the user had selected the account indicated by accountIndex and granted permission to sign-up, if applicable.

  6. Return success with data null.

5.4. Click dialog button

HTTP Method URI Template
POST /session/{session id}/fedcm/clickdialogbutton

The remote end steps are:

  1. If parameters is not a JSON Object, return a WebDriver error with error code invalid argument.

  2. Let dialogButton be the result of getting a property named "dialogButton" from parameters.

  3. If dialogButton is not a string that is "ConfirmIdpLoginContinue", return a WebDriver error with error code invalid argument.

  4. If no FedCM dialog is currently open or the dialog is not a confirm IDP login dialog, return a WebDriver error with error code no such alert.

  5. Act as if the user had clicked the "continue" button in the confirm IDP login dialog and initiate the login flow.

  6. Return success with data null.

5.5. Account list

HTTP Method URI Template
GET /session/{session id}/fedcm/accountlist

The remote end steps are:

  1. If no FedCM dialog is currently open, return a WebDriver error with error code no such alert.

  2. Let accounts be the list of accounts that the user can or could choose from in the current flow.

  3. Let list be an empty list.

  4. For each account in accounts:

    1. Let accountState be the result of running the compute the connection status algorithm given account and the IdentityProviderRequestOptions of the IDP account belongs to

    2. Append a dictionary to list with the following properties:

      1. accountId set to the account’s id

      2. email set to the account’s email

      3. name set to the account’s name

      4. givenName set to the account’s given_name, if present

      5. pictureUrl set to the account’s picture, if present

      6. idpConfigUrl set to the configURL of the IDP this account belongs to

      7. loginState to "SignUp" if accountState is disconnected and "SignIn" otherwise

      8. termsOfServiceUrl to the terms_of_service_url if one was provided and the loginState is "SignUp", otherwise undefined

      9. privacyPolicyUrl to the privacy_policy_url if one was provided and the loginState is "SignUp", otherwise undefined

  5. Return success with data list.

5.6. Get title

HTTP Method URI Template
GET /session/{session id}/fedcm/gettitle

Note: This command lets automation verify that the context api was applied properly

The remote end steps are:

  1. If no FedCM dialog is currently open, return a WebDriver error with error code no such alert.

  2. Let data be a dictionary with an object with properties as follows:

    1. title set to the title of the open dialog

    2. subtitle set to the subtitle of the open dialog, if there is one

  3. Return success with data data.

5.7. Get dialog type

HTTP Method URI Template
GET /session/{session id}/fedcm/getdialogtype

The remote end steps are:

  1. If no FedCM dialog is currently open, return a WebDriver error with error code no such alert.

  2. Let type be a string that is "AutoReauthn" if the user is being auto-reauthenticated, or "AccountChooser" if the dialog is an account chooser, or "ConfirmIdpLogin" if the dialog is a confirm IDP login dialog.

  3. Return success with data type.

5.8. Set delay enabled

HTTP Method URI Template
POST /session/{session id}/fedcm/setdelayenabled

The remote end steps are:

  1. If parameters is not a JSON Object, return a WebDriver error with error code invalid argument.

  2. Let enabled be the result of getting a property named "enabled" from parameters.

  3. If enabled is undefined or is not a boolean, return a WebDriver error with error code invalid argument.

  4. If enabled is false, disables the promise rejection delay; otherwise, re-enables it.

  5. Return success with data null.

5.9. Reset cooldown

HTTP Method URI Template
POST /session/{session id}/fedcm/resetcooldown

The remote end steps are:

  1. If the user agent uses a cooldown delay, which disables the API for an amount of time after the user dismissed the dialog, then this command resets that cooldown such that the next FedCM call can succeed again.

  2. Return success with data null.

6. Security

This section provides a few of the security considerations for the FedCM API. Note that there is a separate section for § 7 Privacy considerations.

6.1. Content Security Policy

The first fetches triggered by the FedCM API are the manifest list, which is public, and the config file. Imagine a malicious script included by (and running as) the RP attempting to execute the FedCM API calls to a malicious IDP, one which is not trusted by the RP. If the call is successful, this would introduce browser UI on the RP with sign in options into a malicious IDP. This maliciousIDP could then attempt to trick the user. The protection against this attack is the Content Security Policy Level 3 check, which would fail because the origin of the manifest of the malicious IDP would not be an origin included in the allowlist specified by the Content Security Policy Level 3 of the RP, hence preventing the undesired FedCM UI from being shown. Since any subsequent fetches are same origin with respect to the config file or at least dependent on the contents of the config file, they do not require additional checks.

The non-same-origin fetches include, for example, the brand icon. The user agent does not perform a Content Security Policy Level 3 check on these because they are directly specified from the manifest. In addition, the rendering of this image is performed by the user agent, and as such this image cannot affect the RP site nor can they be inspected by the RP in any way.

6.2. Sec-Fetch-Dest Header

The FedCM API introduces several non-static endpoints on the IDP, so these need to be protected from XSS attacks. In order to do so, the FedCM API introduces a new value for the Sec-Fetch-Dest header, a forbidden request-header. The requests initiated by the FedCM API have a webidentity value for this header. The value cannot be set by random websites, so the IDP can be confident that the request was originated by the FedCM browser rather than sent by a websites trying to run an XSS attack. An IDP needs to check for this header’s value in the credentialed requests it receives, which ensures that the request was initiated by the user agent, based on the FedCM API. A malicious actor cannot spam FedCM API calls, so this is sufficient protection for the new IDP endpoints.

6.3. CORS Header

The FedCM API allows the response from the identity assertion endpoint to be shared to the RP. Because of this, we impose the requirement that the IDP explicitly consents to this sharing taking place by using the "cors" mode when fetching this endpoint. This also helps with servers that may accidentally ignore the Sec-Fetch-Dest: they cannot ignore CORS, as without it the fetch will fail.

6.4. Browser Surface Impersonation

The FedCM API introduces new (trusted) user agent UI, and the user agent may choose to show the UI entirely on top of the page’s contents, if anything because the page was the one responsible for this UI. This introduces a potential concern of a malicious site to try to replicate the FedCM UI, gain the user’s trust that the user is interacting with a trusted browser surface, and gather information from the user that they would only give to the browser rather than the site (e.g. usernames/passwords of another site). This would be hard to achieve because the FedCM UI uses metadata about the user accounts of the IDP, which the malicious website doesn’t have access to. If this is a malicious site, it would not know the user accounts unless the user is already compromised. However, the site could have some guess of the user identity, so the browser is encouraged to provide UI that is hard to replicate and that clearly presents the domains of the parties involved in the website’s FedCM call. Overall, an attacker trying to impersonate the browser using exclusively UI that is accessible to the content area (e.g. iframes) to attempt to retrieve sensitive information from the user would be noticeably different from the FedCM UI. Finally, because the FedCM UI can only be queried from the top-level frame (or potentially from an iframe with explicit permission from the top-level frame), the priviledged UI surface is only shown when the top-level frame wants it so. A sneaky iframe cannot force the FedCM UI to occlude important content from the main page.

7. Privacy

This section is intended to provide a comprehensive overview of the privacy risks associated with federated identity on the web for the purpose of measuring the privacy risks and benefits of proposed browser intermediation designs.

7.1. Principals

This section describes the four principals that would participate in an invocation of the API and expectations around their behavior.

  1. The user agent implements § 2 The Browser API and controls the execution contexts for the RP and IDP content. The user agent is assumed to be trusted by the user, and transitively trusted by the RP and IDP.

  2. RPs are websites that invoke the FedCM API for the purpose of authenticating a user to their account or for requesting information about that user. Since any site can invoke the API, RPs cannot necessarily be trusted to limit the user information it collects or use that information in an acceptable way.

  3. IDPs are third-party websites that are the target of a FedCM call to attempt to fetch a token. Usually,the IDP has a higher level of trust than the RP since it already has the user’s personal information, but it is possible that the IDP might use the user’s information in non-approved ways. In addition, it is possible that the IDP specified in the API call may not be an IDP the user knows about. In this case, it likely does not have personal user information in advance.

  4. A tracker is a third-party website that is not an IDP but could abuse the FedCM API exclusively for the purpose of tracking a user as they visit various websites. A tracker may be injected by the RP with or without their knowledge (e.g. injected into one of the various script tags that the RP embeds that is loaded dynamically), but they usually do not modify the UI of the website, so that it is harder to detect the tracking. A tracker that successfully adds tracking scripts for users in various websites may then use this information for various purposes, such as selling the information about the user. It should not be possible for trackers to use the FedCM API to track users across the web.

Based on the above, the privacy discussion makes the following assumptions:

  1. It is not acceptable for an RP, IDP, or tracker to learn that a specific user visited a specific site, without any permission granted by the user. That is, the user agent needs to hide the knowledge that a specific user identity visited a specific site from the RP, IDP, and trackers. It may share this knowledge with the RP and IDP once the user grants permission. In particular, the RP should not know the user identity and the IDP should not know the site that the user has visited before the FedCM flow gathers the user’s permission to do so.

  2. It is the user agent's responsibility to determine when the user has granted permission for the IDP to communicate with the RP in order to provide identification for the user.

  3. Once the user agent has determined that the user has granted permission to provide their account information to the RP, it is ok for the IDP and for the RP to learn information about that specific user’s account, as required to provide identification. The RP should not learn about about any other user accounts.

7.2. Network requests

This specification ensures that the FedCM fetches are all same-origin with respect to the provider specified by the RP. The reason for this is because fetches with cookies would use the cookies from the origin specified, so allowing arbitrary origins would introduce confusion and potential privacy issues with regards to which cookies are shared and with whom within the FedCM flow. The easiest way to ensure that all of these fetches remain same-origin is by disabling redirects and checking the origin of the fetched URLs.

7.3. Attack Scenarios

This section describes the scenarios in which various agents might attempt to gain user information. It considers the possibilities when:

For the purposes of this section, a principal is considered to be participating in the collection of information if it directly or indirectly performs actions with the aim of realizing one of the above threats.

Note: An example of indirect collusion would be an RP importing a script supplied by an IDP where the IDP intends to track users.

For the purpose of discussion, this document assumes that third-party cookies are disabled by default and are no longer effective for use in tracking mechanisms, and also some form of mitigations are implemented against ‘bounce tracking’ using link decoration or postMessage. Most of these scenarios consider how user tracking might happen without them. See also Pervasive Monitoring Is an Attack.

7.3.1. Manifest Fingerprinting

Suppose that the FedCM API did not have a two-tier manifest (see the create an IdentityCredential algorithm), and instead directly had a single manifest. This would introduce the following fingerprinting attack:

// The following will fetch the manifest JSON file, which will know the origin of the RP :(
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: \`https://idp.example/${window.location.href}\`
    }]
  }
});

NOTE: You can read more about the attack described here.

Here, the RP includes identifies itself when fetching the manifest from the IDP. This coupled with the credentialed fetches that the FedCM API performs would enable the IDP to easily track the website that the user is visiting, without requiring any permission from the user. Our mitigation to this problem is to use the § 3.1 The Well-Known File file. The existence of a file at the root of the IDP's domain is enforced to ensure that the file name does not introduce fingerprints about the RP being visited.

The whole manifest could be in this location, but instead it only points to the real manifest from there. This allows the flexibility in the future to allow a small constant number of manifests, should an IDP require this in the future, instead of just a single one. It also helps the IDP's implementation because they any changes to the manifest are more likely to be performed on a file located anywhere, as opposed to the root of the domain, which may have more constraints in terms of ease of update.

7.3.2. Timing Attacks

In the timing attack, the RP and IDP collude to allow the IDP to compute the (RP's origin, IDP's user identity) pair without the user’s permission. This attack is not deterministic: there is room for statistical error because it requires stitching together two separate pieces of information to track the user. However, it is important to mitigate this attack and ensure that it’s economically impractical to perform. In this attack, it is assumed that network requests do not have large fingerprinting vectors (e.g. IP addresses). These vary by user agent and are hard to eliminate entirely, but in general user agents are expected to address these over time. These bits of information tied to the network requests make the timing attack easier, making it more important to address.

Note: this attack is described and discussed here.

The attack is as follows:

  1. The RP logs the time at which it invokes the API, time A and sends it to the IDP to learn itself by marking the time in which it receives the fetch for the RP's client metadata. Time A is tied to the site.

  2. A credentialed request is sent to the IDP that does not explicitly identify the RP, but it is sent around a time that is close enough to the request above. The IDP notes the time in which this request has arrived, time B. Time B is tied to the user identity.

  3. The IDP correlates time A and time B to find the (site, user identity) pair with high probability. Note that fingerprinting can make the correlation more accurate.

Note that this kind of correlation is already possible without FedCM by using simple cross-origin top-level navigations, but using FedCM for this purpose would worsen the problem if it improved timing resolution or if it was less visible to users (e.g. the IDP could return empty accounts to the user agent to deliberately make no browser UI to be triggered, and hence make this attack invisible to the user).

The user agent should mitigate this attack to protect users, in an interoperable way.

7.3.3. IDP Intrusion

From Target Privacy Threat Model § hl-intrusion

Privacy harms don’t always come from a site learning things.

From RFC6973: Intrusion

Intrusion consists of invasive acts that disturb or interrupt one’s life or activities. Intrusion can thwart individuals' desires to be left alone, sap their time or attention, or interrupt their activities.

In the context of federation, intrusion happens when an RP and an IDP are colluding to invasively and aggressively recommend the user to login disproportionally to the their intent. Much like unsolicited notifications, an RP can collude with an IDP to aggressively log users in.

The user agent can mitigate this by mediating the user controls and offering them proportionally to the intent of the user or the privacy risks involved. For example, a user agent can choose to show a loud / disruptive modal mediated dialog when it has enough confidence of the user’s intent or show a quiet / conservative UI hint when it doesn’t.

A user agent could also choose to control disruption of the user’s experience based on the risks involved. For example, when a directed identifier is being exchanged it can be more confident of the unintended consequeces and offer a more aggressive user experience, whereas when global identifiers are exchanged a more conservative user experience.

7.3.4. Cross-Site Correlation

This attack happens when multiple RPs collude to use their user’s data to correlate them and build a richer profile. When a user willingly provides their full name, email address, phone number, etc, to multiple relying parties, those relying parties can collaborate to build a profile of that user and their activity across collaborating sites. Sometimes this is referred to as joining since it amounts to a join of user records between the account databases of multiple RPs. This correlation and profile-building is outside the user’s control and entirely out of the user agent’s or IDP’s view.

  1. User signs into RP1 (which sells jewelry) with an IDP, providing to RP1 their email address [email protected]

  2. User signs into RP2 (which sells houses) with an IDP, providing to RP2 their email address [email protected]

  3. User browses the collection of wedding rings in RP1.

  4. Out of band, RP1 tells RP2 that [email protected] is shopping for wedding rings

  5. User browses the housing inventory in RP2.

  6. RP2 uses the fact that the user is shopping for wedding rings in RP1 to advertise and filters their housing inventory.

  7. User is surprised that RP2 knows that they are shopping for wedding rings.

The problem of RPs joining user data via back-channels is inherent to the proliferation of identifying user data. This can be solved by issuing directed identifiers that provide an effective handle to a user’s identity with a given IDP that is unique and therefore cannot be correlated with other RPs. In the past, there have been schemes to accomplish this using one-way hashes of, for example, the user’s name, the IDP, and the RP. These identifiers would be unique, and hence it would not be possible to correlate these with other RPs.

7.3.5. Unauthorized Data Usage

Another attack is when the RP or IDP uses user information for purposes not authorized by the user. When the user agrees to allow the IDP to provide information to the RP, the permission is specific to certain purposes, such as sign-in and personalization. For instance, the RP might use that data for other purposes that the user would not expect and did not authorize, such as selling email addresses to a spam list. Spamming risk can exist even when using directed identifiers.

7.3.6. RP Fingerprinting

This attack happens when the RP employs client state-based tracking to identify user. Any API that exposes any kind of client state to the web risk becoming a vector for fingerprinting. The purpose of this API is for the user to provide identification to the RP. And the user should be able to rescind the access to that identification, for instance by logging out. However, a tracking RP could keep state to detect the user that was previously logged in:

7.3.7. Secondary Use

Secondary use is the use of collected information about an individual without the individual’s perimssion for a purpose different from that for which the information was collected. This attack happens when IDPs misuse the information collected to enable sign-in for other purposes.

Existing federation protocols require that the IDP know which service is requesting a token in order to allow identity federation. Identity providers can use this fact to build profiles of users across sites where the user has decided to use federation with the same account. This profile could be used, for example, to serve targeted advertisements to those users browsing on sites that the IDP controls.

This risk can exist even in the case where the IDP does not having pre-existing user account information (for instance, if it is not a _bona fide_ IDP), because FedCM requests sent to the IDP are credentialed. This is more likely to occur if the RP is colluding with the IDP to enable tracking via § 7.3.2 Timing Attacks.

  1. User signs into RP1 (which sells jewelry) with an IDP.

  2. User signs into RP2 (which sells houses) with the same IDP.

  3. User navigates to the IDP.

  4. Because the IDP knows that the user has an account with RP1 and RP2, the IDP can show ads about vacations for honeymoons.

  5. The user is surprised that their IDP is aware of their plans to get married.

Preventing tracking of users by the IDP is difficult: the RP has to be coded into the identity token for security reasons, such as token reuse and fraud and abuse prevention. There have been cryptographic schemes developed to blind the IDP to the RP while still preventing token reuse(see Mozilla’s personas). These schemes have not been adopted by this specification.

8. Extensibility

Note: go over the extensibility mechanisms.

9. Acknowledgements

Note: write down the Acknowledgements section.

10. FPWD Issues

Note: The WG has labeled the following issues as critical open issues that must be formally addressed before publication of a Candidate Recommendation.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. Key words for use in RFCs to Indicate Requirement Levels

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CLEAR-SITE-DATA]
Mike West. Clear Site Data. 30 November 2017. WD. URL: https://www.w3.org/TR/clear-site-data/
[CREDENTIAL-MANAGEMENT-1]
Nina Satragno; Marcos Caceres. Credential Management Level 1. 13 August 2024. WD. URL: https://www.w3.org/TR/credential-management-1/
[CSP]
Mike West; Antonio Sartori. Content Security Policy Level 3. 18 June 2024. WD. URL: https://www.w3.org/TR/CSP3/
[CSS-COLOR-4]
Chris Lilley; Tab Atkins Jr.; Lea Verou. CSS Color Module Level 4. 13 February 2024. CR. URL: https://www.w3.org/TR/css-color-4/
[CSS-COLOR-5]
Chris Lilley; et al. CSS Color Module Level 5. 29 February 2024. WD. URL: https://www.w3.org/TR/css-color-5/
[CSSOM-VIEW-1]
Simon Pieters. CSSOM View Module. 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-view-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.es/ecma262/multipage/
[ENCODING]
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[FETCH-METADATA]
Mike West. Fetch Metadata Request Headers. 31 October 2023. WD. URL: https://www.w3.org/TR/fetch-metadata/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[MIMESNIFF]
Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[OIDC-Connect-Core]
OIDC Connect Core. URL: https://openid.net/specs/openid-connect-core-1_0.html
[PERMISSIONS-POLICY-1]
Ian Clelland. Permissions Policy. 24 July 2024. WD. URL: https://www.w3.org/TR/permissions-policy-1/
[PRIVACY-THREAT-MODEL]
Target Privacy Threat Model. URL: https://w3cping.github.io/privacy-threat-model/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC6973]
A. Cooper; et al. Privacy Considerations for Internet Protocols. July 2013. Informational. URL: https://www.rfc-editor.org/rfc/rfc6973
[RFC9110]
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP Semantics. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9110.html
[SECURE-CONTEXTS]
Mike West. Secure Contexts. 10 November 2023. CR. URL: https://www.w3.org/TR/secure-contexts/
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WEBDRIVER1]
Simon Stewart; David Burns. WebDriver. 5 June 2018. REC. URL: https://www.w3.org/TR/webdriver1/
[WebDriver2]
Simon Stewart; David Burns. WebDriver. 23 July 2024. WD. URL: https://www.w3.org/TR/webdriver2/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[CM]
Credential Management. URL: https://w3c.github.io/webappsec-credential-management/
[PERMISSIONS-POLICY]
Permissions Policy. URL: https://w3c.github.io/webappsec-permissions-policy
[PRIVACY-MODEL]
Privacy Model. URL: https://github.com/michaelkleber/privacy-model
[RFC7258]
Pervasive Monitoring Is an Attack. URL: https://datatracker.ietf.org/doc/html/rfc7258

IDL Index

enum LoginStatus {
  "logged-in",
  "logged-out",
};

[Exposed=Window, SecureContext] 
interface NavigatorLogin {
  Promise<undefined> setStatus(LoginStatus status);
};

partial interface Navigator {
  [SecureContext] readonly attribute NavigatorLogin login;
};

dictionary IdentityCredentialDisconnectOptions : IdentityProviderConfig {
  required USVString accountHint;
};

[Exposed=Window, SecureContext]
interface IdentityCredential : Credential {
  static Promise<undefined> disconnect(optional IdentityCredentialDisconnectOptions options = {});
  readonly attribute USVString? token;
  readonly attribute boolean isAutoSelected;
};

dictionary DisconnectedAccount {
  required USVString account_id;
};

partial dictionary CredentialRequestOptions {
  IdentityCredentialRequestOptions identity;
};

enum IdentityCredentialRequestOptionsContext {
  "signin",
  "signup",
  "use",
  "continue"
};

dictionary IdentityCredentialRequestOptions {
  required sequence<IdentityProviderRequestOptions> providers;
  IdentityCredentialRequestOptionsContext context = "signin";
};

dictionary IdentityProviderConfig {
  required USVString configURL;
  required USVString clientId;
};

dictionary IdentityProviderRequestOptions : IdentityProviderConfig {
  USVString nonce;
  DOMString loginHint;
  DOMString domainHint;
};

dictionary IdentityProviderWellKnown {
  required sequence<USVString> provider_urls;
};

dictionary IdentityProviderIcon {
  required USVString url;
  unsigned long size;
};

dictionary IdentityProviderBranding {
  USVString background_color;
  USVString color;
  sequence<IdentityProviderIcon> icons;
  USVString name;
};

dictionary IdentityProviderAPIConfig {
  required USVString accounts_endpoint;
  required USVString client_metadata_endpoint;
  required USVString id_assertion_endpoint;
  required USVString login_url;
  USVString disconnect_endpoint;
  IdentityProviderBranding branding;
};

dictionary IdentityProviderAccount {
  required USVString id;
  required USVString name;
  required USVString email;
  USVString given_name;
  USVString picture;
  sequence<USVString> approved_clients;
  sequence<DOMString> login_hints;
  sequence<DOMString> domain_hints;
};
dictionary IdentityProviderAccountList {
  sequence<IdentityProviderAccount> accounts;
};

dictionary IdentityProviderToken {
  required USVString token;
};

dictionary IdentityProviderClientMetadata {
  USVString privacy_policy_url;
  USVString terms_of_service_url;
};

dictionary IdentityUserInfo {
  USVString email;
  USVString name;
  USVString givenName;
  USVString picture;
};

[Exposed=Window, SecureContext] interface IdentityProvider {
    static undefined close();
    static Promise<sequence<IdentityUserInfo>> getUserInfo(IdentityProviderConfig config);
};

Issues Index

The HTTP header checking should move into the Fetch spec, since it affects all resource loads. ↵
Once Clear-Site-Data supports partitioned cookies, this wording should be updated. ↵
the connected accounts set should be double keyed in the RP (i.e., it should include both the requester and the embedder, or in other words the iframe and the top-level). Otherwise the top-level’s state could be used and modified by the embedder, which introduces leaks and unwanted cross-origin communication. ↵
Support choosing accounts from multiple IDPs, as described here. ↵
We should perhaps provide a way to let the RP request that the second option is provided, possibly gated on a user gesture. See this issue for discussion. ↵
The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details. ↵
relax the size of the provider_urls array. ↵
The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details. ↵
The credentialed fetch in this algorithm can lead to a timing attack that leaks the user’s identities before the user grants permission. This is an active area of investigation that is being explored here. ↵
The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details. ↵
the accounts list returned here should be validated for repeated ids, as described here. ↵
The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details. ↵
The spec is yet to be updated so that all requests are created with mode set to "user-agent-no-cors". See the relevant pull request for details. ↵
Decide whether IdentityProvider is the correct location for the getUserInfo() method. ↵
Clarify the IDP API response when the user is not signed in. ↵