# A Well-Known URL for Changing Passwords

## Draft Community Group Report, 1 January 1970

This version:
  https://wicg.github.io/change-password-url/index.html
Editors:
  Ricky Mondello (Apple Inc.)
  Theresa O'Connor (Apple Inc.)

Copyright © 1970 the Contributors to the A Well-Known URL for Changing Passwords Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

## Abstract

This specification defines a well-known URL that sites can use to make their change password forms discoverable by tools. This simple affordance provides a way for software to help the user find the way to change their password.

## Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

## 1. Introduction

This section is non-normative.

Client-side password management software helps improve both the security and usability of websites which require authentication. It improves security by reducing cross-site password reuse, and enhances usability by providing autofill functionality.

Sites currently lack a way to programmatically advertise where a user can change their password. By proposing a well-known URL for changing passwords, this specification enables password managers to help users change their passwords on sites which support it.

## 2. Infrastructure

This specification depends on the Infra Standard. [INFRA]

This specification uses terminology from the Fetch, HTML, HTTP, and URL standards. [FETCH] [HTML] [HTTP-SEMANTICS] [URL]

## 3. Change Password URLs

A change password url of an origin is a URL that points to a resource that clients can use to discover where a user should go to update their password on origin.

Given an origin, clients generate a change password url by running these steps:

1. If origin is not a potentially trustworthy origin, return failure.

2. Assert: origin is a tuple origin.

3. Let url be a new `URL` with values set as follows:

   scheme

     origin’s scheme

   host

     origin’s host

   port

     origin’s port

   path

     « ".well-known", "change-password" ».

4. Return url.

The change password url for origin `"https://example.com/"` is `"https://example.com/.well-known/change-password"`.

Servers should redirect HTTP requests for an origin’s change password url to the actual page on which users may change their password by returning a response with a redirect status of 302, 303, or 307, and a Location header. [FETCH] [HTTP-SEMANTICS] Clients must handle such redirects when requesting a change password url.

Note: The above paragraph restricts servers to using temporary redirect codes. See Issue 13.

If necessary, servers may respond with an HTML document containing an `http-equiv` pragma directive in the refresh state. [HTML] Clients should handle such redirects when requesting a change password url.

Servers must not locate the actual change password page at the change password url, per RFC5785 §1.1 Appropriate Use of Well-Known URIs. Clients must handle ok status responses when requesting a change password url.

Note: Implementations might want to use ToUnicode when displaying change password urls. [IDNA]

## 4. IANA considerations

### 4.1. The `change-password` well-known URI

This document defines the “`.well-known`” URI `change-password`. This registration will be submitted to the IESG for review, approval, and registration with IANA using the template defined in [WELL-KNOWN] as follows:

URI suffix

  change-password

Change controller

  W3C

Specification document(s)

  This document is the relevant specification. (See § 3 Change Password URLs)

Related information:

  None.

## Acknowledgements

Thanks to Anne van Kesteren, Cl1608Ho, Dan Bernstein, David Singer, Dean Jackson, Florian Rivoal, John Wilander, Maciej Stachowiak, Mark Nottingham, Mike West, and Ricky Mondello for their feedback on this proposal. All of its features are theirs and all of its bugs are mine.

## Conformance

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.

## Index

### Terms defined by this specification

- change password url, in §3
- generate a change password url, in §3

https://fetch.spec.whatwg.org/#ok-status Referenced in:

- 3. Change Password URLs

https://fetch.spec.whatwg.org/#redirect-status Referenced in:

- 3. Change Password URLs

https://fetch.spec.whatwg.org/#concept-request Referenced in:

- 3. Change Password URLs

https://fetch.spec.whatwg.org/#concept-response Referenced in:

- 3. Change Password URLs

https://html.spec.whatwg.org/multipage/origin.html#concept-origin-host Referenced in:

- 3. Change Password URLs

https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv Referenced in:

- 3. Change Password URLs

https://html.spec.whatwg.org/multipage/infrastructure.html#concept-url-origin Referenced in:

- 3. Change Password URLs (2) (3)

https://html.spec.whatwg.org/multipage/origin.html#concept-origin-port Referenced in:

- 3. Change Password URLs

https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-refresh Referenced in:

- 3. Change Password URLs

https://html.spec.whatwg.org/multipage/origin.html#concept-origin-scheme Referenced in:

- 3. Change Password URLs

https://html.spec.whatwg.org/multipage/origin.html#concept-origin-tuple Referenced in:

- 3. Change Password URLs

https://tools.ietf.org/html/rfc7231#section-7.1.2 Referenced in:

- 3. Change Password URLs

https://www.unicode.org/reports/tr46/#ToUnicode Referenced in:

- 3. Change Password URLs

https://w3c.github.io/webappsec-secure-contexts/#potentially-trustworthy-origin Referenced in:

- 3. Change Password URLs

https://url.spec.whatwg.org/#url Referenced in:

- 3. Change Password URLs

https://url.spec.whatwg.org/#concept-url-host Referenced in:

- 3. Change Password URLs

https://url.spec.whatwg.org/#concept-url-path Referenced in:

- 3. Change Password URLs

https://url.spec.whatwg.org/#concept-url-port Referenced in:

- 3. Change Password URLs

https://url.spec.whatwg.org/#concept-url-scheme Referenced in:

- 3. Change Password URLs

### Terms defined by reference

- [FETCH] defines the following terms:
  - ok status
  - redirect status
  - request
  - response
- [HTML] defines the following terms:
  - host
  - http-equiv
  - origin
  - port
  - refresh state
  - scheme
  - tuple origin
- [HTTP-SEMANTICS] defines the following terms:
  - location
- [IDNA] defines the following terms:
  - ToUnicode
- [secure-contexts] defines the following terms:
  - potentially trustworthy origin
- [URL] defines the following terms:
  - URL
  - host
  - path
  - port
  - scheme

## References

### Normative References

[FETCH]
  Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
  Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[HTTP-SEMANTICS]
  R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[INFRA]
  Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
  S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SECURE-CONTEXTS]
  Mike West. Secure Contexts. 15 September 2016. CR. URL: https://www.w3.org/TR/secure-contexts/
[URL]
  Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WELL-KNOWN]
  M. Nottingham. Well-Known Uniform Resource Identifiers (URIs). May 2019. Proposed Standard. URL: https://tools.ietf.org/html/rfc8615

### Informative References

[IDNA]
  Mark Davis; Michel Suignard. Unicode IDNA Compatibility Processing. 26 April 2019. Unicode Technical Standard #46. URL: https://www.unicode.org/reports/tr46/tr46-24.html

#change-password-url Referenced in:

- 3. Change Password URLs (2) (3) (4) (5) (6)