├── .gitignore ├── .pr-preview.json ├── w3c.json ├── LICENSE.md ├── CODE_OF_CONDUCT.md ├── .github └── workflows │ └── deploy.yml ├── Makefile ├── CONTRIBUTING.md ├── README.md ├── response-code-reliability.bs └── change-password-url.bs /.gitignore: -------------------------------------------------------------------------------- 1 | build 2 | *~ 3 | -------------------------------------------------------------------------------- /.pr-preview.json: -------------------------------------------------------------------------------- 1 | { 2 | "src_file": "change-password-url.bs", 3 | "type": "bikeshed", 4 | "params": { 5 | "force": 1 6 | } 7 | } 8 | 9 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": 49309 3 | , "contacts": ["wseltzer", "weiler"] 4 | , "policy": "open" 5 | , "repo-type": "rec-track" 6 | } 7 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All documents in this Repository are licensed by contributors under the [W3C Document 2 | License](http://www.w3.org/Consortium/Legal/copyright-documents). 3 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). 4 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: deploy 2 | 3 | on: 4 | pull_request: {} 5 | push: 6 | branches: [main] 7 | 8 | jobs: 9 | main: 10 | name: Build, Validate, and Publish 11 | runs-on: ubuntu-20.04 12 | steps: 13 | - uses: actions/checkout@v2 14 | - uses: w3c/spec-prod@v2 15 | with: 16 | SOURCE: change-password-url.bs 17 | TOOLCHAIN: bikeshed 18 | GH_PAGES_BRANCH: gh-pages 19 | BUILD_FAIL_ON: nothing 20 | VALIDATE_LINKS: false 21 | VALIDATE_MARKUP: true 22 | W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }} 23 | W3C_WG_DECISION_URL: https://lists.w3.org/Archives/Public/public-webappsec/2015Mar/0170.html 24 | W3C_BUILD_OVERRIDE: | 25 | shortname: change-password-url 26 | status: WD 27 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # This Makefile assumes you have a local install of bikeshed. Like any 2 | # other Python tool, you install it with pip: 3 | # 4 | # python3 -m pip install bikeshed && bikeshed update 5 | 6 | # It also assumes you have doctoc installed. This is a tool that 7 | # automatically generates Table of Contents for Markdown files. It can 8 | # be installed like any other NPM module: 9 | # 10 | # npm install -g doctoc 11 | 12 | .PHONY: all publish clean update-explainer-toc 13 | .SUFFIXES: .bs .html 14 | 15 | publish: build/index.html build/response-code-reliability.html 16 | 17 | all: publish update-explainer-toc 18 | 19 | clean: 20 | rm -rf build *~ 21 | 22 | update-explainer-toc: README.md Makefile 23 | doctoc $< --title "## Table of Contents" > /dev/null 24 | 25 | build/index.html: build/change-password-url.html 26 | mv $< $@ 27 | 28 | build/%.html: %.bs Makefile 29 | mkdir -p build 30 | bikeshed --die-on=warning spec $< $@ 31 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to this specification 2 | 3 | Contributions to this repository are intended to become part of Recommendation-track documents 4 | governed by the [W3C Patent Policy](http://www.w3.org/Consortium/Patent-Policy-20040205/) and 5 | [Document License](http://www.w3.org/Consortium/Legal/copyright-documents). To contribute, you must 6 | either participate in the relevant W3C Working Group or make a non-member patent licensing 7 | commitment. 8 | 9 | If you are not the sole contributor to a contribution (pull request), please identify all 10 | contributors in the pull request's body or in subsequent comments. 11 | 12 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 13 | 14 | ``` 15 | +@github_username 16 | ``` 17 | 18 | If you added a contributor by mistake, you can remove them in a comment with: 19 | 20 | ``` 21 | -@github_username 22 | ``` 23 | 24 | If you are making a pull request on behalf of someone else but you had no part in designing the 25 | feature, you can remove yourself with the above syntax. 26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # A Well-Known URL for Changing Passwords 2 | 3 | 4 | 5 | ## Table of Contents 6 | 7 | - [Proposal](#proposal) 8 | - [Frequently Asked Questions](#frequently-asked-questions) 9 | - [Why not allow sites to override this location with an HTTP Link header or an HTML `link` element?](#why-not-allow-sites-to-override-this-location-with-an-http-link-header-or-an-html-link-element) 10 | - [Why not serve a JSON resource with links to other account management functions?](#why-not-serve-a-json-resource-with-links-to-other-account-management-functions) 11 | - [What tools have implemented this feature?](#what-tools-have-implemented-this-feature) 12 | - [What about servers whose HTTP response codes are unreliable?](#what-about-servers-whose-http-response-codes-are-unreliable) 13 | 14 | 15 | 16 | Currently, if the user of a password manager would like to change their password on `example.com`, basically all the password manager can do is load `example.com` in a browser tab and hope the user can figure out how to update their password themselves. 17 | 18 | The goal of this [specification](https://w3c.github.io/webappsec-change-password-url/) is to do the simplest possible thing to improve this situation, by defining the /.well-known/change-password [well-known resource](https://tools.ietf.org/html/rfc5785). 19 | 20 | ## Proposal 21 | 22 | `example.com` provides a `/.well-known/change-password` resource which redirects to their change password form, wherever it happens to already be. 23 | 24 | Password managers check for the existence of `/.well-known/change-password` on `https://example.com`. 25 | 26 | If it's there (the response code is `2xx` or `3xx`), the password manager can cause the user's browser to navigate there when the user indicates they'd like to change their password. 27 | 28 | That's it, really. It's a pretty simple idea. 29 | 30 | ## Frequently Asked Questions 31 | 32 | ### Why not allow sites to override this location with an HTTP Link header or an HTML `link` element? 33 | 34 | Implementation complexity. (This would require keeping site-specific state client-side, verifying & invalidating said state periodically, etc.) 35 | 36 | ### Why not serve a JSON resource with links to other account management functions? 37 | 38 | Specification complexity. If we determine we need other account management well-known resources in the future, we can specify them then. 39 | 40 | ### What tools have implemented this feature? 41 | 42 | * iCloud Keychain on iOS 12 43 | * Safari 12 44 | * 1Password (1Password 8 and 1Password for Chrome, Firefox, Edge and macOS Safari) 45 | * Chrome 86 46 | * [Backdrop CMS](https://backdropcms.org/), via the [Well-known module](https://backdropcms.org/project/well_known). 47 | 48 | ### What about servers whose HTTP response codes are unreliable? 49 | 50 | Sometimes, HTTP servers are configured to respond `200 OK` for resources that really aren't there. The [Detecting the reliability of HTTP status codes](https://w3c.github.io/webappsec-change-password-url/response-code-reliability.html) draft attempts to address this problem. 51 | -------------------------------------------------------------------------------- /response-code-reliability.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Title: Detecting the reliability of HTTP status codes
 3 | Shortname: response-code-reliability
 4 | Level: 1
 5 | Status: ED
 6 | Group: WebAppSec
 7 | Repository: w3c/webappsec-change-password-url
 8 | URL: https://w3c.github.io/webappsec-change-password-url/response-code-reliability.html
 9 | Editor: Elaine Knight, w3cid 126366, Apple Inc. https://apple.com, elaine_knight@apple.com
10 | Editor: Ricky Mondello, w3cid 103933, Apple Inc. https://apple.com/, rmondello@apple.com
11 | Editor: Theresa O'Connor, w3cid 40614, Apple Inc. https://apple.com/, hober@apple.com
12 | Abstract: Defines a method for detecting the reliability of an HTTP server's response status codes.
13 | Complain About: accidental-2119 true
14 | Markup Shorthands: idl yes, markdown yes
15 |
16 | 
17 | {
18 |     "WELL-KNOWN": {
19 |         "aliasOf": "RFC8615"
20 |     }
21 | }
22 |
23 | 
24 | text:well-known URI; type:dfn; spec:rfc8615; url:https://tools.ietf.org/html/rfc8615#section-3
25 |
26 | 
27 | spec:url; type:interface; text:URL
28 |
29 | 30 |
31 | 32 |

Introduction

33 | 34 | This section is non-normative. 35 | 36 | A number of specifications define [=well-known URIs=]. [[!WELL-KNOWN]] 37 | 38 | Clients attempting to detect the presence of [=well-known URIs=] sometimes encounter misconfigured HTTP servers which respond with a 2xx status when the resource actually doesn't exist. 39 | 40 | This specification defines a method for discovering if an HTTP server is misconfigured in this way. 41 | 42 |
43 | 44 |

Infrastructure

45 | 46 | This specification depends on the Infra Standard. [[!INFRA]] 47 | 48 |

Detecting the reliability of HTTP status codes

49 | 50 | We can see if a web server's [=response/statuses=] are reliable by [=/fetching=] a URL that should never result in an [=ok status=]. If the response status (after following redirects) is an [=ok status=], it's safe to conclude that the server is not configured properly. 51 | 52 | To test the reliability of an origin's response status codes given |origin|, run the following steps: 53 | 54 | 1. Let |p| be [=a new promise=]. 55 | 1. If |origin| is not a [=tuple origin=], [=reject=] |p| and return it. 56 | 1. Let |status reliability queue| be the result of [=starting a new parallel queue=]. 57 | 1. [=Enqueue the following steps=] to |status reliability queue|: 58 | 1. Let |url| be the result of calling {{URL(url, base)}} with url "/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200" and base |origin|. 59 | 1. Let |request| be a new [=/request=] whose [=request/url=] is |url|, [=request/method=] is `GET`, [=request/origin=] is |origin|, [=request/mode=] is `"same-origin"`, [=request/service-workers mode=] is `"none"`, [=request/credentials mode=] is `"omit"`, [=request/cache mode=] is `"no-store"`, and [=request/redirect mode=] is `"follow"`. 60 | 1. Let |response| be the result of performing a [=/fetch=] using |request|. 61 | 1. If |response| is a [=network error=], [=reject=] |p|. 62 | 1. If |response|'s [=response/status=] is an [=ok status=], [=reject=] |p|. Otherwise, [=/resolve=] |p|. 63 | 1. Return |p|. 64 | 65 |

IANA considerations

66 | 67 |

The `resource-that-should-not-exist-whose-status-code-should-not-be-200` well-known URI

68 | 69 | This document defines the “`.well-known`” URI `resource-that-should-not-exist-whose-status-code-should-not-be-200`. 70 | This registration will be submitted to the IESG for review, approval, and registration with IANA using the template defined in [[!WELL-KNOWN]] as follows: 71 | 72 | : URI suffix 73 | :: `resource-that-should-not-exist-whose-status-code-should-not-be-200` 74 | 75 | : Change controller 76 | :: W3C 77 | 78 | : Specification document(s) 79 | :: This document is the relevant specification. (See [[#semantics]]) 80 | 81 | : Related information: 82 | :: None. 83 | -------------------------------------------------------------------------------- /change-password-url.bs: -------------------------------------------------------------------------------- 1 | 
  2 | Title: A Well-Known URL for Changing Passwords
  3 | Shortname: change-password-url
  4 | Level: None
  5 | Status: ED
  6 | Group: WebAppSec
  7 | Repository: w3c/webappsec-change-password-url
  8 | URL: https://w3c.github.io/webappsec-change-password-url/
  9 | TR: https://www.w3.org/TR/change-password-url/
 10 | Editor: Ricky Mondello, w3cid 103933, Apple Inc. https://apple.com/, rmondello@apple.com
 11 | Editor: Theresa O'Connor, w3cid 40614, Apple Inc. https://apple.com/, hober@apple.com
 12 | Abstract: This specification defines a well-known URL that sites can use
 13 |  to make their change password forms discoverable by tools. This simple
 14 |  affordance provides a way for software to help the user find the way to
 15 |  change their password.
 16 | Complain About: accidental-2119 true
 17 | Markup Shorthands: idl yes, markdown yes
 18 |
19 | 
 20 | text:Location; type:dfn; spec:rfc7231; url:https://tools.ietf.org/html/rfc7231#section-7.1.2
 21 | text:refresh state; type:dfn; spec:html; url: https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-http-equiv-refresh
 22 | spec: UTS46; urlPrefix: https://www.unicode.org/reports/tr46/
 23 |     type: abstract-op; text: ToUnicode; url: #ToUnicode
 24 | spec: RESPONSE-CODE-RELIABILITY; type:dfn; text: test the reliability of an origin's response status codes; url: https://w3c.github.io/webappsec-change-password-url/response-code-reliability.html#test-the-reliability-of-an-origins-response-status-codes
 25 |
26 | 
 27 | {
 28 |     "HTTP-SEMANTICS": {
 29 |         "aliasOf": "RFC7231"
 30 |     },
 31 |     "IDNA": {
 32 |         "aliasOf": "UTS46"
 33 |     },
 34 |     "WELL-KNOWN": {
 35 |         "aliasOf": "RFC8615"
 36 |     },
 37 |     "RESPONSE-CODE-RELIABILITY":
 38 |     {
 39 |         "authors": ["Ricky Mondello", "Theresa O'Connor"],
 40 |         "href": "https://wicg.github.io/change-password-url/response-code-reliability.html",
 41 |         "publisher": "WICG",
 42 |         "status": "CG-DRAFT",
 43 |         "title": "Detecting the reliability of HTTP status codes"
 44 |     }
 45 | }
 46 |
47 | 
 48 | text:base;          type:argument;    spec:url
 49 | text:form;          type:element;     spec:html
 50 | text:Location;      type:http-header; spec:rfc7231
 51 | text:origin;        type:dfn;         spec:url;
 52 | text:request;       type:dfn;         spec:fetch; for:/
 53 | text:response;      type:dfn;         spec:fetch; for:/
 54 | text:URL;           type:interface;   spec:url
 55 | text:url;           type:argument;    spec:url
 56 |
57 | 58 |
59 | 60 |

Introduction

61 | 62 | This section is non-normative. 63 | 64 | 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. 65 | 66 | 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. 67 | 68 |
69 | 70 |

Infrastructure

71 | 72 | This specification depends on the Infra Standard. [[!INFRA]] 73 | 74 | This specification uses terminology from the 75 | Fetch, 76 | HTML, 77 | HTTP, and 78 | URL standards. [[!FETCH]] [[!HTML]] [[!HTTP-SEMANTICS]] [[!URL]] 79 | 80 |

Change Password URLs

81 | 82 | 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=]. 83 | 84 | Given an |origin|, clients generate a change password url by running these steps: 85 | 86 | 1. If |origin| is not a [=potentially trustworthy origin=], return failure. 87 | 88 | 2. Assert: |origin| is a [=tuple origin=]. 89 | 90 | 3. Let |url| be a new {{URL}} with values set as follows: 91 | 92 | : [=url/scheme=] 93 | :: |origin|'s [=origin/scheme=] 94 | : [=url/host=] 95 | :: |origin|'s [=origin/host=] 96 | : [=url/port=] 97 | :: |origin|'s [=origin/port=] 98 | : [=url/path=] 99 | :: « ".well-known", "change-password" ». 100 | 101 | 4. Return |url|. 102 | 103 |

The change password url for origin `"https://example.com/"` is `"https://example.com/.well-known/change-password"`. 104 | 105 | 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]] 106 | Clients must handle such redirects when requesting a [=change password url=]. 107 | 108 | Note: The above paragraph restricts servers to using temporary redirect codes. 109 | See Issue 13. 110 | 111 | If necessary, servers may respond with an HTML document containing an <{meta/http-equiv}> pragma directive in the [=refresh state=]. [[!HTML]] Clients should handle such redirects when requesting a [=change password url=]. 112 | 113 | Servers must not locate the actual change password page at the [=change password url=], per [[WELL-KNOWN#section-1.1|RFC8615 §1.1 Appropriate Use of Well-Known URIs]]. Clients must handle [=ok status=] responses when requesting a [=change password url=]. 114 | 115 | Note: Implementations might want to use [$ToUnicode$] when displaying 116 | [=change password url=]s. [[IDNA]] 117 | 118 | ISSUE: Make use of [=test the reliability of an origin's response status codes=] from [[!RESPONSE-CODE-RELIABILITY]]. 119 | 120 |

IANA considerations

121 | 122 |

The `change-password` well-known URI

123 | 124 | This document defines the “`.well-known`” URI `change-password`. 125 | This registration will be submitted to the IESG for review, approval, and registration with IANA using the template defined in [[!WELL-KNOWN]] as follows: 126 | 127 | : URI suffix 128 | :: change-password 129 | 130 | : Change controller 131 | :: W3C 132 | 133 | : Specification document(s) 134 | :: This document is the relevant specification. (See [[#semantics]]) 135 | 136 | : Related information: 137 | :: None. 138 | 139 |

Acknowledgements

140 | 141 | Thanks to 142 | Anne van Kesteren, 143 | Cl1608Ho, 144 | Dan Bernstein, 145 | David Singer, 146 | Dean Jackson, 147 | Florian Rivoal, 148 | John Wilander, 149 | Maciej Stachowiak, 150 | Mark Nottingham, 151 | Mike West, and 152 | Ricky Mondello 153 | for their feedback on this proposal. All of its features are theirs and all of its bugs are mine. 154 | --------------------------------------------------------------------------------