A Well-Known URL for Passkey Endpoints

Editor’s Draft,

More details about this document
This version:
https://w3c.github.io/webappsec-passkey-endpoints/passkey-endpoints.html
Feedback:
public-webappsec@w3.org with subject line “[passkey-endpoints] … message topic …” (archives)
Issue Tracking:
GitHub
Editor:
(Microsoft)

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

This specification defines a well-known URL which WebAuthn Relying Parties (RPs) can host to make their creation and management endpoints discoverable by WebAuthn clients and authenticators.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Changes to this document may be tracked at https://github.com/w3c/webappsec.

The (archived) public mailing list public-webappsec@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “passkey-endpoints” in the subject, preferably like this: “[passkey-endpoints] …summary of comment…”

This document was produced by the Web Application Security Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

This section is non-normative.

WebAuthn Relying Parties (RPs) currently lack a way to programmatically advertise that they support passkeys, where a user can create a passkey, and where they can manage existing passkeys. By proposing a well-known URL which defines a set of passkey-specific endpoints, this specification enables WebAuthn clients and authenticators to link directly to workflow-specific endpoints instead of the user needing to dig through their account settings.

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. Passkey Endpoints URLs

To advertise support for passkeys and/or provide direct endpoints for passkey creation and management, Relying Parties MUST host a JSON document at the path formed by concatenating the string .well-known/passkey-endpoints with the https scheme and relying party identifier as per [WELL-KNOWN]. A redirect MUST not be returned.

The passkey endpoints URL for RP ID "example.com" is "https://example.com/.well-known/passkey-endpoints".

3.1. Server Response

The server in this context is a WebAuthn Relying Party supporting passkeys.

A successful response MUST use the 200 OK HTTP status code and return a JSON object using the application/json content type.

The returned JSON object can contain any of the members defined below.

enroll

This OPTIONAL member contains a direct URL to the passkey creation page for a user account

manage

This OPTIONAL member contains a direct URL to the passkey management page for a user account

HTTP/1.1 200 OK
Content-Type: application/json

{
   "enroll": "https://example.com/account/manage/passkeys/create",
   "manage": "https://example.com/account/manage/passkeys"
}

An empty JSON object CAN be returned to signal support for passkeys, but not advertise specific endpoints.

HTTP/1.1 200 OK
Content-Type: application/json

{}

3.2. Client Processing

A client in this context can be either a WebAuthn client or an authenticator.

Given a passkey’s relying party identifier, generate a passkey endpoints URL by running these steps:

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

    scheme

    "https"

    host

    the passkey’s relying party identifier

    port

    null

    path

    « ".well-known", "passkey-endpoints" ».

  2. Return url.

The passkey endpoints URL for RP ID "example.com" is "https://example.com/.well-known/passkey-endpoints".

4. IANA considerations

4.1. The passkey-endpoints well-known URI

This document defines the ".well-known" URI passkey-endpoints. 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

passkey-endpoints

Change controller

W3C

Specification document(s)

This document is the relevant specification. (See § 3.1 Server Response)

Related information:

None.

Acknowledgements

Thanks to

for their feedback on this proposal.

Conformance

Document conventions

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.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by reference

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.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP Semantics. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9110.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://datatracker.ietf.org/doc/html/rfc2119
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WEBAUTHN-2]
Jeff Hodges; et al. Web Authentication: An API for accessing Public Key Credentials - Level 2. URL: https://w3c.github.io/webauthn/
[WEBAUTHN-3]
Michael Jones; Akshay Kumar; Emil Lundberg. Web Authentication: An API for accessing Public Key Credentials - Level 3. URL: https://w3c.github.io/webauthn/
[WELL-KNOWN]
M. Nottingham. Well-Known Uniform Resource Identifiers (URIs). May 2019. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8615