HTTP-APIs authentifizieren Aufrufer mit einem Credential im Authorization-Header — einem API-Key oder bearer token (Authorization: Bearer <token>). Stärkere Verfahren signieren jeden Request mit HMAC über einen kanonischen Request, sodass Credentials nie wiederholbar sind, nutzen OAuth 2.0 Client-Credentials für Machine-to-Machine-Tokens und ergänzen mutual TLS, wo Identität auf Transportebene erforderlich ist.
Bearer tokens und API-Keys
Die einfachste Authentifizierung ist ein bearer-Credential: der Client präsentiert ein geheimes Token im Authorization-Header und der Server validiert es. RFC 9110 definiert den Authorization-Header und sein Schema-Präfix, und OAuth 2.0 definiert das Bearer-Schema — Authorization: Bearer <token> —, dessen entscheidende Eigenschaft ist, dass bereits der Besitz Zugriff gewährt; das Token darf daher nur über TLS reisen und nie in einer URL, einem Log oder einer Fehlermeldung erscheinen. Ein API-Key ist dieselbe Idee mit einem langlebigeren, oft nicht ablaufenden Secret. Weil ein bearer-Credential bei Abfangen wiederholbar ist, ist es die Basislinie, nicht die Obergrenze: es ist leicht zu integrieren und über TLS für die meiste Last völlig ausreichend, aber hochwertige Operationen legen oft Request-Signierung darüber.
POST /v1/messages HTTP/1.1
Host: api.example
Authorization: Bearer eyJhbGciOi... # secret; TLS only, never logged
Content-Type: application/jsonHMAC-Request-Signierung
Request-Signierung hebt die Messlatte: statt das Secret zu senden, nutzt der Client es, um ein HMAC über eine kanonische Repräsentation des Requests zu berechnen, und sendet nur die Signatur. Der Server, der dasselbe Secret hält, berechnet die Signatur neu und vergleicht. Weil die Signatur die Methode, den Pfad, Schlüssel-Header und einen Hash des Bodys abdeckt, kann eine abgefangene Signatur nicht gegen einen anderen Request abgespielt werden, und weil das Secret selbst den Client nie verlässt, verrät das Abfangen eines Requests das Credential nicht. Die Konstruktion spiegelt die Webhook-Signierung in umgekehrter Richtung und ist dasselbe HMAC-SHA256-Primitiv (RFC 2104 / RFC 6234). Der heikle Teil ist der kanonische Request: beide Seiten müssen sich Byte für Byte einig sein, wie er serialisiert wird, sonst weicht jede Signatur ab.
canonical =
HTTP-METHOD + '\n' +
URI-PATH + '\n' +
SORTED-QUERY + '\n' +
SIGNED-HEADERS (name:value, sorted, '\n'-joined) + '\n' +
HEX(SHA256(raw_body))
signature = HMAC_SHA256(secret, canonical)
Authorization: SIGV1 Credential=<key-id>,
SignedHeaders=host;x-date;content-type, Signature=<hex>Signierte Header und das Request-Datum
Zwei Details machen die Request-Signierung solide. Erstens benennt eine explizite SignedHeaders-Liste genau, welche Header abgedeckt sind, sodass ein Intermediär, der unbeteiligte Header hinzufügt oder umordnet, die Signatur nicht ungültig macht, während jeder vom Client gewählte signierte Header manipulationssicher ist. Zweitens ist ein Request-Datum (ein signiertes X-Date oder der Standard-Date-Header) Teil des kanonischen Requests und wird innerhalb einer Toleranz gegen die Server-Uhr geprüft — dieselbe Replay-Abwehr wie bei webhooks, angewandt auf eingehende API-Aufrufe. Zusammen bedeuten sie, dass ein signierter Request an seinen exakten Inhalt, seine deklarierten Header und ein enges Zeitfenster gebunden ist; ein abgefangener Request ist wenige Minuten später nutzlos.
Key-Scoping und -Rotation
Credentials sollten das geringste funktionierende Privileg tragen und ohne Ausfallzeit rotierbar sein. Scoping heftet einem Key Berechtigungen an — welche Operationen er aufrufen darf, von welcher Quelle, mit welcher Rate —, sodass ein Key, der nur Nachrichten sendet, keine Kontoeinstellungen lesen kann und der Schadensradius eines geleakten Keys begrenzt ist. Die Rotation folgt dem Muster überlappender Keys: ein neues Credential ausgeben, beide parallel laufen lassen, während Clients migrieren, dann das alte widerrufen, sodass nichts mitten im Flug bricht. Keys sollten identifizierbar sein (eine nicht geheime Key-ID reist im Request, damit der Server weiß, gegen welches Secret er verifizieren und welches Scope er anwenden muss) und einzeln widerrufbar, sodass eine kompromittierte Integration abgeschnitten wird, ohne die übrigen zu stören.
| Schema | Was übertragen wird | Stärke / Verwendung |
|---|---|---|
| API-Key | Langlebiges Geheimnis im Authorization-Header | Einfache Grundlage; nur mit TLS; leicht in Logs offengelegt |
| Bearer-Token (OAuth 2.0) | Kurzlebiges Zugriffstoken | Ablaufend, mit Scope; Erneuerung über den Token-Endpunkt |
| HMAC-Anfragesignierung | Signatur (Geheimnis bleibt lokal) | Pro Anfrage replay-resistent und manipulationserkennbar |
| mTLS | Client-X.509-Zertifikat | Identität auf Transportebene; stark, aber aufwendigerer Betrieb |
Mutual TLS
Mutual TLS authentifiziert den Client auf der Transportebene: zusätzlich dazu, dass der Server ein Zertifikat präsentiert, präsentiert der Client während des Handshakes sein eigenes X.509-Zertifikat, und der Server lässt nur Verbindungen zu, deren Zertifikat auf eine vertrauenswürdige CA zurückführt und einer eingetragenen Identität entspricht. Das bindet die API-Identität an einen auf Verbindungsebene verwalteten kryptografischen Schlüssel statt an ein bearer-Secret in einem Header, was für hochsichere Machine-to-Machine-Verbindungen und zum Pinnen eines Partners auf bestimmte Zertifikate attraktiv ist. Der Preis ist betrieblich — Zertifikatsausstellung, -verteilung, -rotation und -widerruf —, daher ist mTLS typischerweise den sensibelsten Integrationen vorbehalten, oft kombiniert mit einem bearer token oder einer Signatur für feingranulare Autorisierung über der groben Transport-Identität.
OAuth 2.0 Client-Credentials für M2M
Für Server-zu-Server-Integrationen ohne anwesenden Endnutzer definiert OAuth 2.0 (RFC 6749) den Client-Credentials-Grant. Der Client authentifiziert sich an einem Token-Endpoint mit seiner client_id und seinem client_secret (oder einem Client-Zertifikat) und erhält ein kurzlebiges Access-Token, das er dann als bearer token bei API-Aufrufen präsentiert, bis es abläuft und erneuert wird. Der Vorteil gegenüber einem statischen API-Key ist Lebensdauer und Scope: Tokens sind kurzlebig, sodass ein abgefangenes Token schnell abläuft, und sie tragen explizite Scopes, sodass ein zum Senden ausgestelltes Token nicht das Konto administrieren kann. Dies ist das Standardmuster für Machine-to-Machine-API-Zugriff und der Mechanismus, den BroadNets Authentifizierungsleitfaden konkret für seine Endpunkte dokumentiert.
POST /oauth/token HTTP/1.1
Host: auth.example
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<id>
&client_secret=<secret>
&scope=messages:send
-> { "access_token": "...", "token_type": "Bearer",
"expires_in": 3600, "scope": "messages:send" }Häufig gestellte Fragen
Was ist der Unterschied zwischen einem bearer token und HMAC-Signierung?
Ein bearer token wird bei jedem Request gesendet und gewährt Zugriff durch Besitz, sodass ein abgefangenes Token bis zum Ablauf wiederholbar ist. HMAC-Signierung sendet das Secret nie — der Client signiert einen kanonischen Request und sendet nur die Signatur, sodass ein abgefangener Request nicht gegen einen anderen Aufruf abgespielt werden kann und das Credential selbst nie offengelegt wird.
Warum braucht HMAC-Signierung einen kanonischen Request?
Weil beide Seiten denselben String berechnen müssen, um übereinstimmende Signaturen zu erhalten. Der kanonische Request legt genau fest, wie Methode, Pfad, sortierte Query, signierte Header und Body-Hash serialisiert werden. Jede Abweichung — Header-Reihenfolge, Whitespace, ein neu codierter Body — erzeugt eine andere Signatur, und der Request wird abgewiesen, obwohl nichts manipuliert wurde.
Was gibt mir OAuth 2.0 Client-Credentials gegenüber einem API-Key?
Kurze Lebensdauer und explizites Scope. Der Client tauscht seine Credentials an einem Token-Endpoint gegen ein kurzlebiges, gescoptes Access-Token (RFC 6749). Ein abgefangenes Token läuft schnell ab, und ein zum Senden ausgestelltes Token kann das Konto nicht administrieren. Ein statischer API-Key ist demgegenüber langlebig und meist breit.
Wie sollten API-Keys gescopt und rotiert werden?
Gewähren Sie das geringste Privileg — beschränken Sie jeden Key auf die Operationen, Quellen und Rate, die er braucht —, sodass ein Leak eingedämmt ist. Rotieren Sie mit überlappenden Keys: ein neues Credential ausgeben, beide parallel laufen lassen, während Clients migrieren, dann das alte widerrufen. Keys sollten eine nicht geheime Key-ID tragen und einzeln widerrufbar sein, sodass eine kompromittierte Integration allein abgeschnitten wird.
Wann ist mutual TLS den betrieblichen Aufwand wert?
Wenn Sie kryptografische Identität auf Transportebene für eine hochsichere Machine-to-Machine-Verbindung brauchen oder einen Partner auf bestimmte Zertifikate pinnen wollen. mTLS lässt nur Clients zu, deren X.509-Zertifikat auf eine vertrauenswürdige CA zurückführt. Es ist aufwändiger im Betrieb — Ausstellung, Rotation, Widerruf —, daher meist den sensibelsten Integrationen vorbehalten, oft mit einem Token oder einer Signatur zur Autorisierung überlagert.
Warum dürfen bearer-Credentials nie in einer URL oder einem Log erscheinen?
Weil ein bearer-Credential Zugriff allein durch Besitz gewährt. URLs werden von Proxys geloggt, in der Browser-Historie gespeichert und über den Referer-Header geleakt, und Anwendungslogs sind weithin lesbar, sodass ein Token in einem davon faktisch offengelegt ist. Bearer-Credentials dürfen nur im Authorization-Header über TLS reisen und müssen aus Logs entfernt werden.
Quellenspezifikationen
Diese Seite basiert auf den veröffentlichten Standards. (Wird in einem neuen Tab geöffnet.)