모든 기사 개발자

지도 API 인증

작성자 The Kaleidr Team · 게시일 2026년 8월 17일 · 16 분 읽기

브라우저 공개 키 및 출처 바인딩 세션을 백엔드 서버 키와 비공개 데이터에서 분리한 안전한 지도 API 아키텍처.

안전한 지도 API 인증 설계는 실행 환경별로 자격 증명을 분리합니다. 브라우저에는 공개되어도 안전하고 승인된 출처와 기능으로 엄격히 제한된 자격 증명이 필요합니다. 백엔드에는 클라이언트 코드에 절대 들어가지 않고 서버 간 작업을 승인하는 비밀 자격 증명이 필요합니다. 둘은 서로 바꿔 쓸 수 없어야 합니다. 범위를 제한하고 환경을 분리하며 사용량을 모니터링하고 키를 교체하며 인증 실패와 권한 부여 실패를 구분하세요. Kaleidr는 공개 키(kld_pk_live_…)와 서버 키(kld_sk_live_…)를 사용합니다.

아래에서는 브라우저와 서버 자격 증명, 출처, CORS, 범위, 수명 주기, 멀티테넌트 신뢰 경계, 흔한 실수를 다룹니다. 개발자 문서, AI 지도 SDK란?, 인터랙티브 지도 임베드 방법, Mapbox, Google Maps, MapLibre에 AI 채팅 추가도 참고하세요.

인증 핵심 원칙

  • 실행 환경 우선: 브라우저 자격 증명은 공개, 서버 자격 증명은 비밀 유지를 전제로 설계합니다.
  • 출처 ≠ 인증: CORS와 허용 출처는 자격 증명 검사를 대신하지 않습니다.
  • 범위 ≠ 테넌트: API 기능 범위는 사용자 또는 데이터 행 권한이 아닙니다.
  • 안전한 교체: 활성 키를 폐기하기 전에 대체 키를 배포합니다.
  • 로그 마스킹: 키 ID와 상태 코드만 기록하고 값은 기록하지 않습니다.

브라우저 공개 키 및 출처 바인딩 세션을 백엔드 서버 키와 비공개 데이터에서 분리한 안전한 지도 API 아키텍처.

브라우저의 지도 API 인증은 왜 다른가요?

브라우저는 신뢰할 수 없는 실행 환경입니다. 전달된 내용은 페이지 소스, 개발자 도구, 네트워크 요청, 번들 JavaScript, 저장소, 런타임 객체로 보통 확인할 수 있습니다. 장기 서버 비밀 키를 React 소스, Next.js NEXT_PUBLIC_*, Vite VITE_*, HTML, 모바일 WebView, 프런트엔드 JSON에 넣는 것은 위험합니다. 브라우저는 실행하는 사람에게 비밀을 숨길 수 없습니다. 키를 어디에 숨길지가 아니라 무엇을 할 수 있고 어디서 실행할 수 있는지를 물어야 합니다.

속성 공개／브라우저 자격 증명 서버 자격 증명
대상 환경 브라우저 또는 클라이언트 SDK 신뢰할 수 있는 백엔드
클라이언트 노출 가능 절대 불가
보안 모델 제한 기능 + 승인 출처 + 지원 시 단기 세션 비밀 bearer 자격 증명
주요 위험 무단 재사용 또는 할당량 남용 계정 또는 데이터 침해

이름은 달라도 패턴은 같습니다. Kaleidr는 공개 키와 서버 키를 사용합니다(Auth & Scopes). Mapbox는 공개·비밀 토큰 범위를 구분하고 비밀 토큰 요청은 서버에서 하도록 안내합니다(Mapbox 안전 사용). Google Maps Platform은 앱·API 제한을 사용하고 웹 서비스 자격 증명을 보호하며 지원 시 서버 간 OAuth 2.0을 사용하도록 권장합니다(보안 지침).

Kaleidr 공개 키와 서버 키는 어떻게 작동하나요?

현재 문서는 같은 조직·기능 시스템에 두 키 유형을 정의합니다. kld_pk_live_…는 HTML, SDK, <kaleidr-map>, 브라우저 통합에서 사용됩니다. SDK는 이 문자열을 상시 bearer로 쓰지 않고 실행 중 출처 바인딩 단기 세션으로 교환합니다. kld_sk_live_…는 신뢰할 수 있는 서버에서만 Authorization: Bearer … 또는 X-Api-Key: …로 사용합니다. 브라우저에서 차단되며 CORS 허용도 받지 않습니다(CORS & Allowed Origins). 서버 키를 클라이언트에 넣거나 공개 환경 변수를 비밀 저장소로 취급하지 마세요.

허용 출처는 경로와 끝 슬래시가 없는 https://app.example.com 형식이어야 하며 https://app.example.com/maps가 아닙니다. Kaleidr는 localhost와 127.0.0.1 로컬 테스트 외에는 HTTPS를 요구합니다. 루트, www, app, admin, preview 호스트는 서로 다른 출처입니다. 출처 제한은 무단 재사용을 줄이지만 서버 비밀 키를 클라이언트 밖에 두는 조치를 대신하지 않습니다.

CORS, 인증, 범위, 앱 권한은 어떻게 다른가요?

CORS는 브라우저가 교차 출처 응답을 읽을 수 있는지 제어하고 인증은 호출자를 식별합니다. 범위 권한은 자격 증명이 기능을 사용할 수 있는지, 호스트 앱 권한은 어떤 사용자나 테넌트가 비공개 레코드에 접근하는지 결정합니다. Kaleidr는 preflight를 허용해도 승인된 출처에만 Access-Control-Allow-Origin을 반환하며 서버 키에는 브라우저 CORS를 부여하지 않습니다. 401은 보통 자격 증명 누락, 무효, 만료, 폐기를 뜻합니다. 403은 유효하지만 권한이 없다는 뜻이며 필요한 기능이 없을 때 insufficient_scope를 사용합니다. 진단과 모니터링에서 따로 처리하세요.

브라우저 출처 제어, 자격 증명 인증, API 기능 범위, 앱 사용자 권한을 분리한 네 가지 보안 계층.

자격 증명을 어떻게 생성, 저장, 교체, 폐기해야 하나요?

최소 권한을 적용해 필요한 범위만 부여하세요. Mapbox는 최소 범위와 브라우저의 공개 범위만 사용하라고 권장하고 Google은 실제 사용 API에만 앱·API 제한을 적용하라고 권장합니다. 개발, 미리보기, 운영에서 키를 공유하지 마세요. 분리하면 영향 범위가 줄고 교체가 안전해집니다. Mapbox는 환경·클라이언트별 토큰, Google은 앱별 키를 권장합니다(토큰 관리).

새 Kaleidr 키 값은 한 번만 표시되므로 즉시 비밀 관리자에 저장합니다. 서버 키를 공개 저장소나 브라우저 번들에 두지 마세요. CI/CD에서는 배포 시 주입하고 로그에서 마스킹하며 환경 덤프를 출력하지 않습니다. 키 ID, 상태, 출처만 기록하고 Authorization 헤더와 값은 가립니다. 대체 키를 생성·제한·배포하고 트래픽을 확인한 뒤 이전 키를 폐기합니다. 침해 시에는 더 빨리 처리하세요. 할당량도 보안 제어입니다. Platform API 사용량은 조직 단위로 측정되고 스트리밍은 동시성을 제한합니다(Quota & Rate Limits). 429는 401·403과 다르게 처리하고 재시도 폭주 대신 백오프하세요.

// 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}`
  }
});

자격 증명의 생성과 제한부터 안전한 배포, 모니터링, 교체, 폐기까지의 수명 주기.

운영 앱은 플랫폼 인증과 호스트 인증을 어떻게 분리하나요?

권장 패턴은 브라우저가 승인 출처에서 공개 키로 공개 SDK 기능을 사용하고 인증된 제품 요청은 호스트 백엔드로 보내는 것입니다. 백엔드는 사용자 신원, 테넌트 소속, 객체 권한, 비공개 위치 데이터, 비밀 관리자의 서버 키를 소유하며 서버 간 플랫폼 호출 후 승인된 필드만 반환합니다. 공개 키는 최종 사용자 인증이 아니고 서버 키는 DB 행 권한이 아닙니다. 공개 Viewer 지도는 공유 링크로 제한되며 API 키가 필요 없다고 문서화되어 있지만, 링크도 접근 제어로 취급하고 제한 없는 공개 보기로 비공개 데이터를 보내지 마세요. CSP와 안전한 HTML 렌더링도 보완 수단입니다. Mapbox는 신뢰할 수 없는 HTML 팝업의 XSS 위험을 경고하고 텍스트 렌더링을 권장합니다.

브라우저 SDK는 공개 키를 쓰고 비공개 공간 작업은 사용자 권한과 비밀 서버 키가 있는 백엔드를 거치는 멀티테넌트 아키텍처.

팀이 피해야 할 실수는?

실수 위험 더 나은 방법
JavaScript에 서버 키 포함 자격 증명 도난 공개 키 또는 백엔드 프록시
CORS를 인증으로 취급 비브라우저 호출자가 우회 보호 요청을 모두 인증
한 키를 모든 곳에 사용 큰 영향 범위 환경과 앱 분리
모든 범위 부여 과도한 권한 최소 권한 적용
출처 목록에 경로 추가 출처 일치 실패 scheme://host[:port] 사용
Authorization 헤더 기록 로그에 비밀 유출 자격 증명 마스킹
공개 키를 사용자 신원으로 사용 사용자 구분 불가 실제 사용자 인증 사용
API 인증이 비공개 행을 보호한다고 가정 테넌트 데이터 유출 앱 권한 적용
트래픽 확인 없이 교체 운영 중단 대체 키 배포 후 폐기
429 무시 재시도 폭주와 나쁜 UX 백오프와 할당량 모니터링

브라우저 실패 시 출처 철자, HTTPS, 키 유형, 범위, 세션 교환 순서를 확인하세요. 서버 실패 시 키 유형, 환경, 범위, 비밀 주입, 교체 중 실수로 폐기했는지 확인하세요.

최종 평가

지도 API 보안은 브라우저와 백엔드에 같은 자격 증명 모델을 쓰지 않는다는 결정에서 시작합니다. 브라우저에는 출처, 범위, 세션 수명 등으로 제한된 공개 가능한 자격 증명이, 백엔드에는 신뢰 인프라 안의 비밀이 필요합니다. 최소 권한, 환경 격리, 앱 권한, 모니터링, 교체를 더하세요. Kaleidr 공개 키는 출처 제한 후 단기 세션으로 교환되고 서버 키는 서버 간 bearer이며 브라우저에서 차단됩니다. 프런트엔드에 키를 숨기려는 것보다 이 경계가 중요합니다.

Kaleidr 문서로 지도 API 보호하기

배포 전에 키 유형, 기능 범위, 출처 규칙, API 동작을 확인하세요. Kaleidr Auth & Scopes 읽기 후 개발자 문서에서 SDK 마운트와 Platform API 경로를 확인하세요.

자주 묻는 질문

지도 API 인증이란?

지도, 장소, 타일, 경로, 공간 API에 접근하는 앱이나 서비스를 식별하는 방식입니다. API 키, 액세스 토큰, 세션, bearer 토큰, OAuth 등이 있습니다.

API 키를 브라우저에서 안전하게 쓸 수 있나요?

제공자가 클라이언트용으로 설계한 경우만 가능합니다. 허용 출처, 공개 범위, 앱 제한, 단기 세션 교환이 필요하며 서버 비밀 키는 넣으면 안 됩니다.

공개 API 키는 비밀인가요?

아니요. 문자열을 숨기는 데 보안을 의존하지 않지만 제한과 모니터링은 필요합니다.

서버 API 키는 비밀인가요?

네. 신뢰할 수 있는 백엔드에만 두고 HTML, JavaScript 번들, WebView, 공개 저장소, 클라이언트 저장소에 노출하지 않습니다.

CORS는 인증인가요?

아니요. CORS는 교차 출처 응답 읽기를, 인증은 호출자 식별을, 권한은 가능한 작업을 결정합니다.

401과 403의 차이는?

401은 보통 누락, 무효, 만료, 폐기된 자격 증명입니다. 403은 유효하지만 요청 작업 권한이 없는 상태입니다.

개발과 운영 키를 분리해야 하나요?

네. 영향 범위를 줄이고 출처 제한과 사용량 파악을 단순화하며 교체를 안전하게 합니다.

API 키를 어떻게 교체하나요?

대체 키를 생성하고 제한을 설정해 배포한 뒤 운영 트래픽을 확인하고 이전 키를 폐기합니다. 침해 중이면 더 빨리 처리하세요.

Kaleidr Viewer에 API 키가 필요한가요?

현재 문서에 따르면 공개 Viewer 지도는 공유 링크로 제한되며 API 키가 필요 없습니다.

Kaleidr는 브라우저 통합을 어떻게 보호하나요?

허용 출처 목록이 있는 공개 키를 SDK가 출처 바인딩 단기 세션으로 교환합니다. 서버 키는 브라우저에서 차단되며 서버 간 호출용입니다.

참고 문헌

@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}
}

관련 콘텐츠

지도를 비즈니스 성장의 동력으로 바꾸세요