Content Security Policy
Sendet Ihre Website einen Content-Security-Policy-Header, blockiert der Browser alles, was diese Richtlinie nicht ausdrücklich erlaubt – auch Skripte, Frames und Anfragen von Kaleidr. Hier stehen die nötigen Freigaben für jedes Produkt. Ohne einen solchen Header benötigen Sie diese Seite nicht.
Welche Freigaben nötig sind, hängt vom Ausführungsort des Produkts ab:
| Produkt | Ausführung | Ihre Richtlinie muss zulassen |
|---|---|---|
| Viewer | In einem von Kaleidr gehosteten iframe | Das Loader-Skript und den Frame. |
| Tile | In einem von Kaleidr gehosteten iframe | Den Loader, die Sitzungsanfrage und den Frame. |
| Chat | Direkt auf Ihrer Seite | Loader-Skript, API-Anfragen, eingefügte Styles, eingebettete Schriftarten und Bilder. |
| Editor | Auf Ihrer Seite mit eigener Karte | Alles Genannte sowie den Basiskartenhost, Karten-Worker und Kartenbilder. |
Bei den zwei iframe-Produkten unterliegen die Karte und ihre Ressourcen der eigenen Kaleidr-Richtlinie im Frame, nicht Ihrer. Deshalb sind die nötigen Freigaben kurz.
Die Hosts
| Host | Bereitgestellte Ressourcen | Verwendet von |
|---|---|---|
https://cdn.kaleidr.com | kaleidr.js und die geladenen Produkt-Bundles (chat.js, viewer.js, editor.js, tile.js). | Alle Produkte bei Verwendung des SDK. |
https://api.kaleidr.com | Sitzungsaustausch und Chat-Anfragen während der Antworten. | Chat, Editor, Tile. |
https://map-embed.kaleidr.com | Die im Viewer- und Tile-iframe dargestellte Seite. | Viewer, Tile. |
https://tile.kaleidr.com | Die im Editor dargestellte Basiskarte: Stil, Kacheln, Sprites und Schriftarten. | Editor. |
Für Kaleidr-Produkte müssen keine Hosts von Mapbox, MapTiler oder OpenStreetMap freigegeben werden. Frühere Fassungen nannten sie; diese Einträge können entfernt werden. Nutzt Ihre Seite eine eigene Karte, müssen deren Hosts weiterhin erlaubt bleiben.
Viewer
Mit dem SDK-Element oder Kaleidr.mount:
script-src https://cdn.kaleidr.com;
frame-src https://map-embed.kaleidr.com;
Mit dem einfachen iframe-Code aus Studio wird kein Skript benötigt:
frame-src https://map-embed.kaleidr.com;
Viewer benötigt keinen connect-src-Eintrag, weil ein Viewer ohne Schlüssel keine Anfrage von Ihrer Seite ausführt.
Tile
script-src https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
frame-src https://map-embed.kaleidr.com;
connect-src erlaubt den Sitzungsaustausch, den das SDK mit Ihrem öffentlichen Schlüssel vor der Erstellung des Frames durchführt.
Chat
script-src https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
style-src 'unsafe-inline';
font-src data:;
img-src data: https:;
| Anweisung | Grund |
|---|---|
script-src https://cdn.kaleidr.com | Loader und chat.js. |
connect-src https://api.kaleidr.com | Sitzungsaustausch sowie jede Frage und Antwort. |
style-src 'unsafe-inline' | Chat fügt dem Dokumentkopf ein <style>-Element ohne Nonce hinzu. |
font-src data: | Chat-Schriftarten sind als data:-URLs im Bundle eingebettet. |
img-src data: | Chat-Symbole sind als data:-URLs eingebettet. |
img-src https: | Ortskarten zeigen Fotos von wechselnden Bildhosts, die hier nicht vollständig aufgelistet werden können. Bei einem engeren img-src bleiben Fotos nicht zugelassener Hosts aus. |
img-src https: (Websitesymbole) | Links in Antworten und Websites auf Ortskarten zeigen das Website-Symbol. Es kommt über Googles Favicon-Dienst unter https://www.google.com mit Weiterleitungen an https://t0.gstatic.com bis https://t3.gstatic.com. Bei engerem img-src müssen https://www.google.com und https://*.gstatic.com zugelassen sein. Sonst fehlen die Symbole, die Links funktionieren jedoch weiterhin. |
Das Chat-Bundle enthält keine Kartenbibliothek und benötigt kein 'wasm-unsafe-eval'. Es zeichnet auf Ihrer vorhandenen Karte. Behalten Sie deshalb alle von Ihrer Kartenbibliothek geforderten Freigaben bei: ihren Skripthost, Kachel- und Stilhosts in connect-src und img-src sowie worker-src blob: für Mapbox GL JS und MapLibre GL JS.
Steuert Chat statt Ihrer eigenen Karte ein Kaleidr-Viewer- oder Tile-Element, ergänzen Sie dessen Anweisungen, insbesondere frame-src https://map-embed.kaleidr.com.
Editor
script-src 'self' https://cdn.kaleidr.com;
style-src 'self' 'unsafe-inline';
connect-src 'self' https://api.kaleidr.com https://tile.kaleidr.com;
img-src 'self' data: blob: https://tile.kaleidr.com;
worker-src blob:;
font-src 'self' data:;
| Anweisung | Grund |
|---|---|
script-src https://cdn.kaleidr.com | Loader und editor.js. |
style-src 'unsafe-inline' | Editor fügt Stylesheets per JavaScript ohne Nonce ins Dokument ein. |
connect-src https://api.kaleidr.com | Sitzungsaustausch. |
connect-src https://tile.kaleidr.com | Basiskartenstil, Kacheln, Sprites und Beschriftungsschriften, die der Editor von Ihrer Seite aus lädt. |
img-src data: blob: https://tile.kaleidr.com | Kartenbilder und Symbole; die Karte erzeugt Bilder aus blob:- und data:-URLs. |
worker-src blob: | Die Karten-Worker laufen aus blob:-URLs. |
font-src data: | Editor-Schriftarten sind als data:-URLs eingebettet. |
'wasm-unsafe-eval' gehört nicht zur Standardliste. Fügen Sie es nur dann zu script-src hinzu, wenn die Konsole meldet, dass Ihre Richtlinie die WebAssembly-Kompilierung von editor.js (dem 3D-Modelldecoder) blockiert.
Wenn Sie mit styleId eine vollständige Stil-URL übergeben, erlauben Sie zusätzlich die Hosts dieses Stils in connect-src und img-src.
Mehrere Produkte auf einer Seite
Kombinieren Sie die Listen. Eine Seite mit einer Tile-Karte und einem Chatfenster, das sie steuert, benötigt:
script-src https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
frame-src https://map-embed.kaleidr.com;
style-src 'unsafe-inline';
font-src data:;
img-src data: https:;
Eine vollständige Richtlinie
Die Blöcke oben zeigen, was Kaleidr ergänzt. Eine echte Richtlinie muss auch Ihre eigenen Ressourcen zulassen. Dies ist ein vollständiger Header für eine Website, die alle anderen Ressourcen von ihrem eigenen Ursprung liefert und Viewer sowie Tile einbettet:
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.kaleidr.com; connect-src 'self' https://api.kaleidr.com; frame-src https://map-embed.kaleidr.com; style-src 'self' 'unsafe-inline'
style-src 'unsafe-inline' steht in diesem Beispiel aus einem Grund, der nicht den Kaleidr-Code betrifft: Die Dokumentationsbeispiele geben Elementhöhen mit dem Inline-Attribut style="display:block; height:480px" an. Eine Richtlinie ohne 'unsafe-inline' ignoriert solche Inline-Style-Attribute. Wenn Sie Inline-Stile blockieren möchten, legen Sie die Höhe in Ihrem Stylesheet fest:
kaleidr-map { display: block; height: 480px; }
Die vom SDK festgelegte iframe-Größe ist davon nicht betroffen: Sie wird per Skript gesetzt und nicht von der Style-Richtlinie blockiert. Ebenso bleibt das Standardverhalten display:block des Elements bestehen. Es wird weder durch einen <style>-Tag noch ein style-Attribut bereitgestellt und benötigt daher kein 'unsafe-inline'.
Nonces, Hashes und strict-dynamic
- Skripte. Der Loader fügt jedes Produkt-Bundle als
<script src>-Element hinzu. Ein hostbasiertesscript-srcerlaubt es. Verwendet Ihre Richtlinie einen Nonce zusammen mit'strict-dynamic', setzen Sie diesen auf den Loader-Tag. Die von ihm hinzugefügten Skripte gelten dann über'strict-dynamic'als vertrauenswürdig und der Host-Eintrag ist entbehrlich. - Stile. Für die von Chat und Editor eingefügten Styles lässt sich dem SDK kein Nonce geben. Ihr Inhalt ändert sich mit Releases, daher kann auch kein Hash fixiert werden. Beide Produkte benötigen
'unsafe-inline'instyle-src. Viewer und Tile fügen Ihrer Seite keine Styles hinzu. - Integrität. Fügen Sie dem Loader-Tag kein
integrity-Attribut hinzu. Die Datei wird am selben Ort aktualisiert. Siehe CDN-Versionierung.
Erkennen blockierter Ressourcen
Jede Blockierung erscheint mit der auslösenden Anweisung in der Browserkonsole. Vergleichen Sie sie mit dieser Tabelle.
| Symptom | Genannte Anweisung | Ergänzen |
|---|---|---|
Nichts wird eingebunden. Kaleidr is not defined. | script-src | https://cdn.kaleidr.com in script-src. |
Das Element bleibt leer. Konsole: [kaleidr:<product>] [kaleidr] failed to load …/embed/v1/<product>.js | script-src | Denselben Host. Der Loader war etwa per Hash zugelassen, das Bundle aber nicht. |
| Viewer oder Tile zeigt ein leeres Feld. | frame-src (oder child-src oder default-src) | https://map-embed.kaleidr.com in frame-src. |
Tile, Chat oder Editor startet nicht; Anfrage sessions wird blockiert. | connect-src | https://api.kaleidr.com in connect-src. |
| Das Chatfenster hat keine Styles. | style-src | 'unsafe-inline' in style-src. |
| Chat-Symbole oder Schriftarten fehlen. | img-src, font-src | data: in beiden. |
| Ortsfotos oder Symbole neben Links fehlen. | img-src | https: in img-src oder die in der Konsole genannten Hosts. |
| Editor-Panels erscheinen, aber die Karte bleibt leer. | connect-src, worker-src oder img-src | https://tile.kaleidr.com in connect-src und img-src; blob: in worker-src und img-src. |
| Editor erscheint ungestaltet. | style-src | 'unsafe-inline' in style-src. |
Das Element ignoriert die Höhe seines style-Attributs. | style-src | Nichts; Höhe per Stylesheet festlegen. |
Nicht jeder Fehler liegt an der Richtlinie. Wird die Anfrage sessions gesendet und mit 401, 403 oder 429 beantwortet, hat die Richtlinie sie zugelassen und die API sie abgelehnt. Siehe Fehler und CORS und zulässige Ursprünge.
Einführung im Report-Only-Modus
So ergänzen Sie Kaleidr in einer strengen Richtlinie, ohne die produktive Seite zu unterbrechen:
- Senden Sie die neue Richtlinie als
Content-Security-Policy-Report-Onlyneben der bestehenden und an einen eigenen Meldeendpunkt. - Testen Sie die Einbettung: Seite laden, Karte bewegen und Chat-Fragen nach Orten mit Fotos stellen.
- Ergänzen Sie die in den Berichten auftauchenden Quellen in den dort genannten Anweisungen. Vor allem Ortsfotos bringen neue Bildhosts.
- Wenn keine Verstöße mehr gemeldet werden, wechseln Sie zu
Content-Security-Policy.
Nicht benötigte Freigaben
- Hosts von Mapbox, MapTiler oder OpenStreetMap für Kaleidr-Produkte.
'unsafe-inline'inscript-src. Der Loader fügt Produktpakete als<script src>-Elemente hinzu, nie als Inline-Skripte.frame-ancestors. Diese Anweisung steuert, wer Ihre Seite einrahmen darf, nicht, was Ihre Seite einrahmen darf.- Einträge für Vorgänge innerhalb der Viewer- oder Tile-iframes.