The IANA Well‑Known URI Registry

Every time a browser or service requests a resource at a path beginning with /.well-known/, it is tapping into a standardized, machine‑readable directory that was designed to make the web more discoverable and secure. The Internet Assigned Numbers Authority (IANA) maintains a public registry of these URIs, documenting the specification, status, and controlling body for each entry.

Why a Dedicated Namespace Matters

• Uniform discovery – Developers can rely on a single, predictable location to fetch configuration or metadata, reducing hard‑coded URLs.
• Security by design – Many entries expose information that can be leveraged by attackers (e.g., security.txt), but the registry also defines how to publish protective data (e.g., mta‑sts.txt).
• Interoperability – Protocols such as OAuth, OpenID Connect, and WebFinger use well‑known endpoints to negotiate capabilities without prior knowledge of the server’s layout.

A Quick Look at the Registry

URI Suffix	Specification	Status	Controller
acme-challenge	RFC8555	Permanent	IETF
assetlinks.json	Google’s Digital Asset Links	Permanent	Google Inc.
openid-configuration	OpenID Connect Discovery	Permanent	OpenID Foundation
security.txt	RFC9116	Permanent	IETF
mta-sts.txt	RFC8461	Permanent	IETF
webfinger	RFC7033	Permanent	IETF
oauth-authorization-server	RFC8414	Permanent	IESG
nodeinfo	Diaspora’s NodeInfo	Provisional	NodeInfo Developer Community
did.json	W3C Credentials Community Group	Provisional	Credentials Community Group

(Full list available at the IANA website.)

How to Use a Well‑Known URI in Your Project

Below is a minimal example of how a Go HTTP server can expose a security.txt file and how a client might fetch it:

// server.go
package main

import (
    "net/http"
)

func main() {
    http.HandleFunc("/.well-known/security.txt", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        w.Write([]byte("Contact: security@example.com\nExpires: 2026-12-31T23:59:59Z"))
    })
    http.ListenAndServe(":8080", nil)
}

# Client fetch
curl http://localhost:8080/.well-known/security.txt

The server’s response can be parsed by security tools to identify responsible parties and compliance dates.

The Evolution of the Registry

• Early days – The first entries, such as acme-challenge (RFC8555), were created to simplify automated certificate issuance.
• Growth in security – Entries like security.txt (RFC9116) and mta‑sts.txt (RFC8461) emerged as the web’s threat surface expanded.
• Identity and trust – The rise of decentralized identifiers (DIDs) and OAuth‑based federation has added did.json, openid-configuration, and oauth-authorization-server.
• Emerging standards – Provisional entries such as nodeinfo and did-configuration.json signal protocol pilots that may become permanent.

Implications for Developers

1. Reduced friction – By exposing configuration at a known path, services can auto‑discover capabilities, cutting onboarding time.
2. Security hygiene – Publishing security.txt or mta‑sts.txt becomes a best practice rather than an optional add‑on.
3. Interoperability testing – Automated tests can fetch well‑known resources to validate compliance with standards.
4. Future‑proofing – As new protocols adopt well‑known URIs, developers can adopt them with minimal changes to existing codebases.

Looking Ahead

The registry is already a living document; entries are added, updated, or deprecated as the web evolves. The IETF and W3C are actively working on new specifications (e.g., privacy-sandbox-attestations.json, gpc.json) that will further tighten privacy controls. For engineers, staying informed about the registry is not just a matter of curiosity—it is a prerequisite for building secure, interoperable, and standards‑compliant services.

Source: IANA Well‑Known URI Registry – https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml