본문으로 건너뛰기

Content Security Policy

Kaleidr SDK는 고객 페이지에서 실행됩니다. 따라서 고객 페이지의 Content Security Policy는 각 product가 로드하는 resource를 허용해야 합니다. 이 페이지가 해당 설정 방법을 제공합니다.

제품별​

Tile 및 Viewer (iframe product)​

Tile과 Viewer는 실제 지도를 map-embed.kaleidr.com 내부의 Kaleidr 자체 CSP 아래에서 로드합니다. parent page는 iframe 자체와 SDK loader만 허용하면 됩니다:

default-src 'self';
script-src  'self' https://cdn.kaleidr.com;
frame-src   https://map-embed.kaleidr.com;
connect-src 'self' https://api.kaleidr.com;

Tile 또는 Viewer만 임베드하는 경우 parent page에서 Mapbox / MapTiler / OSM / vendor image host를 허용할 필요가 없습니다 — 해당 리소스는 Kaleidr iframe 안에서 사용됩니다.

Chat 및 Editor (in-page attach)​

Chat과 Editor는 parent document 안에 MapLibre를 mount합니다. parent page CSP는 MapLibre와 SDK가 실제로 로드하는 모든 host를 허용해야 합니다:

default-src 'self';
script-src  'self' 'wasm-unsafe-eval' https://cdn.kaleidr.com;
style-src   'self' 'unsafe-inline' https://cdn.kaleidr.com;
connect-src 'self'
            https://api.kaleidr.com
            https://api.mapbox.com https://events.mapbox.com
            https://api.maptiler.com
            https://*.tiles.mapbox.com;
img-src     'self' data: blob:
            https://api.mapbox.com https://*.tiles.mapbox.com
            https://api.maptiler.com
            https://*.tile.openstreetmap.org;
worker-src  'self' blob:;
font-src    'self' data:;

'wasm-unsafe-eval'이 필요합니다 — MapLibre는 runtime에 WebAssembly를 compile하므로 이 값이 없으면 실패합니다. CSP에서 'wasm-unsafe-eval'을 금지한다면 현재는 Chat 또는 Editor를 in-page mount할 수 없습니다.

가장 먼저 문제가 생기는 부분​

증상누락되었을 가능성이 높은 directive
SDK loader가 404를 반환하거나 차단됨script-src https://cdn.kaleidr.com
MapLibre init 실패(Chat/Editor)script-src의 'wasm-unsafe-eval'
Tile이 빈 화면 / 회색으로 표시됨vendor host용 connect-src 및/또는 img-src
Iframe이 전혀 렌더링되지 않음(Tile / Viewer)frame-src https://map-embed.kaleidr.com
Console에서 session exchange가 4xxCSP 문제가 아님 — Auth & scopes의 origin allowlist 확인

Nonce 및 hash​

MapLibre가 inline <style> block을 생성하기 때문에 위 style-src에 'unsafe-inline'이 포함되어 있습니다. 현재 CSP가 'unsafe-inline'을 금지한다면 nonce를 사용하고 해당 nonce 아래에서 style을 다시 생성하세요 — SDK는 현재 load별 nonce를 발급하지 않습니다. 필요하다면 kaleidr-sdk에 issue를 열어주세요.

Report-only rollout​

이 policy를 안전하게 적용하는 방법은 다음과 같습니다:

  1. 위 block을 일주일 동안 자체 report-uri와 함께 Content-Security-Policy-Report-Only로 설정합니다.
  2. violation report에 나타나는 host를 올바른 directive에 추가합니다.
  3. report가 더 이상 발생하지 않으면 header를 Content-Security-Policy로 전환합니다.