API 키로 API 액세스 제한

OpenAPI | gRPC

API 키를 사용하여 특정 API 메서드 또는 API의 모든 메서드에 대한 액세스를 제한할 수 있습니다. 이 페이지에서는 API 키가 있는 클라이언트로 API 액세스를 제한하는 방법과 API 키를 만드는 방법을 설명합니다.

Extensible Service Proxy(ESP)는 Service Control API를 사용하여 API 키를 검증하고 API 키와 프로젝트의 사용 설정된 API 간의 연결을 검증합니다. API에 API 키 요구사항을 설정하면 보호되는 메서드, 클래스 또는 API에 대한 요청은 내 프로젝트나 내가 API 사용 설정 권한을 부여한 개발자가 소유한 다른 프로젝트에서 생성된 키가 포함된 경우를 제외하고는 모두 거부됩니다. API 키가 생성된 프로젝트는 로깅되지 않으며 요청 헤더에 추가되지 않습니다. 하지만 특정 소비자 프로젝트용 필터의 설명대로 Endpoints > 서비스에서 클라이언트와 연결된 Google Cloud 프로젝트를 확인할 수 있습니다.

API 키를 만들어야 하는 Google Cloud 프로젝트에 대한 자세한 내용은 API 키로 보호되는 API 공유를 참조하세요.

모든 API 메서드에 대한 액세스 제한

API의 모든 메서드에 액세스하는 데 API 키가 필요하도록 하려면 다음 안내를 따르세요.

텍스트 편집기에서 프로젝트의 openapi.yaml 파일을 엽니다.
샘플 코드 스니펫과 같이 securityDefinitions: 아래에 api_key: 값 apiKey, key, query를 추가합니다.
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
이렇게 하면 API를 보호하는 데 사용할 수 있는 api_key이라는 보안 스키마가 설정됩니다. 다른 api_key 정의 옵션은 Api 키 정의 제한사항을 참조하세요.
파일의 최상위 수준(들여쓰기가 적용되거나 중첩되지 않음)에서 security 지시문에 api_key: []를 추가합니다. security 지시문을 추가해야 할 수도 있고 이 지시문이 이미 있을 수도 있습니다.
```
  security:
    - api_key: []
```
이 지시문은 파일의 모든 메서드에 api_key 보안 스키마를 적용합니다. 대괄호 안은 비워두세요. OpenAPI 사양에 따르면 OAuth를 사용하지 않는 보안 스키마는 빈 목록이어야 합니다.

특정 API 메소드에 대한 액세스 제한

특정 메서드에 API 키가 필요하도록 하려면 다음 안내를 따르세요.

텍스트 편집기에서 프로젝트의 openapi.yaml 파일을 엽니다.
파일의 최상위 수준(들여쓰기가 적용되거나 중첩되지 않음)에서 빈 security 지시문을 추가하여 전체 API에 적용합니다.
```
security: []
```
샘플 코드 스니펫과 같이 securityDefinitions: 아래에 api_key: 값 apiKey, key, query를 추가합니다.
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
이렇게 하면 API를 보호하는 데 사용할 수 있는 api_key이라는 보안 스키마가 설정됩니다. 다른 api_key 정의 옵션은 Api 키 정의 제한사항을 참조하세요.
메서드 정의의 security 지시문에 api_key: []를 추가합니다.
```
...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...
```
이 지시문은 메서드에 api_key 보안 스키마를 적용합니다. 대괄호 안은 비워두세요. OpenAPI 사양에 따르면 OAuth를 사용하지 않는 보안 스키마는 빈 목록이어야 합니다.

메소드의 API 키 제한 삭제

API에 대한 API 액세스를 제한한 경우에도 특정 메서드에 대한 API 키 검증을 끄려면 다음 단계를 따르세요.

텍스트 편집기에서 프로젝트의 openapi.yaml 파일을 엽니다.

메서드 정의에 빈 security 지시문을 추가합니다.

...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security: []
  produces:
  ...

API 키를 사용하여 API 호출

API 또는 API 메서드에 API 키가 필요하면 다음의 curl 예시와 같이 쿼리 매개변수 key를 사용하여 키를 제공합니다.

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

여기에서 ENDPOINTS_HOST 및 ENDPOINTS_KEY는 각각 API 호스트 이름과 API 키입니다.

API 키로 보호되는 API 공유

API 키는 키가 생성된 Google Cloud 프로젝트와 연결됩니다. API에 API 키가 필요하도록 결정했다면 API 키가 생성되는 Google Cloud 프로젝트는 다음 질문에 대한 답에 따라 달라집니다.

할당량과 같은 Endpoints 기능을 사용할 수 있도록 API 호출자를 구별해야 하나요?
모든 API 호출자에게 자체 Google Cloud 프로젝트가 있나요?
API 키 제한을 다양하게 설정해야 하나요?

다음과 같은 결정 트리를 참조하여 API 키를 만들 Google Cloud 프로젝트를 결정할 수 있습니다.

API를 사용 설정하도록 권한 부여

API 호출자를 구분하고 각 호출자에게 자체 Google Cloud 프로젝트가 있도록 해야 한다면 주 구성원에게 자체 Google Cloud 프로젝트에서 API를 사용 설정할 수 있는 권한을 부여하면 됩니다. 이렇게 하면 API 사용자는 API에서 사용할 자체 API 키를 만들 수 있습니다.

예를 들어 팀에서 회사의 다양한 클라이언트 프로그램에서 내부적으로 사용할 API를 만들었고 각 클라이언트 프로그램에 자체 Google Cloud 프로젝트가 있다고 가정해 보겠습니다. API 호출자를 구분하기 위해 각 호출자의 API 키는 서로 다른 Google Cloud 프로젝트에서 생성되어야 합니다. 동료에게 클라이언트 프로그램이 연결된 Google Cloud 프로젝트에서 API를 사용 설정할 수 있는 권한을 부여할 수 있습니다.

사용자가 자체 API 키를 만들도록 허용하려면 다음 안내를 따르세요.

API가 구성된 Google Cloud 프로젝트에서 각 사용자에게 API 사용 설정 권한을 부여합니다.
사용자에게 자체 Google Cloud 프로젝트에서 API를 사용 설정하고 API 키를 만들 수 있음을 알립니다.

각 호출자별로 별도의 Google Cloud 프로젝트 만들기

API 호출자를 구분해야 하고 호출자 중에 Google Cloud 프로젝트가 없는 경우가 있으면 각 호출자별로 별도의 Google Cloud 프로젝트와 API 키를 만들 수 있습니다. 프로젝트를 만들기 전에 프로젝트와 연결된 호출자를 손쉽게 식별할 수 있도록 프로젝트 이름을 생각해 둡니다.

예를 들어 외부 API 고객이 있고, API를 호출하는 클라이언트 프로그램이 어떻게 만들어졌는지 모르는 경우를 가정해 보겠습니다. Google Cloud 서비스를 사용하고 Google Cloud 프로젝트가 있는 클라이언트도 있고 그렇지 않은 클라이언트도 있습니다. 호출자를 구분하려면 각 호출자별로 별도의 Google Cloud 프로젝트와 API 키를 만들어야 합니다.

각 호출자별로 별도의 Google Cloud 프로젝트와 API 키를 만들려면 다음 안내를 따르세요.

각 호출자별로 별도의 프로젝트를 만듭니다.
각 프로젝트에서 API를 사용 설정하고 API 키를 만듭니다.
각 호출자에게 API 키를 제공합니다.

각 호출자별 API 키 만들기

API 호출자를 구분할 필요가 없지만 API 키 제한사항을 추가하려는 경우, 동일 프로젝트에서 각 호출자에 대해 별도의 API 키를 만들 수 있습니다.

동일한 프로젝트 내 각 호출자별로 API 키를 만들려면 다음 안내를 따르세요.

API가 구성된 프로젝트 또는 API가 사용 설정된 프로젝트에서 필요한 API 키 제한이 있는 각 고객의 API 키를 만듭니다.
각 호출자에게 API 키를 제공합니다.

모든 호출자를 위한 하나의 API 키 만들기

API 호출자를 구분할 필요가 없고 API 제한사항을 추가할 필요가 없지만 API 키가 여전히 필요한 경우(예: 익명 액세스 방지), 모든 호출자가 사용할 하나의 API 키를 만들 수 있습니다.

모든 호출자를 위한 하나의 API 키를 만들려면 다음 안내를 따르세요.

API가 구성된 프로젝트 또는 API가 사용 설정된 프로젝트에서 모든 호출자를 위한 API 키를 만듭니다.
모든 호출자에게 동일한 API 키를 제공합니다.

권장사항

API 키를 사용하여 API 및 사용자 데이터에 대한 액세스를 보호하는 경우 Extensible Service Proxy V2(ESPv2) 시작을 구성할 때 --service_control_network_fail_open 플래그를 close로 설정해야 합니다. 플래그의 기본값은 open.입니다.

ESPv2는 Service Control을 호출하여 API 키를 확인합니다. Service Control에 연결할 때 네트워크 오류가 있고 ESPv2에서 API 키를 확인할 수 없으면 사기성 키가 있는 API에 대한 잠재적인 요청이 거부됩니다.