Authentifizierung für Karten-APIs

Ein sicherer Entwurf für die Karten-API-Authentifizierung trennt Anmeldedaten nach Laufzeitumgebung. Ein Browser benötigt einen Schlüssel, der offengelegt werden darf und streng auf genehmigte Origins und Fähigkeiten beschränkt ist. Ein Backend benötigt einen geheimen Schlüssel, der nie in Clientcode gelangt und Server-zu-Server-Vorgänge autorisiert. Beide dürfen nicht austauschbar sein. Beschränken Sie Scopes, trennen Sie Umgebungen, überwachen Sie die Nutzung, rotieren Sie Schlüssel und unterscheiden Sie Authentifizierungs- von Autorisierungsfehlern. Kaleidr setzt dies mit veröffentlichbaren Browser-Schlüsseln (kld_pk_live_…) und Server-Schlüsseln (kld_sk_live_…) um.

Die folgenden Abschnitte behandeln Browser- und Server-Anmeldedaten, Origins, CORS, Scopes, Lebenszyklus, Mandantengrenzen und häufige Fehler. Produktdetails finden Sie in der Entwicklerdokumentation. Zur SDK-Architektur siehe Was ist ein KI-Karten-SDK?. Zu Einbettung und Chat-Mounts siehe Interaktive Karte einbetten und KI-Chat für Mapbox, Google Maps und MapLibre.

Grundlagen der Authentifizierung

• Laufzeit zuerst: Browser-Anmeldedaten sind zur Offenlegung bestimmt, Server-Anmeldedaten zur Geheimhaltung.
• Origin ≠ Authentifizierung: CORS und erlaubte Origins ersetzen keine Prüfung der Anmeldedaten.
• Scope ≠ Mandant: API-Scopes sind keine Benutzer- oder Zeilenautorisierung der Anwendung.
• Sicher rotieren: Stellen Sie einen Ersatz bereit, bevor Sie einen aktiven Schlüssel widerrufen.
• Logs schwärzen: Protokollieren Sie Schlüssel-IDs und Statuscodes, nie Schlüsselwerte.

Warum ist Karten-API-Authentifizierung im Browser anders?

Ein Browser ist eine nicht vertrauenswürdige Laufzeitumgebung. Alles, was an ihn ausgeliefert wird, lässt sich meist über Quelltext, Entwicklertools, Netzwerkanfragen, gebündeltes JavaScript, Browserspeicher oder Laufzeitobjekte untersuchen. Ein langlebiges Server-Geheimnis im Clientcode—React-Quelltext, Next.js-Variablen NEXT_PUBLIC_*, Vite-Variablen VITE_*, HTML, mobile Webviews oder Frontend-JSON—ist unsicher, da der Browser es nicht vor der ausführenden Person verbergen kann. Fragen Sie, was ein Schlüssel tun darf und wo er laufen darf, nicht wo er sich in einem Frontend-Bundle verstecken lässt.

Plattformen verwenden unterschiedliche Namen, das Muster ist jedoch üblich. Kaleidr nutzt veröffentlichbare und Server-Schlüssel (Auth & Scopes). Mapbox unterscheidet öffentliche und geheime Token-Scopes und verlangt Serveranfragen für geheime Token (Mapbox sicher verwenden). Google Maps Platform nutzt API-Schlüssel mit Anwendungs- und API-Beschränkungen und empfiehlt den Schutz von Webservice-Anmeldedaten sowie OAuth 2.0, wo dies für Serverzugriff unterstützt wird (Sicherheitsempfehlungen). Client-Schlüssel müssen für Offenlegung, Server-Schlüssel für Geheimhaltung entworfen sein.

Wie funktionieren veröffentlichbare und Server-Schlüssel von Kaleidr?

Die aktuelle Dokumentation definiert zwei Schlüsselformen für dasselbe Organisations- und Fähigkeitssystem. Veröffentlichbare Schlüssel tragen das Präfix kld_pk_live_… und werden in HTML, dem Kaleidr SDK, <kaleidr-map> und Browserintegrationen verwendet. Das SDK tauscht sie zur Laufzeit gegen eine kurzlebige, origin-gebundene Sitzung, statt die Zeichenfolge dauerhaft als Bearer-Schlüssel zu verwenden. Server-Schlüssel mit Präfix kld_sk_live_… gehören ausschließlich auf vertrauenswürdige Server, typischerweise als Authorization: Bearer … oder X-Api-Key: …. Sie sind im Browser gesperrt und erhalten keine CORS-Freigabe (CORS & Allowed Origins). Legen Sie nie einen Server-Schlüssel in Clientcode ab und behandeln Sie öffentliche Frontend-Umgebungsvariablen nicht als Geheimnisspeicher.

Erlaubte Origins müssen reine Origins ohne Pfad und abschließenden Schrägstrich sein, etwa https://app.example.com, nicht https://app.example.com/maps. Kaleidr verlangt derzeit HTTPS, außer bei lokalen Tests auf localhost oder 127.0.0.1. Exakter Abgleich ist wichtig: Root-, www-, App-, Admin- und Vorschau-Hosts sind verschiedene Origins. Origin-Beschränkungen verringern unbefugte Browsernutzung, ersetzen aber nicht das Fernhalten von Server-Geheimnissen aus dem Client.

Worin unterscheiden sich CORS, Authentifizierung, Scope und App-Autorisierung?

CORS steuert, ob ein Browser eine Cross-Origin-Antwort lesen darf. Authentifizierung identifiziert den Aufrufer. Scope-Autorisierung prüft, ob der Schlüssel eine Fähigkeit nutzen darf. Die Autorisierung der Host-Anwendung entscheidet, welcher Benutzer oder Mandant auf private Datensätze zugreifen darf. Kaleidrs CORS-Ablauf kann einen Preflight erlauben, gibt Access-Control-Allow-Origin aber nur für erlaubte Origins zurück; Server-Schlüssel erhalten keine Browser-CORS-Freigabe. 401 bedeutet meist fehlende, ungültige, abgelaufene oder widerrufene Anmeldedaten. 403 bedeutet meist gültige Anmeldedaten ohne Berechtigung; Kaleidr verwendet insufficient_scope, wenn die für eine Route nötige Fähigkeit fehlt. Behandeln Sie diese Fehler in Diagnose und Überwachung getrennt.

Wie sollten Schlüssel erstellt, gespeichert, rotiert und widerrufen werden?

Wenden Sie geringste Rechte an: Gewähren Sie jeder Integration nur benötigte Scopes. Mapbox empfiehlt minimale Token-Scopes und nur öffentliche Scopes im Browser; Google empfiehlt Anwendungsbeschränkungen plus Beschränkung auf tatsächlich verwendete APIs. Teilen Sie keinen Schlüssel zwischen Entwicklung, Vorschau und Produktion. Getrennte Schlüssel begrenzen den Schadensradius und erleichtern Rotation. Mapbox empfiehlt eigene Token je Umgebung oder Client, Google eigene API-Schlüssel je Anwendung (Token-Verwaltung).

Neue Kaleidr-Schlüsselwerte werden nur einmal angezeigt. Kopieren Sie sie sofort in einen Secret Manager. Server-Schlüssel gehören in einen Secret Manager oder eine geschützte serverseitige Umgebung, nie in öffentliche Repositories oder Browser-Bundles. Injizieren Sie Geheimnisse in CI/CD beim Deployment, maskieren Sie sie in Logs und drucken Sie keine Umgebungs-Dumps. Protokollieren Sie Schlüssel-ID, Status und Origin; schwärzen Sie Authorization-Header und Werte. Rotieren Sie durch Erstellen und Einschränken eines Ersatzes, Deployment, Verkehrsprüfung und erst dann Widerruf des alten Schlüssels—bei Kompromittierung schneller. Quoten sind ebenfalls Sicherheitskontrollen: Die Platform API misst Nutzung je Organisation, Streaming-Endpunkte begrenzen Parallelität (Quota & Rate Limits). Behandeln Sie 429 anders als 401 und 403; nutzen Sie Backoff statt Retry-Stürmen.

// Unsafe: never ship a server key to the browser
const SERVER_KEY = "YOUR_KALEIDR_SERVER_KEY";

// Safer browser pattern: publishable key + SDK session exchange
Kaleidr.mount("#map", {
  publishableKey: "kld_pk_live_REPLACE_ME"
});

// Safer backend pattern: server key stays on the host
const response = await fetch("https://api.example.com/resource", {
  headers: {
    Authorization: `Bearer ${process.env.KALEIDR_SERVER_KEY}`
  }
});

Wie trennen Produktionsanwendungen Plattform- und Host-Authentifizierung?

Ein empfohlenes Muster nutzt im Browser einen veröffentlichbaren Schlüssel für öffentliche SDK-Kartenfunktionen über einen genehmigten Origin; authentifizierte Produktanfragen gehen an das Host-Backend. Dieses verwaltet Benutzeridentität, Mandantenmitgliedschaft, Objektberechtigungen, private Standortdaten und einen Server-Schlüssel im Secret Manager. Es ruft die räumliche Plattform serverseitig auf und gibt nur freigegebene Felder zurück. Veröffentlichbare Schlüssel sind keine Endbenutzer-Authentifizierung, Server-Schlüssel keine Datenbank-Zeilenberechtigung. Laut aktueller Kaleidr-Dokumentation ist eine veröffentlichte Viewer-Karte durch einen Freigabelink geschützt und benötigt keinen API-Schlüssel. Behandeln Sie den Link dennoch als Zugriffskontrolle und liefern Sie private Daten nicht über eine uneingeschränkte öffentliche Ansicht aus. CSP und sichere HTML-Darstellung ergänzen dies; Mapbox warnt vor XSS durch nicht vertrauenswürdiges HTML in Pop-ups und empfiehlt Textdarstellung.

Welche Fehler sollten Teams vermeiden?

Bei Browserfehlern prüfen Sie Schreibweise des Origins, HTTPS, Schlüsseltyp, Scope und Reihenfolge des Sitzungsaustauschs, bevor Sie einen Plattformausfall vermuten. Bei Serverfehlern prüfen Sie Typ, Umgebung, Scope, Secret-Injektion und einen versehentlichen Widerruf während der Rotation.

Fazit

Karten-API-Sicherheit beginnt mit einer Architekturentscheidung: Verwenden Sie nicht dasselbe Schlüsselmodell für Browser und Backend. Browserintegrationen brauchen offenlegbare, durch Origin, Scope, Sitzungsdauer oder gleichwertige Anbieterregeln beschränkte Schlüssel. Backendintegrationen brauchen Geheimnisse in vertrauenswürdiger Infrastruktur. Ergänzen Sie geringste Rechte, Umgebungstrennung, Anwendungsautorisierung, Überwachung und Rotation. Kaleidrs aktuelles Modell folgt diesem Muster: veröffentlichbare Schlüssel sind origin-beschränkt und werden vom SDK gegen kurzlebige Sitzungen getauscht; Server-Schlüssel sind Bearer-Schlüssel für Server-zu-Server-Aufrufe und im Browser gesperrt. Diese Grenze ist wichtiger als der Versuch, einen Schlüssel im Frontend zu verstecken.

Sichern Sie Ihre Karten-API mit der Kaleidr-Dokumentation

Prüfen Sie vor dem Deployment aktuelle Schlüsseltypen, Scopes, Origin-Regeln und API-Verhalten. Kaleidr Auth & Scopes lesen erklärt Browser- und Server-Schlüssel; die Entwicklerdokumentation enthält SDK-Mounts und Platform-API-Routen.

Häufig gestellte Fragen

Was ist Karten-API-Authentifizierung?

Sie identifiziert eine Anwendung oder einen Dienst, der auf Karten-, Orts-, Kachel-, Routing- oder räumliche APIs zugreift. Übliche Mechanismen sind API-Schlüssel, Zugriffstoken, Sitzungen, Bearer-Token und OAuth.

Kann ein API-Schlüssel sicher im Browser verwendet werden?

Nur wenn der Anbieter ihn ausdrücklich für Clientnutzung entwirft. Er benötigt Beschränkungen wie erlaubte Origins, öffentliche Scopes, App-Beschränkungen oder kurzlebigen Sitzungsaustausch. Ein Server-Geheimnis gehört nie in Browsercode.

Ist ein veröffentlichbarer API-Schlüssel geheim?

Nein. Seine Sicherheit darf nicht davon abhängen, dass die Zeichenfolge verborgen bleibt. Beschränkungen und Überwachung sind dennoch nötig.

Ist ein Server-API-Schlüssel geheim?

Ja. Er muss in vertrauenswürdiger Backend-Infrastruktur bleiben und darf nicht in HTML, JavaScript-Bundles, Webviews, öffentlichen Repositories oder Clientspeicher erscheinen.

Ist CORS Authentifizierung?

Nein. CORS steuert, ob ein Browser Cross-Origin-Antworten lesen darf. Authentifizierung identifiziert den Aufrufer; Autorisierung bestimmt seine Rechte.

Was ist der Unterschied zwischen 401 und 403?

401 bedeutet meist fehlende, ungültige, abgelaufene oder widerrufene Anmeldedaten. 403 bedeutet meist gültige Anmeldedaten ohne Berechtigung für den Vorgang.

Sollte ich getrennte API-Schlüssel für Entwicklung und Produktion erstellen?

Ja. Das verkleinert den Schadensradius, vereinfacht Origin-Regeln, verbessert die Nutzungsübersicht und macht Rotation sicherer.

Wie rotiere ich einen API-Schlüssel?

Erstellen und beschränken Sie einen Ersatz, stellen Sie ihn bereit, prüfen Sie den Produktionsverkehr und widerrufen Sie erst dann den alten Schlüssel. Bei aktiver Kompromittierung handeln Sie schneller.

Benötigt Kaleidr Viewer einen API-Schlüssel?

Laut aktueller Dokumentation sind veröffentlichte Viewer-Karten durch Freigabelinks geschützt und benötigen keinen API-Schlüssel.

Wie schützt Kaleidr Browserintegrationen?

Das aktuelle Modell verwendet einen veröffentlichbaren Schlüssel mit Origin-Allowlist. Das SDK tauscht ihn gegen eine kurzlebige, origin-gebundene Sitzung. Server-Schlüssel sind im Browser gesperrt und für Server-zu-Server-Aufrufe vorgesehen.

Quellen

• IETF. HTTP Semantics (RFC 9110). RFC Editor. Abgerufen am 17. August 2026. https://www.rfc-editor.org/rfc/rfc9110

• IETF. The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). RFC Editor. Abgerufen am 17. August 2026. https://www.rfc-editor.org/rfc/rfc6750

• WHATWG. Fetch Standard. Abgerufen am 17. August 2026. https://fetch.spec.whatwg.org/#http-cors-protocol

• Google. Sicherheitsempfehlungen für Google Maps Platform. Dokumentation der Google Maps Platform. Abgerufen am 17. August 2026. https://developers.google.com/maps/api-security-best-practices

• Kaleidr. Auth & Scopes. Kaleidr-Entwicklerdokumentation. Abgerufen am 17. August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes

• Kaleidr. CORS & Allowed Origins. Kaleidr-Entwicklerdokumentation. Abgerufen am 17. August 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins

• Kaleidr. Quota & Rate Limits. Kaleidr-Entwicklerdokumentation. Abgerufen am 17. August 2026. https://docs.kaleidr.com/platform-api/quota-and-rate-limits

• Mapbox. Mapbox sicher verwenden. Mapbox-Dokumentation. Abgerufen am 17. August 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/

• Mapbox. Token-Verwaltung. Mapbox-Dokumentation. Abgerufen am 17. August 2026. https://docs.mapbox.com/accounts/guides/tokens/

@misc{ietf_rfc9110_2026,
  title  = {HTTP Semantics (RFC 9110)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc9110}
}

@misc{ietf_rfc6750_2026,
  title  = {The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc6750}
}

@misc{whatwg_fetch_cors_2026,
  title  = {Fetch Standard},
  author = {{WHATWG}},
  note   = {CORS protocol; accessed 17 August 2026},
  url    = {https://fetch.spec.whatwg.org/#http-cors-protocol}
}

@misc{kaleidr_auth_scopes_2026,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_cors_origins_2026,
  title  = {CORS and Allowed Origins},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/cors-and-allowed-origins}
}

@misc{kaleidr_quota_2026,
  title  = {Quota and Rate Limits},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/quota-and-rate-limits}
}

@misc{mapbox_token_management_2026,
  title  = {Token Management},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/accounts/guides/tokens/}
}

@misc{mapbox_secure_2026,
  title  = {How to Use Mapbox Securely},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/}
}

@misc{google_maps_security_2026,
  title  = {Google Maps Platform Security Guidance},
  author = {{Google}},
  note   = {Accessed 17 August 2026},
  url    = {https://developers.google.com/maps/api-security-best-practices}
}