CORS 및 허용된 출처
게시용 키에는 해당 키를 사용할 수 있는 웹사이트를 지정하는 허용된 출처 목록을 설정할 수 있습니다. 이 페이지에서는 목록이 검사되는 위치, 검사에 실패했을 때 브라우저에 표시되는 내용, 그리고 이 목록이 보호하지 못하는 범위를 설명합니다.
출처(origin)는 페이지의 스킴, 호스트, 포트로 구성됩니다. 예를 들어 https://www.example.com 또는 http://localhost:3000입니다. 경로는 포함되지 않습니다.
목록 설정은 선택 사항입니다
게시용 키는 목록이 비어 있어도 작동합니다. 목록이 비어 있으면 모든 출처에서 해당 키를 사용할 수 있습니다. 출처를 지정하지 않고 생성한 키는 이런 상태이며, 나중에 목록을 비울 수도 있습니다.
키를 프로덕션 사이트에 배포하기 전에 출처를 추가하세요. 목록이 설정되어 있으면 다른 사람의 웹페이지에 키를 복사해 붙여 넣더라도 해당 페이지에서는 작동하지 않습니다. 이 기능이 보호하는 것과 보호하지 못하는 것은 아래에서 설명합니다.
서버 키에는 이 목록이 적용되지 않습니다. 목록에 무엇이 있든 서버 키는 브라우저에서 사용할 수 없습니다.
항목 작성 방법
| 규칙 | 예시 |
|---|---|
| 스킴, 호스트 및 필요한 경우 포트만 입력합니다. 경로, 쿼리 또는 끝의 슬래시는 넣지 않습니다. | https://www.example.com을 사용하고 https://www.example.com/은 사용하지 않습니다 |
https가 필요합니다. http는 localhost, 127.0.0.1, [::1]에서만 허용됩니다. API 키 페이지는 [::1]을 허용하지 않으므로 키 관리 API로 설정하세요. | http://localhost:3000 |
정확히 일치해야 합니다. 와일드카드는 허용되지 않으며 하위 도메인은 별도의 출처입니다. *가 포함된 항목은 입력한 그대로 저장되지만 어떤 사이트와도 일치하지 않습니다. | https://example.com과 https://www.example.com은 서로 다른 두 항목입니다 |
포트는 출처의 일부입니다. 기본 포트(https는 443, http는 80)는 생략합니다. | https://example.com을 사용하고 https://example.com:443은 사용하지 않습니다 |
| 키당 최대 100개까지 등록할 수 있습니다. 중복 항목은 거부됩니다. |
항목은 브라우저에서 전송하는 값과 일치하도록 소문자로 저장되며 기본 포트는 제거됩니다.
디스크에서 직접 연 페이지(file://)에는 추가할 수 있는 출처가 없습니다. 개발할 때는 http://localhost에서 페이지를 제공하세요.
목록은 kaleidr.com/api-keys의 API 키 페이지에서 설정하거나, 키 관리 API의 allowed_origins로 설정할 수 있습니다.
목록이 검사되는 위치
| 단계 | 검사 내용 | 실패하는 경우 |
|---|---|---|
| 1. 세션 교환 | 키에 목록이 있는 경우 요청의 Origin 헤더가 해당 목록에 있어야 합니다. | 403 origin_not_allowed를 반환하며 세션이 발급되지 않습니다. Origin 헤더가 아예 없으면 403 origin_required를 반환합니다. |
| 2. 모든 런타임 호출 | 세션 토큰은 발급받은 출처에서만 작동합니다. | 403 session_origin_mismatch를 반환합니다. |
| 3. 모든 런타임 호출 | 세션의 출처가 계속해서 키의 목록에 있어야 합니다. | 401을 반환합니다. 키에서 출처를 제거하면 해당 출처에 이미 발급된 세션도 종료됩니다. |
| 4. 키가 포함된 기본 지도 요청 | 임베디드 Editor는 스타일, 스프라이트 및 글꼴을 요청할 때 게시용 키를 https://tile.kaleidr.com에 전송합니다. 키가 인식되려면 페이지의 사이트가 키 목록에 있어야 합니다. | 키가 없는 요청으로 처리되며 429 tile_access_restricted로 거부될 수 있습니다. |
| 5. 응답 | 인증 정보가 유효하고 출처가 허용된 경우에만 API가 Access-Control-Allow-Origin을 추가합니다. | 브라우저가 페이지에서 응답을 읽지 못하도록 차단합니다. |
5단계는 일반적인 CORS 동작이며 브라우저에서 실패가 이런 방식으로 나타나는 이유입니다.
사전 요청(Preflight)
JSON 본문이 포함된 사이트 간 POST를 보내기 전에 브라우저는 OPTIONS 사전 요청을 전송합니다. 사전 요청에는 인증 정보가 없어 키와 대조할 수 없으므로 Kaleidr는 모든 사전 요청에 204로 응답하고 요청 출처를 그대로 반영합니다. 출처 목록은 실제 요청에 적용됩니다.
| 사전 요청 응답 헤더 | 값 |
|---|---|
Access-Control-Allow-Methods | GET, POST, OPTIONS |
Access-Control-Allow-Headers | Authorization, Content-Type, Accept, X-Api-Key, X-Request-Id |
Access-Control-Max-Age | 600 |
다른 헤더를 전송하는 요청은 브라우저의 사전 요청 단계에서 실패합니다. 페이지에서 보내는 호출에 사용자 지정 헤더를 추가하지 마세요.
허용된 응답에서 API는 Access-Control-Expose-Headers: Retry-After, X-Request-Id도 전송하므로 페이지 코드가 이 두 헤더를 읽을 수 있습니다. API는 쿠키를 사용하지 않으므로 Access-Control-Allow-Credentials는 전송하지 않습니다.
출처가 거부되면 표시되는 내용
출처나 인증 정보가 거부되면 응답에 Access-Control-Allow-Origin 헤더가 없습니다. 그러면 브라우저가 코드에서 응답을 읽을 수 없게 숨깁니다. 따라서 페이지는 401 또는 403 응답 본문을 볼 수 없고, 네트워크 오류만 확인합니다.
콘솔에는 다음과 같이 표시됩니다.
Access to fetch at 'https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions' from origin
'https://www.example.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present
on the requested resource.
그 뒤에 [kaleidr:chat](또는 마운트한 제품명)이 포함된 SDK 오류가 이어집니다. 아무것도 렌더링되지 않습니다.
실제 원인을 확인하려면 브라우저의 Network 탭을 열고 sessions 요청을 선택한 뒤 상태와 응답을 확인하세요.
| Network 탭의 상태 및 코드 | 원인 | 해결 방법 |
|---|---|---|
403 origin_not_allowed | 현재 페이지의 출처가 키 목록에 없습니다. | 요청의 Origin 헤더에 표시된 출처를 정확히 추가하세요. |
401 Invalid or missing API key | 키가 잘못 입력되었거나 취소되었거나 만료되었습니다. | API 키 페이지에서 키를 확인하세요. |
403 server_key_in_browser | 페이지에서 서버 키가 전송되었습니다. | 페이지에는 게시용 키를 사용하고 서버 키를 교체하세요. |
403 session_origin_mismatch | 세션을 요청한 출처와 다른 출처에서 세션 토큰이 사용되었습니다. | 세션을 실제로 사용하는 페이지에서 다시 세션을 교환하세요. |
사전 요청이 실패하고 POST가 표시되지 않음 | 요청이 허용 목록에 없는 헤더를 전송했습니다. | 사용자 지정 헤더를 제거하세요. |
인증 정보와 출처가 허용된 후에는 이후 오류를 페이지에서 읽을 수 있으며 CORS 오류가 발생하지 않습니다. 출처에서는 유효하지만 해당 제품에는 허용되지 않은 키는 읽을 수 있는 403(product_not_allowed, insufficient_scope 또는 tier_capability_not_allowed)으로 세션 교환에 실패하고 SDK는 kaleidr session exchange failed (403)를 기록합니다. 유효한 세션에 대한 429 응답은 응답 본문과 Retry-After 헤더를 함께 전달합니다. 각 코드는 인증 및 범위에 설명되어 있습니다.
CORS는 브라우저 규칙이므로 터미널에서 같은 요청을 보내더라도 CORS 오류가 나타나지 않습니다. 따라서 curl을 이용해 키와 출처 조합을 빠르게 확인할 수 있습니다.
curl -i https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
-H "X-Api-Key: kld_pk_live_…" \
-H "Origin: https://www.example.com" \
-H "Content-Type: application/json" \
-d '{"product":"chat"}'
허용된 출처는 access-control-allow-origin: https://www.example.com 헤더와 함께 200을 반환합니다. 거부된 출처는 해당 헤더 없이 403 {"detail":"origin_not_allowed"}를 반환합니다.
브라우저에서 서버 키가 거부되는 이유
서버 키는 계속 유효한 비밀 정보입니다. 키를 가진 사람은 키가 취소될 때까지 조직의 권한으로 API를 호출할 수 있습니다. 페이지 소스는 공개되므로 페이지 안에 서버 키를 넣었다면 그 키는 유출된 것입니다.
Kaleidr는 세 지점에서 서버 키를 거부합니다.
- SDK는 마운트할 때
kld_sk_…키를 거부하며 네트워크 요청 없이 콘솔 오류를 표시합니다. Origin헤더가 포함된 서버 키 요청에 대해 API는 403server_key_in_browser를 반환합니다.- 응답에 CORS 헤더가 없으므로 페이지 코드는 어떤 경우에도 응답을 읽지 못합니다.
이러한 조치로 유출 사실이 되돌려지지는 않습니다. CORS는 요청이 아니라 응답을 차단합니다. API가 요청을 거부할 때는 이미 키가 전송된 후이므로 페이지를 보는 누구나 키를 확인할 수 있습니다. 서버 키가 페이지에 포함된 적이 있다면 키를 교체하세요.
이 목록은 비밀 정보를 지켜 주지 않습니다
브라우저는 Origin 헤더를 올바르게 설정하지만 브라우저 외의 클라이언트는 그렇지 않을 수 있습니다. 위의 curl 예시처럼 스크립트, 명령줄 도구 또는 서버는 원하는 Origin을 보낼 수 있습니다. 따라서 다음 두 가지를 이해해야 합니다.
- 이 목록은 다른 웹사이트가 방문자의 브라우저에서 내 키를 사용하지 못하도록 합니다. 이것이 목록의 역할이며 이 목적에는 효과적입니다.
- 이 목록은 의도적으로 우회하는 호출자를 막지 못합니다. 공개용 키를 복사하고 브라우저 외부에서 내 출처를 지정해 요청을 보내는 사람까지 막지는 못합니다.
이를 전제로 설계하세요. 게시용 키로 접근할 수 있는 모든 정보는 내 페이지를 읽을 수 있는 누구에게나 공개될 수 있다고 생각해야 합니다.
- 키별 월간 한도와 요청 속도 제한을 사용하여 할당량 노출을 제한하세요. 할당량 및 요청 속도 제한을 참조하세요.
- 해당 페이지에 공개해도 되는 데이터를 읽는 경우가 아니라면 게시용 키에
vendor범위를 부여하지 마세요. 인증 및 범위를 참조하세요. - 웹사이트마다 키를 하나씩 사용하여 다른 사이트에 영향을 주지 않고 특정 키를 취소할 수 있도록 하세요.
자세한 내용은 보안 모델을 참조하세요.
URL에 포함된 인증 정보
플랫폼 API 호출은 URL이 아닌 헤더에 인증 정보를 담습니다. Kaleidr 임베드의 기본 지도 요청만 예외이며, 요청 URL에 브라우저 인증 정보가 포함됩니다. 이 정보는 브라우저 기록이나 네트워크 로그에 남을 수 있습니다. 이미 공개된 게시용 인증 정보에는 허용되지만 서버 키에는 절대 허용되지 않습니다. 어떤 URL에도 kld_sk_…를 넣지 마세요.
목록 변경
- 출처 추가는 해당 출처에서 다음 세션 교환을 실행할 때 적용됩니다. 기본 지도 요청에 변경 사항이 반영되기까지 몇 분 걸릴 수 있습니다.
- 출처 제거는 해당 출처의 새 세션 교환을 거부하고 기존 세션을 다음 요청 시 종료합니다.
- 목록 비우기는 다시 '모든 출처'를 허용하도록 설정합니다.