/.well-known/ erklärt: Webserver-Metadateien

Das „Schwarze Brett" Ihres Webservers: Leitfaden zu /.well-known/-Metadateien

Was ist /.well-known/ – und warum sollten Sie es kennen?

Stellen Sie sich vor, ein Bürogebäude hätte im Eingangsbereich ein schwarzes Brett – nicht für Mieter gedacht, sondern ausschließlich für offizielle Hinweise an Besucher: Notausgänge, Sicherheitsbeauftragte, Hausregeln. Genau das ist /.well-known/ für Ihren Webserver: ein reservierter Bereich, den Browser, Bots, Apps und APIs automatisch abrufen – ohne dass ein Mensch eingreifen muss.

Der Namespace ist durch RFC 8615 (Mai 2019, Mark Nottingham) standardisiert und ersetzt den ursprünglichen RFC 5785 (2010). Die IANA pflegt das offizielle Register mit über 100 Einträgen: iana.org/assignments/well-known-uris

Wichtige Grundregeln:

• /.well-known/security.txt ist gültig – /blog/.well-known/security.txt ist es nicht (gilt nur am Origin-Root).
• Unterstützte Schemes: HTTP, HTTPS, WebSocket (ws/wss), CoAP.
• Statuswerte im IANA-Register: permanent, provisional, obsoleted.

# Apache: Schreibzugriff per WebDAV/PUT sperren
<Directory "/.well-known">
  <LimitExcept GET HEAD OPTIONS>
    Require all denied
  </LimitExcept>
</Directory>

Kategorie 1: Sicherheit & Zertifikate

/.well-known/acme-challenge Aufwand: automatisch · kein Aufwand bei cPanel

RFC 8555 · permanent

Wenn Sie bei FORMALITY ein kostenloses SSL-Zertifikat über Let's Encrypt beantragen, läuft im Hintergrund automatisch die ACME HTTP-01-Challenge ab. Seit Ende 2015 wurden damit inzwischen Milliarden Zertifikate ausgestellt – der meistgenutzte Well-Known-Pfad weltweit.

Ablauf:

1. ACME-Client legt Token-Datei unter /.well-known/acme-challenge/<TOKEN> ab.
2. CA ruft die Datei über plain HTTP (Port 80) ab – HTTPS ist bewusst nicht erlaubt.
3. Response Body = <TOKEN>.<Account-Key-Thumbprint>
4. CA bestätigt Domainbesitz, stellt Zertifikat aus. Token-Datei wird gelöscht.

# Token-Datei (plain text, kein JSON)
Pfad:    /.well-known/acme-challenge/YnVzaW5lc3M
                        Inhalt:  YnVzaW5lc3M.k3nABDE8F1Gf9q7zNpT2x_Rv0WsHiJmLcOuYXeQC4dZ

# Certbot Apache
certbot --apache -d example.com -d www.example.com
# Certbot Nginx
certbot --nginx -d example.com
# Dry-Run Test
certbot renew --dry-run
# Standalone (Port 80 frei)
                        certbot certonly --standalone -d example.com

# Apache .htaccess: ACME-Verzeichnis von HTTPS-Redirect ausnehmen
RewriteEngine On
RewriteCond %{REQUEST_URI} !^/.well-known/acme-challenge/
RewriteCond %{HTTPS} off
                        RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

# Nginx
server {
    listen 80;
    server_name example.com;
    location /.well-known/acme-challenge/ {
        root /var/www/html;
        default_type text/plain;
    }
    location / {
        return 301 https://$host$request_uri;
    }
                        }

# Validierung
                        curl -si http://example.de/.well-known/acme-challenge/test-token

# Apache: Empfohlene Response-Header
<Location "/.well-known/acme-challenge/">
  Header set Content-Type "text/plain"
  Header set Cache-Control "no-store"
</Location>

/.well-known/security.txt Aufwand: 5 min · kein Technikwissen nötig

RFC 9116 · permanent

security.txt ist der „Notausgang"-Wegweiser für Sicherheitslücken: eine maschinenlesbare Kontaktdatei, die Sicherheitsforschern und Bug-Bounty-Reportern sofort zeigt, wohin sie sich wenden sollen. BSI und ENISA empfehlen sie ausdrücklich für alle Behörden und Unternehmen.

Pflichtfelder: Contact:, Expires: (ISO 8601)
Optional: Encryption:, Acknowledgments:, Policy:, Preferred-Languages:, Canonical:, Hiring:, CSAF:

# Minimal
Contact: mailto:security@example.de
            Expires: 2026-12-31T23:59:59+00:00

# Vollständig mit allen optionalen Feldern
Contact: mailto:security@example.de
Contact: https://example.de/security/report
Expires: 2026-12-31T23:59:59+00:00
Encryption: https://example.de/.well-known/openpgpkey/security-pgp.asc
Acknowledgments: https://example.de/security/hall-of-fame
Policy: https://example.de/security/disclosure-policy
Preferred-Languages: de, en
Canonical: https://example.de/.well-known/security.txt
Hiring: https://example.de/jobs
CSAF: https://example.de/.well-known/csaf/provider-metadata.json

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Contact: mailto:security@example.de
Expires: 2026-12-31T23:59:59+00:00
Canonical: https://example.de/.well-known/security.txt
Preferred-Languages: de, en
-----BEGIN PGP SIGNATURE-----
[... PGP-Signatur ...]
                        -----END PGP SIGNATURE-----

# Apache: Empfohlene Response-Header
<Files "security.txt">
  Header set Content-Type "text/plain; charset=utf-8"
  Header set Cache-Control "public, max-age=3600"
  Header set X-Content-Type-Options "nosniff"
                        </Files>

# Validierung
curl -si https://example.de/.well-known/security.txt | head -20

/.well-known/mta-sts.txt Aufwand: 30 min · DNS-Zugang erforderlich

RFC 8461 · permanent

Wichtig: Die Datei muss auf der Subdomain mta-sts.<domain> liegen und benötigt einen ergänzenden DNS-TXT-Record.

# Policy-Datei: https://mta-sts.example.de/.well-known/mta-sts.txt
version: STSv1
mode: enforce
mx: mail.example.de
mx: *.example.de
            max_age: 604800

# DNS-TXT-Record
_mta-sts.example.de.  IN TXT  "v=STSv1; id=20240101120000Z"
# TLSRPT: Fehlerberichte per E-Mail
_smtp._tls.example.de.  IN TXT  "v=TLSRPTv1; rua=mailto:tls-reports@example.de"

# MTA-STS ID automatisch per Timestamp generieren (Shell)
MTA_STS_ID=$(date -u +"%Y%m%d%H%M%SZ")
echo "v=STSv1; id=${MTA_STS_ID}"

# Validierung
curl -si https://mta-sts.example.de/.well-known/mta-sts.txt

/.well-known/sbom Hinweis: Compliance-relevant

RFC 9472 · permanent

Eine Software Bill of Materials (SBOM) ist ein maschinenlesbares Inventar aller Softwarekomponenten – vergleichbar mit einem Zutatenverzeichnis für Software. Besonders relevant für Compliance-Anforderungen.

{
  "spdxVersion": "SPDX-2.3",
  "dataLicense": "CC0-1.0",
  "SPDXID": "SPDXRef-DOCUMENT",
  "name": "example-webserver",
  "documentNamespace": "https://example.de/sbom/2024-01",
  "packages": [
    {
      "SPDXID": "SPDXRef-nginx",
      "name": "nginx",
      "versionInfo": "1.25.3",
      "downloadLocation": "https://nginx.org",
      "filesAnalyzed": false
    }
  ]
}

Content-Type: application/spdx+json oder application/vnd.cyclonedx+json

Kategorie 2: Identität & Authentifizierung

/.well-known/openid-configuration Hinweis: für SSO-Betreiber

OpenID Connect Core 1.0 · permanent

Jede Anwendung, die sich per „Login mit Google" oder eigenem SSO anmeldet, nutzt diese Datei. Der Client fragt hier automatisch nach: Wo bekomme ich ein Token? Welche Scopes werden unterstützt?

{
  "issuer": "https://auth.example.de",
  "authorization_endpoint": "https://auth.example.de/oauth/authorize",
  "token_endpoint": "https://auth.example.de/oauth/token",
  "userinfo_endpoint": "https://auth.example.de/oauth/userinfo",
  "jwks_uri": "https://auth.example.de/.well-known/jwks.json",
  "response_types_supported": ["code", "token", "id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "ES256"],
  "scopes_supported": ["openid", "email", "profile"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
            }

# jwks.json – öffentliche Schlüssel für Token-Verifikation
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "2024-01",
      "alg": "RS256",
      "n": "sA6pQ8...[base64url-Modulus]...",
      "e": "AQAB"
    }
  ]
            }

# Validierung
curl -s https://auth.example.de/.well-known/openid-configuration | python3 -m json.tool

/.well-known/oauth-authorization-server Hinweis: für OAuth-Betreiber

RFC 8414 · permanent

Das OAuth-2.0-Pendant zur OpenID-Configuration – ohne OIDC-spezifische Felder. Wird von reinen OAuth-2.0-Servern ohne OpenID-Connect-Erweiterung genutzt.

{
  "issuer": "https://auth.example.de",
  "authorization_endpoint": "https://auth.example.de/authorize",
  "token_endpoint": "https://auth.example.de/token",
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "private_key_jwt"],
  "revocation_endpoint": "https://auth.example.de/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"]
}

/.well-known/webfinger Hinweis: für Fediverse & Identitätsplattformen

RFC 7033 · permanent

WebFinger ist der Mechanismus hinter dem Fediverse: Wenn Sie auf Mastodon einer Person folgen, fragt Ihr Server via WebFinger nach, wo das ActivityPub-Profil zu finden ist.

# Request
GET /.well-known/webfinger?resource=acct:alice@mastodon.social
Host: mastodon.social
Accept: application/jrd+json
# Response
{
  "subject": "acct:alice@mastodon.social",
  "aliases": [
    "https://mastodon.social/@alice",
    "https://mastodon.social/users/alice"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://mastodon.social/@alice"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://mastodon.social/users/alice"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://mastodon.social/authorize_interaction?uri={uri}"
    }
  ]
            }

# Validierung
curl -s "https://example.de/.well-known/webfinger?resource=acct:user@example.de" | python3 -m json.tool

Kategorie 3: App-Verlinkung & Mobile

/.well-known/apple-app-site-association Aufwand: 60 min · Apple Developer Account nötig

Apple Developer Docs · permanent

Stellen Sie sich diese Datei als „offiziellen Hausausweis" vor: Apple prüft beim App-Install auf dem Gerät, ob die Website wirklich zur App gehört – bevor HTTPS-Links direkt in der App geöffnet werden dürfen (Universal Links).

Zwingend: Keine Dateiendung · kein gzip · Content-Type: application/json

// Minimal
{
  "applinks": {
    "details": [
      {
        "appIDs": ["A1B2C3D4E5.com.example.app"],
        "components": [
          { "/": "/kunden/*" }
        ]
      }
    ]
  }
            }

// Vollständig: Universal Links + App Clips + Web Credentials + Ausschlüsse
{
  "applinks": {
    "details": [
      {
        "appIDs": ["A1B2C3D4E5.com.example.app"],
        "components": [
          { "/": "/kunden/bestellung/*", "comment": "Bestellverfolgung öffnet App" },
          { "/": "/kunden/rechnung/*", "comment": "Rechnungen in App" },
          { "/": "/support/ticket?id=*", "comment": "Support-Tickets" },
          { "/": "/", "exclude": true, "comment": "Startseite immer im Browser" },
          { "/": "/blog/*", "exclude": true, "comment": "Blog immer im Browser" }
        ]
      }
    ]
  },
  "appclips": { "apps": ["A1B2C3D4E5.com.example.app.clip"] },
  "webcredentials": { "apps": ["A1B2C3D4E5.com.example.app"] }
}

# Apache .htaccess
<Files "apple-app-site-association">
    Header set Content-Type "application/json"
    SetEnv no-gzip 1
    SetEnv dont-vary 1
                        </Files>

# Nginx
location = /.well-known/apple-app-site-association {
    default_type application/json;
    gzip off;
    add_header Cache-Control "public, max-age=3600";
                        }

# Validierung: Content-Type prüfen
curl -I https://example.de/.well-known/apple-app-site-association
# gzip prüfen (darf NICHT gzip-codiert sein)
curl -I https://example.de/.well-known/apple-app-site-association | grep -i "content-encoding"
# JSON-Struktur prüfen
curl -s https://example.de/.well-known/apple-app-site-association | python3 -m json.tool

/.well-known/assetlinks.json Aufwand: 30 min · Android-Entwicklerkonto nötig

Google / Android App Links · permanent

Das Android-Pendant zur Apple AASA-Datei. Benötigt den SHA-256-Fingerprint des App-Signing-Zertifikats (aus Android Studio oder der Google Play Console).

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "de.example.app",
      "sha256_cert_fingerprints": [
        "A1:B2:C3:D4:E5:F6:G7:H8:I9:J0:K1:L2:M3:N4:O5:P6:Q7:R8:S9:T0:U1:V2:W3:X4:Y5:Z6:00:11:22:33:44:55"
      ]
    }
  }
            ]

# Validierung
adb shell am start -a android.intent.action.VIEW -d 'https://example.de' de.example.app

/.well-known/change-password Aufwand: 5 min · kein Technikwissen nötig

WHATWG Well-Known URL · permanent

# Apache .htaccess
            RedirectMatch 301 ^/.well-known/change-password$ /kunden/passwort-aendern

# Nginx
location = /.well-known/change-password {
    return 301 /kunden/passwort-aendern;
            }

<?php
// PHP-Fallback
header('Location: /kunden/passwort-aendern', true, 301);
exit;
            ?>

# Validierung
curl -I https://example.de/.well-known/change-password

Kategorie 4: Protokoll-Discovery & Infrastruktur

/.well-known/caldav & /.well-known/carddav Aufwand: 10 min · cPanel-Zugang

RFC 6764 · permanent

Ohne diese Weiterleitungen müssen Nutzer von Apple Kalender oder Thunderbird den Servernamen manuell eingeben. Mit diesen Pfaden reicht E-Mail-Adresse und Passwort – der Client findet den Server automatisch.

# Apache .htaccess
RedirectMatch 301 ^/.well-known/caldav$  https://caldav.example.de/calendars/
            RedirectMatch 301 ^/.well-known/carddav$ https://carddav.example.de/addressbooks/

# Nginx
location = /.well-known/caldav  { return 301 https://caldav.example.de/calendars/; }
            location = /.well-known/carddav { return 301 https://carddav.example.de/addressbooks/; }

# DNS SRV-Records für maximale Client-Kompatibilität
_caldavs._tcp.example.de.  IN SRV  0 1 443 caldav.example.de.
            _carddavs._tcp.example.de. IN SRV  0 1 443 carddav.example.de.

# Validierung
curl -I https://example.de/.well-known/caldav

/.well-known/autoconfig/mail/config-v1.1.xml Aufwand: 15 min · für E-Mail-Hoster

Mozilla Autoconfig · de facto (nicht im IANA-Register)

<?xml version="1.0" encoding="UTF-8"?>
<clientConfig version="1.1">
  <emailProvider id="example.de">
    <domain>example.de</domain>
    <displayName>FORMALITY Mail</displayName>
    <displayShortName>FORMALITY</displayShortName>
    <!-- IMAP -->
    <incomingServer type="imap">
      <hostname>mail.example.de</hostname>
      <port>993</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <!-- POP3 (optional) -->
    <incomingServer type="pop3">
      <hostname>mail.example.de</hostname>
      <port>995</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <!-- SMTP -->
    <outgoingServer type="smtp">
      <hostname>mail.example.de</hostname>
      <port>587</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>
  </emailProvider>
</clientConfig>

/.well-known/nodeinfo Hinweis: für Fediverse-Instanzen

NodeInfo 2.0 · permanent

// Stufe 1: /.well-known/nodeinfo (Link-Dokument)
{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.1",
      "href": "https://mastodon.example/nodeinfo/2.1"
    }
  ]
}
// Stufe 2: Payload unter /nodeinfo/2.1
{
  "version": "2.1",
  "software": { "name": "mastodon", "version": "4.2.8" },
  "protocols": ["activitypub"],
  "usage": {
    "users": { "total": 1250, "activeMonth": 340, "activeHalfyear": 780 },
    "localPosts": 45200
  },
  "openRegistrations": false
}

/.well-known/matrix Hinweis: für Matrix-Homeserver

Matrix Spec · permanent

{
  "m.homeserver": { "base_url": "https://matrix.example.de" },
  "m.identity_server": { "base_url": "https://identity.example.de" }
}

/.well-known/pvd Hinweis: für ISPs & VPN-Betreiber

RFC 8801 · permanent

{
  "identifier": "example.de",
  "expires": "2025-12-31T23:59:59Z",
  "prefixes": ["203.0.113.0/24", "2001:db8::/32"],
  "dnsZones": ["example.de"],
  "reachable-prefixes": ["0.0.0.0/0"],
  "no-default-route": false
}

Kategorie 5: Traffic-Steuerung & Performance

/.well-known/traffic-advice Aufwand: 5 min · für contentintensive Websites

WICG Draft · provisional (kein offizieller RFC)

Diese JSON-Datei teilt Chromium-basierten Browsern mit, ob und wie aggressiv sie Links im Hintergrund vorladen dürfen. Besonders relevant für Seiten mit kostenpflichtigen Inhalten oder Besucher mit mobilen Tarifen.

// Alles erlauben (Standard – Datei kann fehlen)
[{"user_agent": "*"}]
// Alles verbieten
[{"user_agent": "*", "disallow": true}]
// Nur 10 % der Prefetch-Anfragen erlauben
[{"user_agent": "prefetch-proxy", "fraction": 0.1}]
// Differenziert nach Bot-Typ
[
  {"user_agent": "prefetch-proxy", "disallow": true},
  {"user_agent": "googlebot",      "disallow": false},
  {"user_agent": "*",              "fraction": 0.5}
]

Kategorie 6: Nicht im IANA-Register, aber im Web üblich

/robots.txt & /sitemap.xml Aufwand: 10 min · Site-Root, nicht /.well-known/

RFC 9309 / sitemaps.org

# robots.txt (liegt unter /robots.txt, NICHT unter /.well-known/)
User-agent: *
Disallow: /admin/
Disallow: /kunden/
Allow: /
User-agent: GPTBot
Disallow: /
            Sitemap: https://example.de/sitemap.xml

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.de/</loc>
    <lastmod>2024-01-15</lastmod>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>
</urlset>

/.well-known/apple-developer-merchantid-domain-association Hinweis: für Apple Pay

# Apache .htaccess
<Files "apple-developer-merchantid-domain-association">
    Header set Content-Type "text/plain"
    SetEnv no-gzip 1
</Files>

/.well-known/pki-validation/ Aufwand: 5 min · für SSL-Validierung via CA

# Pfad: /.well-known/pki-validation/AB1234CD.txt
A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2
comodoca.com
EF567890

/.well-known/related-website-set.json Hinweis: für Multi-Domain-Organisationen

{
  "primary": "https://example.de",
  "associatedSites": ["https://example.com", "https://example.cloud"],
  "serviceSites": ["https://cdn.example.de", "https://assets.example.de"],
  "rationaleBySite": {
    "https://example.com": "Gleiche Organisation, anderes TLD",
    "https://example.cloud": "Cloud-Produktlinie von FORMALITY"
  }
}

/.well-known/keybase.txt Aufwand: 5 min · Keybase-Account nötig

### Keybase proof
I hereby claim:
  * I am on keybase under the username example-user
  * I have a public key whose fingerprint is A1B2 C3D4 ...
To claim this, I am signing this object:
...[base64-signiertes JSON]...

/.well-known/api-catalog neu: Dezember 2024

RFC 9727 · permanent

{
  "apis": [
    {
      "title": "FORMALITY Hosting API",
      "description": "Verwaltung von Domains, DNS und Hosting-Paketen",
      "openapi": "https://api.example.de/v2/openapi.json",
      "base-url": "https://api.example.de/v2",
      "tags": ["hosting", "dns", "domains"]
    },
    {
      "title": "FORMALITY Mail API",
      "description": "Postfächer, Weiterleitungen, Spam-Regeln",
      "openapi": "https://api.example.de/mail/openapi.json",
      "base-url": "https://api.example.de/mail",
      "tags": ["email", "spam", "mailbox"]
    }
  ]
}

Welche Dateien brauche ich wirklich?

Glossar

RFC

Request for Comments – offizielles Standarddokument der IETF, das Internet-Protokolle und -Standards definiert.

IANA

Internet Assigned Numbers Authority – Behörde, die IP-Adressen, Protokollnummern und Well-Known-URI-Suffixe verwaltet und registriert.

ACME

Automatic Certificate Management Environment – Protokoll (RFC 8555) zur automatischen Ausstellung und Erneuerung von TLS-Zertifikaten, genutzt von Let's Encrypt.

STARTTLS

Erweiterungskommando für E-Mail-Protokolle (SMTP, IMAP), das eine unverschlüsselte Verbindung nachträglich auf TLS-Verschlüsselung hochstuft.

JRD

JSON Resource Descriptor – JSON-basiertes Format (RFC 7033) für WebFinger-Antworten, das Service-URLs zu einer Identität beschreibt.

SHA-256

Kryptografische Hashfunktion aus der SHA-2-Familie, die einen 256-Bit-Fingerabdruck erzeugt – genutzt z. B. zur Verifikation von App-Signing-Zertifikaten.

Content-Type

HTTP-Header, der dem Client mitteilt, in welchem Format die Antwort vorliegt (z. B. application/json oder text/plain).

gzip

Komprimierungsverfahren für HTTP-Antworten – beschleunigt die Übertragung, muss aber für bestimmte Dateien (z. B. AASA) explizit deaktiviert werden.