Password Change Automation

A Collection of Interesting Ideas,

This version:
(Google Inc.)


This document defines a mechanism by which web developers may offer password managers the ability to automatically change a user’s password.

1. Introduction

TODO(mkwst): Put an introduction here.

1.1. Goals

  1. Password managers should be able to respond to breach reports by changing a user’s password directly, rather than prompting a user to do it themselves.

  2. Password changes should be possible in a completely automated fashion, without depending on heuristics to detect password change forms, or (worse) on manually coded mechanisms for every origin.

  3. Any password manager should be able to make use of the functionality, without necessitating a deep integration between products.

  4. Accounts protected by second-factor authentication mechanisms should be able to reauthenticate a user before their password is changed.

2. Framework

At a high level, the mechanism in this document boils down to the following:

  1. An origin hosts a discovery manifest at `/.well-known/password`, which contains metadata which both asserts that passwords stored for this origin are capable of being changed automatically, and defines parameters which a password manager will use when making a change request.

  2. Once a password manager has verified that an origin’s passwords can be automatically changed, it may do so by sending a `PUT` request to `/.well-known/password/change` which contains the user’s current username and password tuple, along with the new password.

2.1. Discovery

In order to assert that passwords for an origin are automatically changable, a conformant server MUST serve a password change automation manifest which password managers retrieve by sending a `GET` request to the well-known URL `/.well-known/password`.

The manifest MUST be delivered as a response whose status code is `200`, content type is `application/json`, and body is equivalent to the result of executing JSON.stringify() on a PasswordChangeAutomation dictionary:

dictionary PasswordChangeAutomation {
  boolean passwordChangeAutomationSupported = true;
  DOMString title;
  USVString failureURL;
MegaCorp, Inc. wishes to support password change automation for accounts used on ``. It informs password managers that the change mechanism described in this document is supported by placing the following file at ``:
  "passwordChangeAutomationSupported: true,
  "title: "MegaCorp, Inc.",
  "failureURL: ""

3. Ideas

It would be bad if automation meant that attackers could trivially modify all the passwords for all the users caught up in password dumps. We could harden this mechanism in a few ways:

  1. Extend the credential management API to accept a public key along with credential storage. The server would generate a keypair when calling `store()`, hand the public key to the password manager without storing it, and store the private key in some secure way. When requesting a password change, the client would encrypt the password change request using the public key, and the server would decrypt using the private key.

    The upside is mitigation of dragnet password changes. The downside is that key management is hard.

  2. Moar?


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. [RFC2119]

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.


Terms defined by this specification


Normative References

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL:

IDL Index

dictionary PasswordChangeAutomation {
  boolean passwordChangeAutomationSupported = true;
  DOMString title;
  USVString failureURL;