Skip to main content

Redirect a request to /.well-known/change-password to the password change url

Set a redirect from /.well-known/change-password to the password change page of your website. This will allow password managers to navigate their users directly to that page.


How could you know passwords are not the best way to manage accounts. Fortunately, there are emerging technologies such as
WebAuthn and techniques such as one-time passwords that help us approach a world without passwords. However, these technologies are still being developed and things will not change quickly. Many developers will still need to deal with passwords for at least the next few years. While we wait for emerging technologies and techniques to become commonplace, we can at least make passwords easier to use.

A good way to do this is to better support password managers.

How Password Managers Help

Password managers can be integrated into browsers or provided as third-party applications. They can help users in several ways:

Autocomplete password for correct input field: Some browsers can heuristically find the correct entry even if the website is not optimized for this purpose. Web developers can help password managers by correctly annotating HTML input tags.

Prevent phishing: Because password managers remember where the password was recorded, the password can be autofilled only at the appropriate URLs and not on phishing websites.

Generate strong and unique passwords: Because the password manager directly generates and stores strong and unique passwords, users do not have to remember a single character of the password.

Generating and auto-filling passwords with a password manager has already worked well on the web, but considering its lifecycle, updating passwords whenever necessary is just as important as generating and auto-filling. To take advantage of that properly, password managers are adding a new feature:

Detect vulnerable passwords and suggest updating themPassword managers can detect passwords that are reused, analyze passwords for entropy and weakness, and even detect potentially leaked passwords or those that are known to be unsafe from sources such as They have cheated me?.

A password manager can warn users about problematic passwords, but there is a lot of friction in asking users to navigate from the home page to a password change page, in addition to going through the actual password change process (which varies from site to site). . It would be much easier if password managers could take the user directly to the password change URL. This is where a well-known URL to change passwords it becomes useful.

By reserving a known URL path that redirects the user to the password change page, the website can easily redirect users to the right place to change their passwords.

Configure "a known URL to change passwords"

.well-known / change-password it is proposed as a well-known URL to change passwords. All you have to do is configure your server to redirect requests for .well-known / change-password
to your website's password change URL.

For example, let's say your website is and the password change url is You will only need to configure your server to redirect a request for to That's it. For redirection, use HTTP status code
302 Found, 303 See Other or 307 Temporary Redirect.

Alternatively, you can serve HTML in your .well-known / change-password URL with a label using a
http-equiv = "refresh".

<meta http-equiv="refresh" content="0;url=">

Re-visit the password change page HTML

The purpose of this feature is to help make the user's password life cycle more seamless. You can do two things so that the user can update their password without problems:

  • If your password change form requires the current password, add
    autocomplete = "current-password" to the label to help the password manager to fill it in automatically.
  • For the new password field (in many cases it is two fields to ensure that the user entered the new password correctly), add
    autocomplete = "new-password" to the label to help the password manager suggest a generated password.

Learn more at Best Practices for the Login Form.

How to use it in the real world


Thanks to Apple Safari
/.well-known/change-password, is already available on some major websites for a while:

Try them for yourself and do the same for yours.

Browser compatibility

A well-known URL has been created to change passwords. supported in Safari since 2019. Chrome's password manager is starting to support it as of version 86 (which is scheduled for a stable release in late October 2020) and other Chromium-based browsers may follow. Firefox finds it worth implementing, but has not indicated that it plans to do so from August 2020.

Chrome password manager behavior

Let's take a look at how Chrome's password manager handles vulnerable passwords.

Chrome's password manager can search for leaked passwords. Navigating to chrome://settings/passwords users can run Check passwords against stored passwords and view a list of passwords that are recommended to update.


Chrome Check passwords functionality

By clicking on the Change password together with a password that is recommended to update, the browser:

  • Open the website password change page if /.well-known/change-password is configured correctly.
  • Open the website home page if /.well-known/change-password it is not configured and Google does not know the alternative.

Password managers try to determine if a website supports a known URL for changing passwords by sending a request to /.well-known/change-password before forwarding a user to this URL. If the request returns 404 Not Found
the url is obviously not available, but a 200 OK The answer does not necessarily mean that the URL is available, because there are some extreme cases:

  • A server-side rendering website shows "Not Found" when there is no content but with 200 OK.
  • A server-side rendering website responds with 200 OK when there is no content after redirecting to "Not Found" page.
  • A single page application responds with the shell with 200 OK and displays the "Not Found" page on the client side when there is no content.

For these extreme cases, users will be redirected to a "Not Found" page and that will be a source of confusion.

Because of that there are a proposed standard mechanism
to determine if the server is configured to respond with 404 Not Found
when there really is no content, requesting a random page. In fact, the URL is also reserved:
/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200. Chrome, for example, uses this URL path to determine if it can expect a proper password change URL from /.well-known/change-password in advance.

When you are deploying /.well-known/change-password, make sure your server returns 404 Not Found for any non-existent content.


If you have any comments on the specification, please submit a problem to the spec repository.


Photo by Matthew brodeur in Unsplash