API 키에 제한사항 추가

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

API 키는 Google Cloud에서 애플리케이션 또는 웹사이트를 식별합니다. API 키 제한사항을 통해 앱과 웹사이트만 키를 사용할 수 있습니다. 보안상의 이유로 다음을 지정하는 제한사항을 추가하는 것이 좋습니다.

• API 키를 사용할 수 있는 클라이언트 또는 웹사이트
• 애플리케이션에서 API 키를 사용하여 호출할 수 있는 Google Cloud API

클라이언트가 제한된 API 키를 사용하여 API 키 제한사항을 충족하지 않는 요청을 실행하는 경우 요청이 실패합니다. 예를 들어 API 키에 특정 도메인에서 HTTP 요청을 전송해야 하지만 다른 도메인에서 HTTP 요청을 수신한 경우 오류가 표시되며 요청이 거부됩니다.

CreateKey 메서드를 사용하여 API 키를 만들 때 제한사항을 추가하거나 UpdateKey 메서드를 사용하여 키를 만든 후에 제한사항을 추가할 수 있습니다. 이 페이지에서는 API 키에 추가할 수 있는 제한사항을 설명하고 이러한 제한사항을 추가하는 방법을 설명합니다.

시작하기 전에

이 페이지에서는 oauth2l 명령줄 도구와 함께 curl를 사용하여 API 키의 API에 요청을 보냅니다. API를 설정하기 위한 자세한 내용은 API 키 시작하기를 참조하세요.

클라이언트 제한 추가

클라이언트 제한사항은 API 키를 사용할 수 있는 웹사이트, IP 주소 또는 앱을 지정합니다. API를 호출하는 클라이언트 유형에 따라 클라이언트 제한을 추가합니다. 다음 유형의 클라이언트 제한 중 하나를 지정할 수 있습니다.

• browserKeyRestrictions: 키를 사용할 수 있는 HTTP 리퍼러 (웹사이트)입니다.
• serverKeyRestrictions: 키를 사용할 수 있는 호출자의 IP 주소입니다.
• androidKeyRestrictions: 키를 사용할 수 있는 Android 앱입니다.
• iosKeyRestrictions: 키를 사용할 수 있는 iOS 앱입니다.

참고: API 키별로 한 가지 유형의 클라이언트 제한만 설정할 수 있습니다. 예를 들어 API를 사용하는 Android 앱과 iOS 앱이 모두 있는 경우 각 클라이언트 앱 유형에 대해 별도의 API 키를 만들어야 합니다.

브라우저 제한사항 추가

다음 예에서는 UpdateKey 메서드를 호출하여 HTTP 리퍼러를 www.example.com로 제한하는 방법을 보여줍니다.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \
  --request PATCH \
  --data '{
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": "www.example.com"
      }
    }
    "etag": "ETAG"
  }'

operations.get의 응답에 "done": true가 포함된 경우 response에는 제한사항을 포함하여 업데이트된 Key가 포함됩니다.

다음 예시에서는 특정 URL 목록에서만 HTTP 요청을 허용하는 새 API 키를 만드는 방법을 보여줍니다.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \
  --request POST \
  --data '{
    "displayName" : "API key with browser restrictions",
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": ["www.example.com", "www.example-2.com"]
      }
    }
  }'

다음 표는 시나리오 및 브라우저 제한사항의 몇 가지 예시를 보여줍니다.

시나리오	제한사항
사이트의 모든 URL 허용	`allowedReferrers` 목록에 두 개의 URL을 설정해야 합니다. 하위 도메인이 없는 도메인의 URL, 경로에 대한 와일드 카드가 포함됩니다. 예를 들면 다음과 같습니다. example.com/* 하위 도메인의 와일드 카드와 경로에 와일드 카드를 포함하는 두 번째 URL입니다. 예를 들면 다음과 같습니다. *.example.com/*
특정 URL 허용	정확한 경로가 있는 URL을 추가합니다. 예를 들면 다음과 같습니다. www.example.com/path www.example.com/path/path
단일 하위 도메인 또는 네이키드 도메인의 모든 URL 허용	전체 도메인을 허용하려면 `allowedReferrers` 목록에 두 개의 URL을 설정해야 합니다. 끝에 대한 슬래시가 없는 도메인의 URL입니다. 예: www.example.com sub.example.com example.com 경로에 대한 와일드 카드가 포함된 도메인의 두 번째 URL입니다. 예: www.example.com/* sub.example.com/* example.com/*

서버 제한사항 추가

API 키를 사용할 수 있는 호출자의 IP 주소(예: 웹 서버 또는 크론 작업)를 하나 이상 지정할 수 있습니다. IP 주소는 다음 형식으로 지정할 수 있습니다.

• IPv4 (198.51.100.1)
• IPv6 (2001:db8::1)
• CIDR 표기법을 사용하는 서브넷 (198.51.100.0/24, 2001:db8::/64)

다음 예시에서는 allowedIps 목록으로 API 키를 만드는 방법을 보여줍니다.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with server restrictions with IPv4, IPv6 and CIDR",
    "restrictions" : {
      "serverKeyRestrictions": {
        "allowedIps": ["198.51.100.1","198.51.100.0/24","2001:db8::1","2001:db8::/64"]
      }
    }
  }'

Android 제한 추가

API 키 사용을 Android 앱으로만 제한할 수 있습니다. API 키를 만들거나 업데이트할 때 각 앱에 대해 패키지 이름과 20바이트 SHA-1 지문을 제공합니다.

예를 들어 keytool 유틸리티를 실행했고 다음 지문을 만들었다고 가정해 보겠습니다.

  Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

다음 예시에서는 androidKeyRestrictions에 패키지 및 패키지 이름을 사용하여 API 키를 만드는 방법을 보여줍니다.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with Android restrictions",
    "restrictions" : {
      "androidKeyRestrictions": {
        "allowedApplications": [
          {
            "sha1Fingerprint": "DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09",
            "packageName": "com.example.my.app"
          }
        ]
      }
    }
  }'

iOS 제한 추가

키를 만들거나 업데이트할 때 각 앱의 번들 ID를 제공하여 API 키 사용을 iOS 앱으로만 제한할 수 있습니다. 다음 예시에서는 API 키를 만들 때 iosKeyRestrictions를 설정하는 방법을 보여줍니다.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with iOs restrictions",
    "restrictions" : {
      "iosKeyRestrictions": {
        "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"]
      }
    }
  }'

API 제한사항 추가

API 제한을 사용하면 API 키를 사용해서 호출할 수 있는 Google Cloud API를 지정할 수 있습니다. 모든 API 키에 클라이언트 및 API 제한사항을 모두 추가하는 것이 좋습니다.

API 제한사항에서 서비스를 하나 이상 지정할 수 있습니다. 다음 예시에서는 새 API 키 사용을 translate.googleapis.com 및 datastore.googleapis.com 서비스로만 제한하는 방법을 보여줍니다.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
  }'

Cloud 프로젝트에서 사용 설정된 서비스 목록을 가져오려면 gcloud services list 명령어를 사용합니다.

특정 서비스에 사용할 API 키를 제한하는 것 외에도 각 서비스의 메서드를 선택적으로 지정하여 API 키를 추가로 제한할 수 있습니다. 다음 예시에서는 이전 키를 translate.googleapis.com의 허용된 메서드로 제한하는 방법을 보여줍니다.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions  \
  --request PATCH \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
          "methods": [
            "Get*",
            "DetectLanguage"
          ]
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
    "etag": "ETAG"
  }'

다음 단계

• Cloud 감사 로그 보기
• 문제해결