FedCM updates: Domain Hint API

Eiji Kitamura

From Chrome 123, you can use the Domain Hints alongside the Federated Credential Management API (FedCM). With the Domain Hint API, developers can provide a better user experience by only showing the federated login accounts from the domain that they accept.

Domain Hint API

FedCM can be used to make it easier for a user to login to a relying party (RP, referring to a website) using account information provided by an identity provider (IdP). However, there are cases where the RP already knows that only accounts associated with a certain domain are allowed to login to the site. This is particularly common in enterprise scenarios where the site being accessed is restricted to a corporate domain. To provide a better user experience, the FedCM API allows the RP to only show the accounts which may be used to login to the RP. This prevents scenarios where a user tries to login to the RP using an account outside of the corporate domain, only to be served with an error message later (or silence where the login did not work) because the right type of account was not used.

With the Domain Hint API, RPs can specify a domainHint property on a FedCM API call to show only matching accounts for the user. The IdP can provide a domain_hints property as part of a response from the accounts list endpoint to indicate with which domain(s) an account is associated. This way, the browser can show the matching accounts without disclosing the requested domain hint to the IdP.

An example JSON response from the accounts list endpoint would look like the following:

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

The RP can call navigator.credentials.get() with a domainHint property to filter the accounts. For example, say a user visits corp-partner.example and signs in with an account from corp.example. The site would invoke the API as follows:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

The domainHint value is not sent to the accounts list endpoint for server side filtering, since that can be a fingerprinting vector to the IdP. Instead, Chrome performs a FedCM request as usual, and filters out the accounts that don't match the domainHint value specified by the navigator.credentials.get() call. Then, Chrome shows the FedCM dialog to the user with the new accounts list. This approach is similar to the Login Hint API, but these two APIs answer different questions. The Login Hint API aims to answer "which is an identifier for the user I want?", while Domain Hint aims to answer "which corporation or server must this account belong to?".

When domainHint: "any" is used, Chrome filters out accounts which don't have any domains (that is, domain_hints is not passed or is empty). For example, this allows use cases where the RP only allows managed accounts in its signup process.

When no accounts match the domainHint, the FedCM dialog shows a login prompt, which allows the user to login to an IdP account matching the hint requested by the RP. When the user taps on the prompt, a popup window is opened with the login URL specified in the config file. The link is then appended with the login hint and the domain hint query parameters.