콘텐츠 보안 정책
사이트가 Content-Security-Policy 헤더를 보내면 브라우저는 그 정책에서 허용하지 않는 모든 항목을 차단합니다. Kaleidr의 스크립트, iframe 및 요청도 포함됩니다. 이 페이지는 제품별로 허용해야 할 항목을 안내합니다. 헤더가 없다면 이 설정은 필요하지 않습니다.
필요한 허용 항목은 제품이 실행되는 위치에 따라 달라집니다:
| 제품 | 실행 위치 | 정책에서 허용할 항목 |
|---|---|---|
| Viewer | Kaleidr가 호스팅하는 iframe 내부 | 로더 스크립트와 프레임. |
| Tile | Kaleidr가 호스팅하는 iframe 내부 | 로더, 세션 요청, 프레임. |
| Chat | 사용자 페이지 안 | 로더, API 요청, 삽입된 스타일, 내장 글꼴과 이미지. |
| Editor | 자체 지도가 있는 사용자 페이지 안 | 위 항목 전부와 베이스맵 호스트, 지도 워커, 지도 이미지. |
두 iframe 제품의 지도와 그 안에서 불러오는 자료는 외부 페이지의 정책이 아닌 iframe 내부의 Kaleidr 정책을 따릅니다. 그래서 허용 목록이 짧습니다.
호스트
| 호스트 | 제공하는 리소스 | 사용 제품 |
|---|---|---|
https://cdn.kaleidr.com | kaleidr.js와 제품 번들(chat.js, viewer.js, editor.js, tile.js). | SDK를 사용하는 모든 제품. |
https://api.kaleidr.com | 세션 교환과 Chat 답변 과정의 요청. | Chat, Editor, Tile. |
https://map-embed.kaleidr.com | Viewer와 Tile iframe 내부에서 실행되는 페이지. | Viewer, Tile. |
https://tile.kaleidr.com | Editor 내부 지도의 베이스맵: 스타일, 타일, 스프라이트, 글꼴. | Editor. |
Kaleidr 제품에 는 Mapbox, MapTiler 또는 OpenStreetMap 호스트를 허용할 필요가 없습니다. 이전 문서에 있던 항목은 제거해도 됩니다. 단, 페이지에서 자체 지도를 사용한다면 해당 지도가 필요로 하는 호스트는 계속 허용해야 합니다.
Viewer
SDK 요소 또는 Kaleidr.mount 사용 시:
script-src https://cdn.kaleidr.com;
frame-src https://map-embed.kaleidr.com;
Studio의 단순 iframe 코드를 사용할 경우 스크립트가 필요 없습니다:
frame-src https://map-embed.kaleidr.com;
키 없이 마운트된 Viewer는 페이지에서 요청을 보내지 않으므로 connect-src 항목이 필요 없습니다.
Tile
script-src https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
frame-src https://map-embed.kaleidr.com;
connect-src는 SDK가 iframe을 만들기 전에 공개 가능 키로 수행하는 세션 교환을 허용합니다.
Chat
script-src https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
style-src 'unsafe-inline';
font-src data:;
img-src data: https:;
| 지시문 | 이유 |
|---|---|
script-src https://cdn.kaleidr.com | 로더와 chat.js. |
connect-src https://api.kaleidr.com | 세션 교환과 모든 질문·답변. |
style-src 'unsafe-inline' | Chat이 문서 head에 nonce 없는 <style> 요소를 추가합니다. |
font-src data: | Chat 글꼴은 번들에 data: URL로 내장되어 있습니다. |
img-src data: | Chat 아이콘은 data: URL로 내장되어 있습니다. |
img-src https: | 장소 카드 사진은 장소마다 다른 이미지 호스트에서 불러오므로 여기 모두 나열할 수 없습니다. img-src를 제한하면 허용되지 않은 호스트의 사진은 표시되지 않습니다. |
img-src https:(사이트 아이콘) | 답변 링크와 장소 카드의 웹사이트에는 해당 사이트 아이콘이 표시됩니다. Google favicon 서비스 https://www.google.com에서 가져오며 https://t0.gstatic.com부터 https://t3.gstatic.com으로 리디렉션됩니다. 제한적인 img-src라면 https://www.google.com과 https://*.gstatic.com을 허용해야 합니다. 그렇지 않으면 아이콘이 빠지지만 링크는 정상 동작합니다. |
Chat 번들에는 지도 라이브러리가 없고 'wasm-unsafe-eval'도 필요하지 않습니다. 페이지에 이미 있는 지도에 그리므로 해당 지도 라이브러리가 요구하는 스크립트 호스트, connect-src와 img-src의 타일 및 스타일 호스트, Mapbox GL JS와 MapLibre GL JS를 위한 worker-src blob:은 유 지하세요.
Chat이 자체 지도가 아닌 Kaleidr Viewer 또는 Tile 요소를 제어한다면 해당 제품의 지시문도 추가해야 합니다. 여기에는 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:;
| 지시문 | 이유 |
|---|---|
script-src https://cdn.kaleidr.com | 로더와 editor.js. |
style-src 'unsafe-inline' | Editor는 nonce 없이 JavaScript로 스타일시트를 문서에 추가합니다. |
connect-src https://api.kaleidr.com | 세션 교환. |
connect-src https://tile.kaleidr.com | 페이지에서 가져오는 베이스맵 스타일, 타일, 스프라이트, 레이블 글꼴. |
img-src data: blob: https://tile.kaleidr.com | 지도 이미지와 아이콘. 지도는 blob: 및 data: URL로 이미지를 만듭니다. |
worker-src blob: | 지도 워커는 blob: URL에서 실행됩니다. |
font-src data: | Editor 인터페이스 글꼴은 data: URL로 내장되어 있습니다. |
'wasm-unsafe-eval'은 기본 목록에 넣지 않습니다. Editor의 3D 모델 디코더인 editor.js에서 WebAssembly 컴파일이 정책에 차단되었다는 메시지가 콘솔에 표시될 때만 script-src에 추가하세요.
styleId로 전체 스타일 URL을 전달했다면 그 스타일의 호스트도 connect-src와 img-src에서 허용하세요.
한 페이지의 여러 제품
각 제품의 허용 목록을 합치세요. Tile 지도와 이를 제어하는 Chat 패널을 함께 사용하는 페이지에는 다음이 필요합니다:
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:;
전체 정책
위 코드 블록은 Kaleidr가 추가로 요구하는 항목만 설명합니다. 실제 정책에는 사용자 사이트의 리소스도 허용해야 합니다. 다른 리소스는 전부 자체 오리진에서 제공하고 Viewer와 Tile을 삽입하는 사이트용 전체 헤더 예시:
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'이 포함된 이유는 Kaleidr 코드 자체가 아닙니다. 문서의 코드 예시가 style="display:block; height:480px" 인라인 속성으로 요소 크기를 정하기 때문입니다. 'unsafe-inline'이 없는 정책은 인라인 스타일 속성을 무시합니다. 인라인 스타일을 계속 막고 싶다면 스타일시트에서 크기를 지정하세요:
kaleidr-map { display: block; height: 480px; }
SDK가 iframe에 지정하는 크기에는 영향이 없습니다. 스크립트로 설정되며 스타일 정책이 막지 않습니다. 요소의 기본 display:block도 <style> 태그나 style 속성으로 제공되는 것이 아니라서 영향을 받지 않고 'unsafe-inline'이 필요 없습니다.
Nonce, 해시, strict-dynamic
- 스크립트. 로더는 각 번들을
<script src>요소로 추가합니다. 호스트 기반script-src에서 허용할 수 있습니다. nonce와'strict-dynamic'을 쓴다면 로더 태그에 nonce를 지정하세요. 이후 추가되는 스크립트는'strict-dynamic'으로 신뢰되므로 호스트를 따로 등록할 필요가 없습니다. - 스타일. Chat과 Editor가 삽입하는 스타일에는 SDK로 nonce를 지정할 수 없습니다. 내용이 버전마다 달라져 해시도 고정할 수 없습니다. 두 제품은
style-src의'unsafe-inline'이 필요합니다. Viewer와 Tile은 페이지에 스타일을 삽입하지 않습니다. - 무결성. 로더 태그에
integrity속성을 추가하지 마세요. 파일이 같은 주소에서 업데이트되기 때문입니다. CDN 버전 관리를 참고하세요.
리소스 차단 증상
브라우저 콘솔은 차단을 일으킨 지시문과 함께 모든 차단 내용을 보고합니다. 아래 표와 비교하세요.
| 증상 | 콘솔에 표시되는 지시문 | 추가할 값 |
|---|---|---|
아무것도 마운트되지 않음. Kaleidr is not defined. | script-src | script-src에 https://cdn.kaleidr.com. |
요소가 비어 있음. 콘솔: [kaleidr:<product>] [kaleidr] failed to load …/embed/v1/<product>.js | script-src | 같은 호스트. 로더는 해시 등으로 허용되었지만 번들은 허용되지 않았습니다. |
| Viewer나 Tile이 빈 상자를 표시함. | frame-src(또는 child-src, default-src) | frame-src에 https://map-embed.kaleidr.com. |
Tile, Chat 또는 Editor가 시작되지 않고 sessions 요청이 차단됨. | connect-src | connect-src에 https://api.kaleidr.com. |
| 채팅 패널의 스타일이 없음. | style-src | style-src에 'unsafe-inline'. |
| Chat 아이콘 또는 글꼴이 없음. | img-src, font-src | 두 곳 모두 data:. |
| 장소 사진이나 링크 옆 아이콘이 없음. | img-src | img-src에 https: 또는 콘솔에 표시된 호스트. |
| Editor 패널은 보이지만 지도가 비어 있음. | connect-src, worker-src 또는 img-src | connect-src와 img-src에 https://tile.kaleidr.com, worker-src와 img-src에 blob:. |
| Editor 스타일이 없음. | style-src | style-src에 'unsafe-inline'. |
요소의 style 속성에 지정한 높이가 적용되지 않음. | style-src | 추가 불필요. 스타일시트에서 크기를 지정하세요. |
모든 오류가 정책 문제는 아닙니다. sessions 요청이 전송된 뒤 401, 403, 429가 반환된다면 정책은 요청을 허용했고 API가 거부한 것입니다. 오류와 CORS 및 허용 오리진을 참고하세요.
보고 전용 모드로 배포
프로덕션 페이지를 중단시키지 않고 엄격한 정책에 Kaleidr를 추가하는 방법:
- 현재 정책을 유지하면서 후보 정책을
Content-Security-Policy-Report-Only로 보내고 직접 관리하는 보고 엔드포인트를 지정합니다. - 삽입 기능을 테스트합니다. 페이지를 열고 지도를 움직이며 Chat에서 사진이 있는 장소를 반환하는 질문을 합니다.
- 보고서에 나타난 출처를 해당 지시문에 추가합니다. 장소 사진 때문에 새 이미지 호스트가 필요한 경우가 많습니다.
- 위반 보고가 없어지면
Content-Security-Policy로 전환합니다.
필요하지 않은 항목
- Kaleidr 제품을 위한 Mapbox, MapTiler 또는 OpenStreetMap 호스트.
script-src의'unsafe-inline'. 로더는 번들을<script src>요소로 추가하며 인라인 스크립트를 사용하지 않습니다.frame-ancestors. 이 지시문은 누가 내 페이지를 iframe으로 표시할 수 있는지 정하지, 내 페이지에서 어떤 iframe을 허용할지는 정하지 않습니다.- Viewer 또는 Tile iframe 내부에서 실행되는 리소스에 대한 추가 항목.