What Is the .well-known Directory?

Defined in RFC 8615, the /.well-known/ URI prefix is a reserved location on any web server where applications, protocols, and security tools expect to find standardized metadata files. Instead of every protocol inventing its own discovery path, they all converge on this single, predictable namespace.

Think of it as a standardized "lobby directory" for your web server — other software can look here to understand your site's capabilities, policies, and configuration without any prior knowledge of your application structure.

Why .well-known Matters for Security

Many critical security and identity workflows depend on automatic discovery. When your browser, an identity provider, or a security scanner needs to understand how your server operates, it shouldn't require human configuration. The .well-known directory makes this machine-to-machine communication reliable and standardized.

Key .well-known Files Explained

security.txt (RFC 9116)

Located at /.well-known/security.txt, this file tells security researchers how to responsibly disclose vulnerabilities in your systems. A well-formed security.txt includes:

  • Contact: An email or URL for vulnerability reports
  • Expires: An ISO date after which the file should not be trusted
  • Encryption: A PGP key for secure communications
  • Policy: A link to your responsible disclosure policy

Without this file, researchers often can't find a verified way to report issues — and may resort to public disclosure instead.

openid-configuration

Identity providers that support OpenID Connect publish their metadata at /.well-known/openid-configuration. This JSON document (also called the "discovery document") contains everything a client needs to interact with the provider:

  • The authorization endpoint URL
  • The token endpoint URL
  • The JWKS (JSON Web Key Set) URI for token validation
  • Supported grant types, scopes, and signing algorithms

This is how your application can automatically configure itself when you specify just an issuer URL — no manual endpoint wiring required.

oauth-authorization-server

Similar to the OIDC discovery document but defined specifically for OAuth 2.0 authorization servers (RFC 8414). It serves the same purpose for pure OAuth flows that don't use OpenID Connect identity semantics.

change-password

A simple redirect target at /.well-known/change-password, this tells password managers and browsers where to send users who want to update their password. Supporting this URL makes browser "change your password" prompts work correctly with your application.

apple-app-site-association / assetlinks.json

Used by iOS and Android respectively for Universal Links and App Links. These files prove domain ownership and authorize mobile apps to handle links from your domain, enabling seamless deep linking without browser redirects.

A Quick Reference Table

Path Purpose Standard
/.well-known/security.txt Vulnerability disclosure contact info RFC 9116
/.well-known/openid-configuration OIDC provider metadata discovery OpenID Connect Discovery
/.well-known/oauth-authorization-server OAuth 2.0 server metadata RFC 8414
/.well-known/change-password Password change redirect WICG Spec
/.well-known/jwks.json Public keys for JWT verification RFC 7517

How to Implement .well-known on Your Server

  1. Create a .well-known directory at your web root (note the leading dot).
  2. Ensure your web server serves this directory — some servers block dot-directories by default.
  3. Add the appropriate files with correct MIME types (most are application/json or text/plain).
  4. Test discoverability with tools like curl https://yourdomain.com/.well-known/security.txt.

Properly maintaining your .well-known directory is a low-effort, high-signal indicator that your team takes web standards and security seriously.