Google Maps Platform 보안 가이드

Google Maps Platform API 및 SDK를 사용하는 앱과 프로젝트는 API 키 또는 지원되는 경우 OAuth 2.0을 사용하여 자체 인증해야 합니다.

다음 권장사항에서는 지도 플랫폼 액세스를 보호하는 방법을 보여줍니다.

OAuth 2.0을 사용하여 서버 간 트래픽을 승인하려면 API 문서에서 OAuth 주제를 찾아보세요. 자세한 내용은 서버 측 앱에 OAuth 사용을 참고하세요.

애플리케이션 및 API 키 제한사항을 적용하는 것 외에 특정 Google Maps Platform 제품에 적용되는 보안 권장사항을 따르세요. 예를 들어 아래 권장되는 애플리케이션 및 API 제한사항에서 Maps JavaScript API를 참고하세요.

API 키가 이미 사용 중인 경우 아래 사용 중인 API 키를 제한하는 경우의 권장사항을 검토하세요.

Maps Static API 및 Street View Static API에서 지원하는 디지털 서명에 관한 자세한 내용은 디지털 서명 가이드를 참고하세요.

추천 권장사항

보안을 강화하고 무단 사용에 대한 요금이 청구되지 않도록 하려면 모든 Google Maps Platform API, SDK 또는 서비스에 대한 다음 API 보안 권장사항을 따르세요.

API 키 제한

앱마다 별도의 API 키 사용

사용하지 않는 API 키 삭제

API 키 사용량 확인

API 키를 회전할 때 주의

클라이언트 측 및 서버 측 사용량을 별도의 프로젝트로 분할

사용하지 않는 서비스 사용 중지하기

클라이언트 측 앱을 위한 추가 권장사항

클라이언트 측 SDK 사용

클라이언트 측 웹 서비스 호출 보호

정적 웹 API를 사용하는 웹사이트 또는 클라이언트 측 앱을 위한 추가 권장사항

정적 웹 API 사용 보호

웹 서비스를 사용하는 서버 측 앱을 위한 추가 권장사항

웹 서비스 API 키 보호

서버 측 앱에 OAuth 사용하기

사용 중인 API 키를 제한하거나 회전하는 경우

  • API 키를 변경하기 전에 API 키 사용량을 확인합니다. 이 단계는 프로덕션 애플리케이션에서 이미 사용 중인 키에 제한사항을 추가하는 경우 특히 중요합니다.

  • 키를 변경한 후 필요에 따라 모든 앱을 새 API 키로 업데이트합니다.

  • API 키가 손상되지 않았고 현재 악용되지 않는 경우 앱을 원하는 속도로 여러 개의 새 API 키로 이전할 수 있습니다. 이때 기존 API 키는 한 가지 유형의 트래픽만 표시될 때까지 그대로 둡니다. 그런 다음 의도치 않은 서비스 중단을 일으키지 않고 단일 유형의 애플리케이션 제한으로 API 키를 안전하게 제한할 수 있습니다.

    자세한 안내는 여러 API 키로 이전을 참고하세요.

    시간 경과에 따른 사용량을 모니터링하고 특정 API, 플랫폼 유형, 도메인이 이전 API 키에서 완전히 이전되었는지 확인한 후에 이전 키를 제한하거나 삭제하세요. 자세한 내용은 보고 및 모니터링 및 측정항목을 참고하세요.

  • API 키가 손상된 경우 API 키를 보호하고 악용을 중지하기 위해 더 신속하게 조치를 취해야 합니다. Android 및 iOS 앱에서는 고객이 앱을 업데이트할 때까지 키가 교체되지 않습니다. 웹페이지 또는 서버 측 앱에서 키를 업데이트하거나 교체하는 일은 훨씬 간단하지만 여전히 신중한 계획과 빠른 작업이 필요할 수 있습니다.

    자세한 내용은 API 키의 무단 사용 처리를 참고하세요.

추가 정보

권장되는 애플리케이션 및 API 제한

API 키 제한

가장 좋은 방법은 항상 하나의 유형의 애플리케이션 제한사항과 하나 이상의 API 제한사항으로 API 키를 제한하는 것입니다. API, SDK 또는 JavaScript 서비스별 추천 제한사항에 대해서는 아래의 권장되는 애플리케이션 및 API 제한사항을 참고하세요.

  • 애플리케이션 제한사항 API 키의 사용을 특정 플랫폼(Android 또는 iOS 애플리케이션), 클라이언트 측 애플리케이션을 위한 특정 웹사이트, 웹 서비스 REST API 호출을 전송하는 서버 측 앱을 위한 특정 IP 주소 또는 CIDR 서브넷으로 제한할 수 있습니다.

    승인하려는 유형의 애플리케이션 제한사항을 하나 이상 추가하여 키를 제한하며, 그 뒤에는 이러한 소스에서 시작된 요청만 허용됩니다.

  • API 제한사항 API 키를 사용할 수 있는 Google Maps Platform API, SDK 또는 서비스를 제한할 수 있습니다. API 제한사항은 지정된 API 및 SDK에 대한 요청만 허용합니다. 특정 API 키에 대해 필요한 만큼의 API 제한사항을 지정할 수 있습니다. 사용 가능한 API의 목록에는 프로젝트에서 사용 설정된 모든 API가 포함됩니다.

API 키에 대한 애플리케이션 제한사항 설정

  1. Google Cloud 콘솔 Google Maps Platform 사용자 인증 정보 페이지를 엽니다.

  2. 제한할 API 키를 선택합니다.

  3. API 키 수정 페이지의 키 제한사항에서 애플리케이션 제한사항 설정을 선택합니다.

    API 키 수정 페이지

  4. 제한사항 유형 중 하나를 선택하고 제한사항 목록에 따라 요청된 정보를 제공합니다.

    제한사항 유형 설명
    웹사이트 리퍼러 웹사이트를 하나 이상 지정합니다.
    • 일반적으로 지원되는 리퍼러 URI 스키마는 https 및 http입니다. 최신 웹브라우저는 개인 정보 보호를 위해 발신 요청에 `Referer` 헤더를 전송하지 않으므로 다른 스키마는 올바르게 작동하지 않을 수 있습니다.
    • 언제나 전체 리퍼러 문자열(프로토콜 스키마, 호스트 이름, 선택적 포트(예: https://google.com))를 제공합니다.
    • 모든 하위 도메인을 승인하는 데 와일드 카드 문자를 사용할 수 있습니다. 예를 들어 https://*.google.com은 .google.com으로 끝나는 모든 사이트를 허용합니다.
    • 대부분의 웹브라우저는 개인 정보 보호를 위해 교차 출처 요청에서 경로를 삭제하므로 전체 경로 리퍼러(예: https://google.com/some/path)를 승인하는 경우 주의합니다.
    IP 주소 하나 이상의 IPv4 또는 IPv6 주소 또는 CIDR 표기법을 사용하는 서브넷을 지정합니다. IP 주소는 Google Maps Platform 서버에서 관찰하는 소스 주소와 일치해야 합니다. 네트워크 주소 변환(NAT)을 사용하는 경우 이 주소는 일반적으로 시스템의 공개 IP 주소에 해당합니다.
    Android 앱 (AndroidManifest.xml 파일의) Android 패키지 이름 및 승인하려는 각 Android 애플리케이션의 SHA-1 서명 인증서 지문을 추가합니다. Play 앱 서명을 사용하여 서명 인증서 지문을 가져오는 경우 API 제공업체와 협업하기를 참고하세요. 자체 서명 키를 관리하고 있다면 애플리케이션 자체 서명을 참고하거나 빌드 환경에 대한 안내를 참고하세요.
    iOS 앱 승인하려는 각 iOS 애플리케이션의 번들 식별자를 추가합니다.

    애플리케이션 제한사항의 권장사항은 권장되는 애플리케이션 제한사항을 참고하세요.

  5. 저장을 선택합니다.

API 키에 대한 API 제한사항 설정

  1. Google Cloud 콘솔 Google Maps Platform 사용자 인증 정보 페이지를 엽니다.

  2. 제한할 API 키를 선택합니다.

  3. API 키 수정 페이지의 API 제한사항에서 다음을 수행합니다.

    • 키 제한을 선택합니다.

    • API 선택을 열고 애플리케이션에서 API 키를 사용하여 액세스해야 하는 API나 SDK를 선택합니다.

    API 또는 SDK가 표시되지 않으면 항목을 사용 설정해야 합니다. 자세한 내용은 하나 이상의 API 또는 SDK를 사용 설정하려면을 참고하세요.

    API 키 수정 페이지에서 API 제한

  4. 저장을 선택합니다.

    이 단계가 지나면 제한사항이 API 키 정의의 일부가 됩니다. API 키 제한사항을 저장하려면 적절한 세부정보를 제공하고 저장을 선택해야 합니다. 자세한 내용은 관심 있는 특정 API 또는 SDK에 관한 문서의 API 키 가져오기 가이드를 참고하세요.

권장되는 API 제한사항은 권장되는 API 제한사항을 참고하세요.

API 키 사용량 확인

API 키가 생성된 후 API 키를 제한하거나 키에서 사용 중인 API를 확인하여 제한하려면 API 키 사용량을 확인해야 합니다. 다음 단계에서는 API 키가 사용되고 있는 서비스 및 API 메서드를 보여줍니다. Google Maps Platform 서비스 외의 사용량이 표시되면 원치 않는 사용을 피하기 위해 더 많은 제한사항을 추가해야 하는지 조사하고 확인하세요. Google Maps Platform Cloud 콘솔 측정항목 탐색기를 사용하면 API 키에 적용할 API 및 애플리케이션 제한사항을 파악할 수 있습니다.

API 키를 사용하는 API 확인

다음 측정항목 보고서를 사용하면 API 키를 사용하는 API를 확인할 수 있습니다. 이러한 보고서를 사용하여 다음 작업을 수행할 수 있습니다.

  • API 키가 사용되는 방식 확인
  • 예상치 않은 사용량 파악
  • 사용하지 않는 키를 삭제해도 무방한지 확인 API 키 삭제에 대한 자세한 내용은 사용하지 않는 API 키 삭제를 참고하세요.

API 제한사항을 적용할 때 이러한 보고서를 사용하여 승인할 API 목록을 만들거나 자동으로 생성된 API 키 제한사항 권장사항을 검사하세요. 권장되는 제한사항에 대한 자세한 내용은 권장되는 제한사항 적용을 참고하세요. 측정항목 탐색기 사용에 대한 자세한 내용은 측정항목 탐색기로 차트 만들기를 참고하세요.

  1. Google Cloud 콘솔의 측정항목 탐색기로 이동합니다.

  2. 로그인하여 확인하려는 API 키를 위한 프로젝트를 선택합니다.

  3. 내 API 유형의 측정항목 탐색기 페이지로 이동합니다.

  4. 각 API 키를 검사합니다.

    1. 필터 추가를 선택합니다.

    2. 라벨 credential_id를 선택합니다.

    3. 검사하려는 키에 해당하는 값을 선택합니다.

    4. 이 API 키가 사용되고 있는 API를 확인하고 사용이 예상된 것인지 확인합니다.

    5. 완료되면 활성 필터 행 끝의 필터 삭제를 선택하여 추가 필터를 삭제합니다.

  5. 나머지 키에 대해 반복합니다.

  6. API 키를 사용 중인 API만으로 제한합니다.

  7. 무단 사용이 확인되면 API 키의 무단 사용 처리를 참고하세요.

측정항목 탐색기를 사용하여 올바른 유형의 애플리케이션 제한사항 선택

API 키가 사용 중인 Google Maps Platform 서비스에만 사용되는지 확인하고 필요한 경우 조치를 취한 후 API 키에 적절한 애플리케이션 제한사항이 적용되도록 하세요.

API 키에 권장되는 API 키 제한사항이 있으면 적용하세요. 자세한 내용은 권장되는 API 키 제한사항 적용을 참고하세요.

API 키에 제한사항 권장사항이 없으면 측정항목 탐색기를 사용하여 보고된 platform_type에 따라 적용할 애플리케이션 제한사항의 유형을 결정하세요.

  1. Google Cloud 콘솔의 측정항목 탐색기로 이동합니다.

  2. 로그인하여 확인하려는 API를 위한 프로젝트를 선택합니다.

  3. 측정항목 탐색기 페이지: 측정항목 탐색기로 이동합니다.

  4. 각 API 키를 검사합니다.

    1. 필터 추가를 선택합니다.

    2. 라벨 credential_id를 선택합니다.

    3. 검사하려는 키에 해당하는 값을 선택합니다.

    4. 완료되면 활성 필터 행 끝의 필터 삭제를 선택하여 추가 필터를 삭제합니다.

  5. 나머지 키에 대해 반복합니다.

  6. API 키에 대한 플랫폼 유형을 선택한 후 해당 platform_type에 애플리케이션 제한사항을 적용합니다.

    PLATFORM_TYPE_JS : 키에 웹사이트 제한사항을 적용합니다.

    PLATFORM_TYPE_ANDROID : 키에 Android 애플리케이션 제한사항을 적용합니다.

    PLATFORM_TYPE_IOS : 키에 iOS 애플리케이션 제한사항을 적용합니다.

    PLATFORM_TYPE_WEBSERVICE : 키를 제대로 제한하기 위해 키에 IP 주소 제한사항을 적용해야 할 수도 있습니다.

    Maps Static API 및 Street View Static API 권장사항은 정적 웹 API 사용 보호를 참고하세요.

    Maps Embed API 권장사항은 Maps Embed API가 있는 웹사이트를 참고하세요.

    내 API 키가 여러 플랫폼 유형을 사용합니다. 하나의 API 키만으로는 트래픽을 제대로 보호할 수 없습니다. 여러 API 키로 이전해야 합니다. 자세한 내용은 여러 API 키로 이전을 참고하세요.

앱마다 별도의 API 키 사용

이렇게 하면 각 키의 범위가 제한됩니다. API 키가 손상된 경우 다른 API 키를 업데이트하지 않고도 손상된 키를 삭제하거나 순환할 수 있습니다. 프로젝트당 최대 300개까지 API 키를 만들 수 있습니다. 자세한 내용은 API 키의 한도를 참고하세요.

보안을 위해서는 애플리케이션당 하나의 키가 이상적이지만, 동일한 유형의 애플리케이션 제한사항의 유형을 사용하는 한 제한된 키를 여러 앱에서 사용할 수 있습니다.

권장되는 API 키 제한사항 적용

일부 프로젝트 소유자, 편집자, API 키 관리자의 경우, Google Cloud 콘솔에서 Google Maps Platform 사용량 및 활동을 기반으로 제한되지 않은 API 키에 특정 API 키 제한사항을 추천합니다.

사용 가능한 경우 권장사항이 Google Maps Platform 사용자 인증 정보 페이지에 미리 작성된 옵션으로 표시됩니다.

자동 추천에서 지원하는 Google Maps Platform API 및 SDK

  • 지도 서비스 (기존), 거리 행렬 서비스 (기존), 고도 서비스, Geocoding 서비스, 장소 클래스, 장소 자동 완성 위젯 (신규), 장소 자동 완성 데이터 API, 장소 라이브러리, 장소 서비스, 장소 자동 완성 위젯을 포함한 Maps JavaScript API

  • Maps Static API 및 Street View Static API

  • Maps Embed API

  • Android용 Maps SDK, Android용 Places SDK, Android용 Navigation SDK

  • iOS용 Maps SDK, iOS용 Places SDK, iOS용 Places Swift SDK, iOS용 Navigation SDK

권장사항이 표시되지 않거나 불완전한 이유

맞춤 동영상이 표시되지 않는 이유

  • Google Maps Platform 서비스가 아닌 서비스 또는 자동 추천에서 아직 지원되지 않는 Maps Platform 서비스에 API 키를 사용하고 있습니다.

    다른 서비스에 사용량이 표시되면 먼저 다음 작업을 실행하지 않고 권장사항을 적용하지 마세요.

    1. Google Cloud 콘솔 측정항목 탐색기에 표시되는 API 사용량이 적절한지 확인합니다.

    2. 승인할 API 목록에 누락된 서비스를 수동으로 추가합니다.

    3. API 목록에 추가된 서비스의 누락된 애플리케이션 제한사항을 수동으로 추가합니다. 추가된 다른 애플리케이션에 다른 유형의 애플리케이션 제한사항이 필요한 경우 여러 API 키로 이전을 참고하세요.

  • API 키가 클라이언트 측 SDK 또는 API에서 사용되지 않습니다.

  • 최근 60일 동안 사용되지 않은 사용량이 적은 앱 또는 웹사이트에서 API 키를 사용합니다.

  • 매우 최근에 새로운 키를 만들었거나 매우 최근에 기존 키를 새 앱에 배치했습니다. 이 경우 권장사항이 업데이트될 때까지 며칠만 기다리세요.

  • 충돌하는 유형의 애플리케이션 제한사항이 필요한 여러 애플리케이션에서 API 키를 사용 중이거나 또는 너무 많은 앱 또는 웹사이트에 동일한 API 키를 사용 중입니다. 각각의 경우 여러 키로 이전하는 것이 가장 좋습니다. 자세한 내용은 여러 API 키로 이전을 참고하세요.

불완전한 추천이 표시되는 이유

  • 최근 60일 동안 사용되지 않은 사용량이 적은 앱 또는 웹사이트에서 API 키를 사용합니다.

  • 새 API 또는 서비스에서 기존 키를 사용하기 시작한 지 얼마 안 지났으며 자동 API 키 제한 권장사항 파이프라인에서 아직 업데이트된 사용량 측정항목을 처리하지 않았습니다. 사용량 측정항목이 반영되기까지 며칠이 걸릴 수 있습니다.

    다른 서비스에 사용량이 표시되면 먼저 다음 작업을 실행하지 않고 권장사항을 적용하지 마세요.

    1. Google Cloud 콘솔 측정항목 탐색기에 표시되는 API 사용량이 적절한지 확인합니다.

    2. 승인할 API 목록에 누락된 서비스를 수동으로 추가합니다.

    3. API 목록에 추가된 서비스의 누락된 애플리케이션 제한사항을 수동으로 추가합니다. 추가된 다른 애플리케이션에 다른 유형의 애플리케이션 제한사항이 필요한 경우 여러 API 키로 이전을 참고하세요.

    4. 무단 사용으로 인해 키를 긴급하게 제한해야 하는 경우가 아니라면 추천이 적용될 때까지 하루나 이틀 정도 기다릴 수도 있습니다.

차트에는 표시되지 않는 권장사항이 표시되는 이유

  • 앱 또는 웹사이트에서 매우 짧은 트래픽 버스트만 전송했습니다. 이 경우 사용량이 여전히 범례에 표시되므로 차트 뷰에서 표 또는 둘 다를 표시하도록 전환하세요. 자세한 내용은 차트의 전체 범례 전환을 참고하세요.

  • 트래픽이 Maps Embed API에서 발생했습니다. 자세한 내용은 API 키를 사용하는 API 확인을 참고하세요.

  • 앱 또는 웹사이트의 트래픽이 Google Cloud 콘솔 측정항목 탐색기에서 사용 가능한 기간을 벗어납니다.

  1. Google Cloud 콘솔 Google Maps Platform 사용자 인증 정보 페이지를 엽니다.

  2. 사용 가능한 경우 권장 제한사항 적용을 선택합니다.

    권장 제한 사항 적용

  3. API 사용량 확인을 선택하여 API 키가 사용되고 있는 서비스를 확인합니다. Google Maps Platform 서비스 이외의 서비스가 표시되면 일시중지하여 위의 권장 단계를 수동으로 검토하세요. 권장되는 API 키 제한사항 적용 섹션 시작 부분의 문제 해결 단계를 참고하세요.

  4. 미리 작성된 권장사항이 API 키를 사용할 것으로 예상되는 웹사이트 및 앱과 일치하는지 다시 확인합니다.

    권장사항: 서비스와 관련되지 않은 애플리케이션 또는 API 제한사항을 문서화하고 삭제합니다. 예기치 않은 종속 항목으로 인해 문제가 발생하면 필수 앱 또는 API를 다시 추가할 수 있습니다.

    • 앱, 웹사이트 또는 API가 권장사항에서 명확히 누락된 것이 확인되면 수동으로 추가하거나 권장사항이 업데이트될 때까지 며칠 기다리세요.

    • 추천된 권장사항과 관련하여 추가 도움이 필요하면 지원팀에 문의하세요.

  5. 적용을 선택합니다.

권장사항을 적용한 후 애플리케이션이 거부되는 경우 취할 조치

권장사항을 적용한 후 앱 또는 웹사이트가 거부되는 것이 확인되면 API 응답 오류 메시지에 추가해야 하는 애플리케이션 제한사항을 찾아보세요.

클라이언트 측 SDK 및 API

브라우저 및 WebView 기반 앱

최신 브라우저는 일반적으로 개인 정보 보호를 위해 교차 출처 요청에서 Referer 헤더를 수정하여 Origin로 줄이는 경우가 많습니다. 그러나 정확한 동작은 호스팅 사이트에 적용된 referrer-policy에 따라 다르며 사용자 브라우저 및 버전에 따라 다를 수도 있습니다.

콘텐츠를 로드하기 위해 불투명 또는 로컬 URI 스키마를 사용하는 웹 애플리케이션에서는 일반적으로 렌더링 브라우저 또는 WebView가 모든 발신 호출에서 Referer 헤더를 완전히 삭제하므로 웹사이트 제한이 있는 API 키를 사용하여 요청이 실패할 수 있습니다.

자세한 내용은 서버에서 브라우저 기반 앱 호스팅을 참고하세요.

브라우저 및 WebView 기반 앱 문제 해결 안내:

  • Maps JavaScript API의 경우 애플리케이션을 승인하는 방법에 관한 자세한 내용은 브라우저 디버그 콘솔을 참고하세요.

    이국적인 URI 스키마는 부분적으로 지원됩니다. 애플리케이션의 일부가 필요한 리퍼러를 승인한 후에도 이국적인 URI 스키마로 작동하지 않으면 서버에서 애플리케이션을 원격으로 호스팅하고 HTTPS (또는 HTTP)를 통해 애플리케이션을 로드해야 할 수 있습니다.

    특수 URI 스키마와 관련하여 도움이 필요한 경우 지원팀에 문의하세요.

  • 다른 Maps Platform API는 일반적으로 클라이언트가 거부된 요청과 함께 이 정보를 전송했다고 가정하여 API 오류 응답에서 승인해야 하는 리퍼러를 반환합니다.

    특이한 URI 스키마는 지원되지 않습니다.

Android 앱

Android 디버그 브리지 (adb) 또는 Logcat 사용

iOS 앱

로그 메시지 보기를 참고하세요.

웹 서비스를 직접 호출하는 앱

클라이언트 측 Google Maps Platform SDK 없이 Maps Platform HTTPS REST API 또는 gRPC 엔드포인트를 직접 호출하는 애플리케이션의 경우 아래를 참고하세요.

Android 및 iOS 앱

Android 또는 iOS 애플리케이션이 사용 가능한 Google Maps Platform 클라이언트 SDK를 사용하지 않고 Maps Platform 서비스를 직접 호출하는 경우 추가 문제 해결 도움말은 Android 앱 및 iOS 앱을, 모바일 사용 사례에 관한 최신 보안 권장사항은 클라이언트 측 웹 서비스 호출 보안을 참고하세요.

앱에서 Maps Platform API 오류 응답을 로깅하는 경우 위의 클라이언트 측 SDK 안내가 인증 문제 해결에도 유용할 수 있습니다.

서버 측 앱

API 키를 사용하는 서버 측 애플리케이션은 IP 주소 제한을 통해 보호하는 것이 가장 좋습니다. 키에 IP 주소 제한을 적용했고 서비스 로그에 Maps Platform API 오류 응답이 로깅된 경우 시스템 로그에서 자세한 정보를 확인하세요. 오류 응답에는 승인해야 하는 서버 IP 주소가 포함됩니다.

브라우저 또는 WebView 기반 앱

Maps Static API, Street View Static API, 최신 Google Maps Platform API도 리퍼러 제한을 지원하지만 웹브라우저 또는 WebView는 교차 출처 요청의 경우 Referer 헤더를 Origin로 제한할 가능성이 높으며, 로컬에서 액세스하는 리소스 또는 HTTP 또는 HTTPS가 아닌 프로토콜을 통해 제공되는 리소스의 경우 전송을 아예 생략할 가능성이 높습니다.

애플리케이션에서 Maps JavaScript API를 사용할 수 없고 웹사이트 제한이 적용되지 않는 경우 브라우저 기반 클라이언트 측 애플리케이션 내에서 안전하게 Maps Platform 웹 서비스 호출을 실행하는 방법은 클라이언트 측 웹 서비스 호출 보호를 참고하세요.

API 제한사항 확인

필요한 API 제한사항을 확인하려면 API 키를 사용하는 API 확인을 참고하세요.

적용할 제한사항을 결정할 수 없는 경우:

  1. 현재 제한사항을 향후 참조를 위해 문서화합니다.
  2. 문제를 조사하는 동안 제한사항을 일시적으로 삭제합니다. API 키 사용량 확인의 단계에 따라 시간 경과에 따른 사용량을 확인할 수 있습니다.
  3. 필요한 경우 지원팀에 문의하세요.

사용하지 않는 API 키 삭제

API 키를 삭제하기 전에 프로덕션에서 사용하고 있지 않은지 확인하세요. 정상 트래픽이 없으면 키를 삭제해도 무방합니다. 자세한 내용은 API 키 사용 확인을 참고하세요.

API 키를 삭제하는 방법은 다음과 같습니다.

  1. Google Cloud 콘솔 Google Maps Platform 사용자 인증 정보 페이지를 엽니다.

  2. 삭제할 API 키를 선택합니다.

  3. 페이지 상단의 삭제 버튼을 선택합니다.

  4. 인증서 삭제 페이지에서, 삭제를 선택합니다.

    API 키 삭제가 반영되기까지 몇 분 정도 걸립니다. 키 삭제가 완료되면 삭제된 API 키를 사용하는 모든 트래픽이 거부됩니다.

API 키 순환 시 주의

API 키를 순환하면 이전 키의 제한사항이 모두 포함된 새 키가 생성됩니다. 이 기간에는 이전 키와 새 키가 모두 허용되므로 앱을 이전하여 새 키를 사용할 수 있습니다.

API 키를 순환하기 전에 다음을 실행합니다.

  • 먼저 API 키 제한에 설명된 대로 API 키를 제한하는 작업부터 시도해 보세요.

  • 애플리케이션 제한 유형이 충돌하여 API 키를 제한할 수 없는 경우 여러 API 키로 이전에 설명된 대로 여러 개의 새로운(제한된) 키로 이전합니다. 이전 작업을 통해 이전을 제어하고 타임라인을 새 API 키로 롤아웃할 수 있습니다.

이전 추천사항이 불가능하고 무단 사용을 방지하기 위해 API 키를 회전해야 하는 경우 다음 단계를 따르세요.

  1. Google Cloud 콘솔 Google Maps Platform 사용자 인증 정보 페이지를 엽니다.

  2. 순환하려는 API 키를 엽니다.

  3. 페이지 상단에서 키 회전을 선택합니다.

  4. 원하는 경우 API 키 이름을 변경합니다.

  5. 만들기를 선택합니다.

  6. 새 키를 사용하도록 애플리케이션을 업데이트합니다.

새 키를 사용하도록 애플리케이션을 업데이트한 후 새 API 키 페이지의 이전 키 섹션에 있는 이전 키 삭제 버튼을 클릭하여 이전 키를 삭제합니다.

여러 API 키로 이전

여러 앱에 하나의 API 키를 사용하는 방식에서 앱별로 하나의 고유 API 키를 사용하는 방식으로 이전하려면 다음 안내를 따르세요.

  1. 새 키가 필요한 앱을 파악합니다.

    • 웹 앱은 개발자가 모든 코드를 관리하므로 업데이트하기가 가장 쉽습니다. 모든 웹 기반 앱의 키를 업데이트할 계획을 세웁니다.
    • 모바일 앱의 경우 새 키를 사용하려면 고객이 각자의 앱을 업데이트해야 하므로 업데이트가 훨씬 더 어렵습니다.

  2. 새 키를 만들고 제한: 애플리케이션 제한과 하나 이상의 API 제한을 모두 추가합니다. 자세한 내용은 권장 권장사항을 참고하세요.

  3. 앱에 새 키 추가: 모바일 앱의 경우 모든 사용자가 새 API 키를 사용하여 최신 앱으로 업데이트할 때까지 이 프로세스에 몇 개월이 걸릴 수 있습니다.

클라이언트 측 사용량과 서버 측 사용량을 별도의 프로젝트로 분할

서버 측 애플리케이션과 최종 사용자 기기를 실행하는 클라이언트 측 애플리케이션에서 모두 Google Maps Platform 서비스를 호출해야 하는 경우 두 개의 별도 프로젝트 간에 사용량을 분할하는 것이 좋습니다.

이 접근 방식을 사용하면 클라이언트 측 프로젝트의 대부분의 Google Maps Platform 서비스에 적절한 분당 사용자별 할당량 제한을 적용할 수 있으므로 모든 최종 사용자가 서로 영향을 주지 않고 전체 프로젝트 할당량의 균등한 혜택을 누릴 수 있습니다.

그러나 사용자별 할당량 제한은 클라이언트 측 애플리케이션과 서버 측 애플리케이션 모두에 영향을 미치므로 서버 측 작업에도 높은 대역폭이 필요한 경우 이 사용 사례에 맞게 사용자별 할당량 한도를 더 높게 또는 아예 없도록 구성된 별도의 프로젝트를 설정하세요.

사용하지 않는 서비스 사용 중지

프로젝트에서 사용하지 않는 서비스를 사용 설정된 상태로 두지 마세요. 이 관행은 악용될 수 있으며 특히 모든 공개 API 키를 제한하지 않은 경우 더욱 그렇습니다. 애플리케이션에 필요한 경우에만 프로젝트에서 서비스를 사용 설정하는 것이 좋습니다.

키에 API 제한을 추가하면 승인되지 않은 서비스에서 키를 사용할 수 없지만 API 제한은 해당 키에만 적용됩니다. 프로젝트 수준에서 서비스를 사용 중지하여 프로젝트에 연결된 모든 키에서 서비스가 무단으로 사용되지 않도록 합니다.

클라이언트 측 SDK 사용

제공된 클라이언트 측 Google Maps Platform SDK를 사용하면 항상 API 키에 적절한 제한사항을 적용하여 서비스 사용을 보호할 수 있습니다.

클라이언트 측 SDK를 사용하면 이를 지원하는 Maps Platform API 노출 영역에서 Firebase 앱 체크와 같은 고급 보안 메커니즘을 채택할 수도 있습니다. 자세한 내용은 App Check를 사용하여 API 키 보호를 참고하세요.

플랫폼에서 클라이언트 측 SDK를 사용할 수 없는 경우 클라이언트 측 웹 서비스 호출 보호를 참고하세요.

다양한 플랫폼에서 클라이언트 측 Google Maps Platform SDK를 사용할 수 있는지 여부는 권장되는 애플리케이션 및 API 제한사항을 참고하세요.

Static Web API 사용 보호

Maps Static API 및 Street View Static API와 같은 정적 웹 API는 웹 서비스 API 호출과 유사합니다.

HTTPS REST API를 사용하여 둘 다 호출하고 일반적으로 서버에서 API 요청 URL을 생성합니다. 그러나 Static Web API는 JSON 응답을 반환하는 대신 생성된 HTML 코드에 포함할 수 있는 이미지를 생성합니다. 더 중요한 것은 일반적으로 서버가 아닌 최종 사용자 클라이언트가 Google Maps Platform 서비스를 호출한다는 것입니다.

디지털 서명 사용

가장 좋은 방법은 항상 API 키와 함께 디지털 서명을 사용하는 것입니다. 또한 하루에 허용할 서명되지 않은 요청 수를 검토하고 그에 따라 서명되지 않은 요청 할당량을 조정합니다.

디지털 서명에 대한 자세한 내용은 디지털 서명 가이드를 참고하세요.

서명 비밀번호 보호

Static Web API를 보호하려면 API 서명 비밀번호를 코드 또는 원본 트리에 직접 포함하거나 클라이언트 측 애플리케이션에 노출하지 마세요. 서명 비밀번호를 보호하기 위한 다음 권장사항을 따르세요.

  • 웹페이지를 게재할 때 또는 모바일 애플리케이션의 요청에 대한 응답으로 서버 측에서 서명된 Maps Static API 및 Street View Static API 요청 URL을 생성합니다.

    정적 웹 콘텐츠의 경우 Cloud 콘솔 Google Maps Platform 사용자 인증 정보 페이지에서 지금 URL 서명 위젯을 사용할 수 있습니다.

    동적 웹 콘텐츠의 경우 사용 가능한 URL 요청 서명 코드 샘플을 참고하세요.

  • 애플리케이션의 소스 코드 및 소스 트리 외부에 서명 비밀번호를 저장합니다. 서명 비밀번호 또는 기타 개인 정보를 환경 변수에 넣거나 별도로 저장된 파일을 포함한 후 코드를 공유하는 경우 서명 비밀번호가 공유 파일에 포함되지 않습니다. 서명 비밀번호 또는 기타 비공개 정보를 파일에 저장하는 경우, 소스 코드 관리 시스템에서 서명 비밀번호에 영향을 미치지 않도록 파일을 애플리케이션 소스 트리 외부에 보관합니다. 이 예방조치는 GitHub와 같은 공개 소스 코드 관리 시스템을 사용하는 경우에 특히 중요합니다.

웹 서비스 API 키 보호

클라이언트 측 앱에서 Google Maps Platform API 및 서비스를 안전하게 사용하려면 클라이언트 측 SDK 사용 및 클라이언트 측 웹 서비스 호출 보호를 참고하세요.

API 키를 애플리케이션의 소스 코드 또는 소스 트리 외부에 저장합니다. API 키 또는 기타 정보를 환경 변수에 포함하거나 별도로 저장된 파일을 포함한 후 코드를 공유하면 API 키가 공유 파일에 포함되지 않습니다. 이는 GitHub와 같은 공개 소스 코드 관리 시스템을 사용하는 경우에 특히 중요합니다.

웹 서비스 API 키가 실수로 사용되지 않도록 보호하려면 Maps Platform에 사용되는 모든 키에 API 제한사항을 적용하는 것이 좋습니다. 또한 웹 서비스 키에 IP 주소 제한사항을 적용하면 키가 실수로 유출되더라도 다른 소스 IP 주소의 무단 사용으로부터 키를 보호할 수 있습니다.

서버 측 앱에 OAuth 사용

OAuth 2.0은 액세스 위임을 위한 개방형 표준입니다.

OAuth 2.0 프로토콜은 최종 사용자가 애플리케이션이 사용자를 대신하여 개인 정보에 액세스하도록 승인하는 사용 사례를 지원하지만, Maps Platform에서 OAuth 2.0을 사용하는 의도된 사용 사례는 개발자가 임시 액세스 토큰을 활용하여 애플리케이션이 서비스 계정의 권한으로 Google Cloud 프로젝트 서비스 계정을 대신하여 API를 호출하도록 승인하는 것입니다.

서비스 계정에는 매우 광범위한 권한이 있을 수 있으므로 개발자의 신뢰할 수 있는 서버 측 애플리케이션과 Google의 Maps Platform 서버 간에 서버 간 호출을 승인하려면 OAuth 2.0을 사용하는 것이 좋습니다.

최종 사용자 기기에서 실행되는 클라이언트 측 애플리케이션의 경우 API 키와 같은 다른 인증 방법을 사용하는 것이 좋습니다.

OAuth 2.0을 사용하여 서버 간 트래픽을 승인하려면 API 문서에서 OAuth 주제를 찾아보세요.

예를 들어 다음은 Address Validation API와 관련된 OAuth 주제입니다.

클라이언트 측 웹 서비스 호출 보호

클라이언트 측 SDK를 사용할 수 없는 경우 아래 권장사항을 참고하세요.

프록시 서버 사용

보안 프록시 서버를 사용하면 API 키, 서명된 비밀 또는 Google Cloud 서비스 계정을 승인되지 않은 사용자에게 노출하지 않고 클라이언트 측 애플리케이션에서 Google Maps Platform 웹 서비스 엔드포인트와 상호작용할 수 있는 견고한 소스를 제공할 수 있습니다.

핵심 사항:

*   Construct your Google Maps Platform requests on the proxy server.
    **Don't** allow clients to relay arbitrary API calls using the proxy.

*   Post-process the Google Maps Platform responses on your proxy server.
Filter out data that the client doesn't need.

프록시 서버 사용에 대한 자세한 내용은 대리 장치: Google Data API 클라이언트 라이브러리에 프록시 서버 사용하기를 참고하세요.

직접 모바일 웹 서비스 호출 보호

클라이언트 측 앱에 보안 프록시 서버를 설정할 수 없는 경우 다음 단계에 따라 애플리케이션을 보호하세요.

  1. HTTP 헤더를 사용합니다.

    • Android: X-Android-Package 및 X-Android-Cert HTTP 헤더를 사용합니다.

    • iOS: X-Ios-Bundle-Identifier HTTP 헤더를 사용합니다.

  2. Android 또는 iOS 키에 해당하는 애플리케이션 제한사항을 추가합니다.

  3. 모바일 애플리케이션에서 Google Maps Platform REST API 웹 서비스로 직접 호출을 실행하려고 하기 전에 잘못된 Android 또는 iOS 애플리케이션 식별자가 있는 요청이 거부되는지 확인하세요.

    테스트된 엔드포인트에서 Android 및 iOS 애플리케이션 제한이 지원되지 않는 경우 모바일 클라이언트와 Google Maps Platform 웹 서비스 엔드포인트 간에 보안 프록시 서버를 사용하는 것이 적극적으로 권장됩니다.

Android 애플리케이션 도움말:

  • Android 애플리케이션을 Google Maps Platform 서비스와 통합하기 전에 애플리케이션 ID (패키지 이름이라고도 함)의 형식이 올바른지 확인합니다. 자세한 내용은 Android 문서의 앱 모듈 구성을 참고하세요.

  • 애플리케이션에서 X-Android-Package를 직접 전달하려면 Context.getPackageName()를 사용하여 프로그래매틱 방식으로 조회합니다.

  • 애플리케이션에서 X-Android-Cert를 직접 전달하려면 PackageInfo.signingInfo를 통해 액세스할 수 있는 애플리케이션 서명 인증서의 필수 SHA-1 지문을 계산합니다.

  • Google Cloud 콘솔을 사용하여 Android 애플리케이션을 승인하는 경우 UI는 SHA-1 지문이 콜론으로 구분된 문자열(예: 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33. 하지만 gcloud 도구와 API 키 API는 구분자가 없는 16진수 문자열을 예상합니다.

iOS 애플리케이션을 위한 팁:

  • iOS 애플리케이션을 Google Maps Platform 서비스와 통합하기 전에 번들 ID의 형식이 올바른지 확인합니다.

  • 일반적으로 iOS 애플리케이션을 승인할 때는 항상 X-Ios-Bundle-Identifier 헤더에서 기본 번들의 번들 ID를 전달해야 합니다.

자세한 내용은 API 키 관리 및 API 키를 사용하여 API에 액세스 도움말을 참고하세요.

서버에서 브라우저 기반 앱 호스팅

Apache Cordova와 같은 프레임워크를 사용하면 WebView 내에서 실행되는 멀티플랫폼 하이브리드 앱을 편리하게 만들 수 있습니다. 그러나 웹 앱이 개발자가 관리하고 승인한 웹사이트에서 HTTP 또는 HTTPS를 사용하여 로드되지 않는 한 API 키 웹사이트 제한이 올바르게 작동하지 않을 수 있습니다.

번들 리소스, 하이브리드 애플리케이션 내에서 로컬로 로드되거나 로컬 파일 URL을 사용하여 액세스되는 리소스는 대부분의 경우 리퍼러 기반 승인 기능이 작동하지 않도록 합니다. WebView를 실행하는 브라우저 엔진이 Referer 헤더 전송을 생략하기 때문입니다. 이를 방지하려면 웹 애플리케이션을 클라이언트 측이 아닌 서버 측에서 호스팅하세요.

또는 모바일 애플리케이션의 경우 웹 기반 SDK를 사용하는 대신 사용 가능한 네이티브 Google Maps Platform Android 및 iOS SDK를 사용하는 것이 좋습니다.

App Check을 사용하여 API 키 보호

특정 Maps SDK 및 API를 사용하면 Firebase 앱 체크와 통합할 수 있습니다. 앱 체크는 합법적인 앱 이외의 소스에서 발생하는 트래픽을 차단하여 앱에서 Google Maps Platform으로의 호출을 보호합니다. 이를 위해 증명 제공업체의 토큰을 확인합니다. 앱을 앱 체크와 통합하면 악의적인 요청으로부터 보호할 수 있으므로 승인되지 않은 API 호출에 대한 요금이 청구되지 않습니다.

App Check 통합 안내:

API 키 무단 사용 처리

승인되지 않은 API 키 사용이 감지되면 다음 단계에 따라 문제를 해결하세요.

  1. 키 제한: 여러 앱에서 동일한 키를 사용하는 경우 여러 API 키로 이전하고 각 앱에 별도의 API 키를 사용합니다. 자세한 내용은 다음을 참고하세요.

  2. Places SDK 또는 Maps JavaScript API를 사용하는 경우 App Check를 사용하여 API 키를 보호할 수도 있습니다.

  3. 다음에 해당하는 경우에만 키를 교체하거나 순환하세요.

    • 제한할 수 없거나 이미 제한된 키의 무단 사용을 감지했지만 앱 체크를 적용할 수 없습니다.

    • 애플리케이션의 합법적인 트래픽에 영향을 미칠 수 있더라도 API 키를 보호하고 악용을 중지하기 위해 더 신속하게 조치를 취해야 합니다.

    계속하기 전에 API 키 순환 시 주의를 읽어보세요.

  4. 여전히 문제가 있거나 도움이 필요한 경우 지원팀에 문의하세요.

권장되는 애플리케이션 및 API 제한

다음 섹션에서는 각 Google Maps Platform API, SDK 또는 서비스에 적합한 애플리케이션 및 API 제한을 제안합니다.

권장되는 API 제한

API 제한에 관한 다음 가이드라인은 모든 Google Maps Platform 서비스에 적용됩니다.

  • API 키를 사용 중인 API로만 제한하세요. 단, 다음과 같은 예외가 있습니다.

    • 앱에서 Android용 Places SDK 또는 iOS용 Places SDK를 사용하는 경우 사용하는 SDK 버전에 따라 Places API (신규) 또는 Places API를 승인하세요. 1

    • 앱에서 Maps JavaScript API를 사용하는 경우 항상 키에 Maps JavaScript API를 승인합니다.

    • 다음 Maps JavaScript API 서비스도 사용하는 경우 해당 API도 승인해야 합니다.

      서비스 API 제한
      경로 서비스 (기존) Directions API (기존)
      거리 행렬 서비스 (기존) Distance Matrix API (기존)
      고도 서비스 Elevation API
      지오코딩 서비스 Geocoding API
      장소 클래스, Place Autocomplete 위젯 (신규), Place Autocomplete Data API Places API (신규)2
      장소 라이브러리, 장소 서비스, 장소 자동 완성 위젯 Places API2

1 자세한 내용은 Android용 Places SDK 및 iOS용 Places SDK 문서를 참고하세요.

2 Places API (신규) 또는 Places API를 승인해야 하는지 확실하지 않은 경우 Maps JavaScript API 문서를 참고하세요.

예를 들면 다음과 같습니다.

  • Android용 Maps SDK 및 Android용 Places SDK를 사용 중인 경우 Android용 Maps SDK 및 Places API (신규)를 API 제한으로 포함합니다.

  • 웹사이트에서 Maps JavaScript API 고도 서비스 및 Maps Static API를 사용하는 경우 다음 API 모두에 대해 API 제한을 추가합니다.

    • Maps JavaScript API
    • Elevation API
    • Maps Static API

권장되는 애플리케이션 제한

웹사이트

Maps JavaScript API 서비스, Maps Static API 또는 Street View Static API를 사용하거나 HTTPS REST API 또는 gRPC를 통해 최신 Google Maps Platform 서비스를 직접 호출하는 웹사이트의 경우 웹사이트 애플리케이션 제한을 사용합니다.

1 모바일 애플리케이션의 경우 네이티브 Android용 Maps SDK 및 iOS용 Maps SDK 사용을 고려해 보세요.

2 모바일 애플리케이션의 경우 네이티브 Android용 Places SDK 및 iOS용 Places SDK 사용을 고려해 보세요.

3 정적 웹 API 사용 보호도 확인해 보세요.

Maps Embed API를 사용하는 웹사이트

Maps Embed API는 무료로 사용할 수 있지만 다른 서비스에서 악용되지 않도록 사용된 API 키를 제한해야 합니다.

권장사항: Maps Embed API 사용을 위한 별도의 API 키를 만들어 이 키를 Maps Embed API로만 제한합니다. 이렇게 제한하면 다른 Google 서비스에 키가 무단으로 사용되지 않도록 충분히 보호할 수 있습니다. Maps Embed API 키를 사용할 수 있는 위치를 완전히 제어하려면 웹사이트 애플리케이션 제한사항도 적용하는 것이 좋습니다.

Maps Embed API 사용을 별도의 API 키로 분리할 수 없는 경우 웹사이트 애플리케이션 제한을 사용하여 기존 키를 보호하세요.

웹 서비스를 사용하는 앱 및 서버

API 키와 함께 웹 서비스를 사용하는 신뢰할 수 있는 기업 내부 네트워크의 서버 및 클라이언트 측 앱의 경우 IP addresses 애플리케이션 제한을 사용합니다.

다음 API를 사용하는 앱 및 서버에 사용합니다.

4 모바일 애플리케이션의 경우 Navigation SDK를 사용하는 것이 좋습니다.

5 안전한 모바일 사용을 위해 보안 프록시 서버를 사용하세요.

6 클라이언트 측 애플리케이션의 경우 플랫폼에서 제공하는 네이티브 위치 정보 서비스를 사용하는 것이 좋습니다. 예를 들어 웹브라우저의 경우 W3C Geolocation, Android의 경우 LocationManager 또는 Fused Location Provider API, iOS의 경우 Apple Core Location 프레임워크를 사용할 수 있습니다.

7 모바일 애플리케이션의 경우 네이티브 Android용 Places SDK 및 iOS용 Places SDK 사용을 고려해 보세요.

8 안전한 클라이언트 측 사용을 위해 보안 프록시 서버를 사용하세요.

Android 앱

Android 앱의 경우 Android apps 애플리케이션 제한을 사용합니다. 다음 SDK를 사용하는 앱에 사용합니다.

또한 Secrets Gradle 플러그인을 사용하여 보안 비밀을 Android 매니페스트에 저장하는 대신 로컬 파일에서 보안 비밀을 삽입하여 실수로 API 키를 버전 제어에 체크인하지 않도록 합니다.

iOS 앱

iOS 앱의 경우 iOS apps 애플리케이션 제한을 사용합니다. 다음 SDK를 사용하는 앱 및 서버에 사용합니다.

추가 자료