What Are .well-known URIs?

If you've ever configured an OAuth server, set up a federated identity system, or checked a site's security policy, you've likely encountered a .well-known URI. These special URL paths — defined under RFC 8615 — provide a standardized location for web services to expose metadata, configuration, and discovery information.

Rather than scattering configuration endpoints across arbitrary URLs, .well-known gives developers and clients a predictable location to find critical information about any domain.

How .well-known Works

The concept is simple: any resource a server wants to advertise as "well-known" lives under the path /.well-known/ on the domain. For example:

  • https://example.com/.well-known/openid-configuration — OpenID Connect discovery
  • https://example.com/.well-known/security.txt — Security contact information
  • https://example.com/.well-known/nodeinfo — Fediverse/ActivityPub server metadata
  • https://example.com/.well-known/webfinger — Resource discovery for federated identity
  • https://example.com/.well-known/assetlinks.json — Android app-to-domain linking

The IANA maintains an official registry of all recognized suffixes, ensuring they don't collide with one another.

Key .well-known Standards You Should Know

1. OpenID Connect Discovery (openid-configuration)

This is arguably the most widely deployed .well-known endpoint. It publishes a JSON document describing an OAuth 2.0/OpenID Connect provider's capabilities — including authorization endpoints, supported scopes, token signing keys, and more. Any compliant client can auto-configure itself by fetching this single URL.

2. WebFinger (webfinger)

WebFinger (RFC 7033) allows clients to discover information about a resource using a URI. It's the backbone of federated identity in the Fediverse — when you follow someone on Mastodon from a different instance, WebFinger is used to locate their profile data across servers.

3. security.txt (security.txt)

Defined in RFC 9116, security.txt lets organizations publish vulnerability disclosure policies and security contact information. It's a simple text file that security researchers can find without digging through websites.

4. NodeInfo (nodeinfo)

Used by federated social platforms, NodeInfo exposes metadata about a server: what software it runs, how many users it has, and which protocols it supports. This powers the discovery layer of the Fediverse.

Implementing a .well-known Endpoint

Setting up a .well-known resource is straightforward on any web server. Here's a basic example for serving a static JSON file with nginx:

location /.well-known/ {
  root /var/www/well-known;
  default_type application/json;
  add_header Access-Control-Allow-Origin *;
}

The Access-Control-Allow-Origin: * header is important — many clients fetch these resources from browser contexts and need CORS access.

Why .well-known Matters for the Decentralized Web

In a decentralized ecosystem where no central authority governs discovery, standardized endpoints like .well-known become essential infrastructure. They allow:

  1. Auto-discovery — Clients find server capabilities without prior configuration
  2. Interoperability — Different software implementations can talk to each other
  3. Trust establishment — Servers prove ownership and publish policies at known locations
  4. Federation — Decentralized networks link accounts and resources across domains

Best Practices

  • Always serve .well-known resources over HTTPS
  • Set appropriate Cache-Control headers — most discovery documents change infrequently
  • Include CORS headers for browser-based clients
  • Register custom suffixes with IANA if you're creating a new standard
  • Validate your endpoints with tools like the WebFinger lookup tool

Understanding .well-known URIs is foundational to working with modern open-web protocols. Whether you're building a federated social app, an OAuth provider, or a security disclosure program, these endpoints are where the decentralized web introduces itself.