[FedCM] Action Required: Upcoming breaking changes

[FedCM developer newsletter]

Hello FedCM newsletter subscribers,

We have been improving FedCM's privacy, developer experience, and browser interoperability, addressing ecosystem feedback. This time it means we need to ship some breaking changes, and your action is required.  

We understand you may be concerned about any disruption in your solution. To allow for a smooth transition, we are providing a grace period. The new behavior will be enabled alongside the old behavior in Chrome 143. We plan to make these changes the default and remove support for the previous setup in Chrome 145. You can always reach out to us by filing a GitHub issue if you need more time to transition.

To help you navigate this transition, we've outlined the key actions and required updates below. 

Upcoming breaking changes

1. Required endpoints in .well-known

To enhance privacy and ensure proper endpoint discovery, we are tightening the validation for the .well-known/web-identity file.

• What's changing? If your FedCM configuration uses the client_metadata endpoint, you are now required to explicitly declare the accounts_endpoint and login_url in your .well-known/web-identity file. 

• Why? This change aims to prevent the IdP from matching an RP to a unique ID passed as a path parameter in the endpoints, reducing the surface area for user tracking.

• Action Required: Update your .well-known/web-identity file to include both accounts_endpoint and login_url. The provider_urls field can be removed, as it is no longer needed when these endpoints are specified. This functionality has been supported since Chrome 132, so you can make this change today.

• Try it out: You can test this behavior in Chrome Canary 143 or newer by enabling the flag: chrome://flags/#fedcm-well-known-endpoint-validation

2. Renaming of IdentityCredentialError.code

We are renaming an error property to prevent confusion with a built-in DOMException's code property.

• What's changing? The IdentityCredentialError.code property is being renamed to IdentityCredentialError.error. The data type remains a DOMString.

• Why? This change prevents potential confusion with the standard DOMException.code property, improving developer experience. This change was suggested by a key contributor in the browser ecosystem, and we're adopting it to ensure interoperability of FedCM among different browsers.

• Action Required: Update your error handling logic to reference IdentityCredentialError.error instead of IdentityCredentialError.code both in the ID assertion response as well as when processing FedCM errors in the RP JavaScript.

• Recommendation: For backward compatibility, we suggest including both code and error in your ID assertion responses for a transitional period. This will ensure that older browsers continue to function correctly as users upgrade.

• Try it out: You can test this in Chrome Canary 143 or newer by enabling the flag: chrome://flags/#fedcm-error-attribute

3. Nonce parameter relocation

• What's changing? The nonce parameter will no longer be accepted as a top-level parameter in the navigator.credentials.get() call. It must now be passed inside the params object. Consequently, the nonce will no longer be a top-level parameter in the request to the ID assertion endpoint, but it will be available within the params that are passed through.

• Why? This change aims to improve the structure of the API, simplify parsing for the IdPs, and future-proof the maintainability of FedCM solutions.

• Action Required:

  1. Modify your client-side calls to navigator.credentials.get() to pass the nonce within the params object.

  2. Adjust your server-side logic at the ID assertion endpoint to extract the nonce, if needed.

• Try it out: You can test this in Chrome Canary by enabling the flag: chrome://flags/#fedcm-nonce-in-params

Timeline

• December 2, 2025 (Chrome 143): Changes are enabled, but the old behavior is still supported.

• February 10, 2026 (Chrome 145): Changes become the default, and support for the old behavior is removed.

We strongly encourage you to begin testing these changes in Chrome Canary using the flags provided above to ensure your integration is ready.

We value your feedback

Your feedback is crucial to the success of FedCM. If you encounter any issues or have questions about these changes, file an issue on our GitHub repository.

As always, we appreciate your collaboration,

The FedCM Team.