Google 인증 사용

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

이 주제에서는 Google 인증을 사용하도록 구성된 API 프록시를 설정하고 배포하는 방법을 설명합니다.

소개

Apigee에서는 Google OAuth 토큰 또는 OpenID Connect 토큰을 사용하여 Cloud Logging 및 Secret Manager와 같은 Google 서비스와 Cloud Functions 및 Cloud Run과 같은 특정 Google Cloud 제품에서 실행되는 커스텀 서비스로 인증할 수 있습니다.

이 기능을 사용하려면 다음 컨텍스트 중 하나에서 <Authentication> XML 요소를 구성해야 합니다.

ServiceCallout 정책
ExternalCallout 정책
TargetEndpoint 구성

이 주제에 설명된 대로 일부 기본 설정 단계를 완료하면 Apigee가 토큰 생성을 수행하고 인증 헤더를 수동으로 설정하거나 서비스 요청을 수정할 필요 없이 대상으로 지정된 Google 서비스 또는 커스텀 호스팅 서비스에 대해 보안 호출을 수행합니다. API 개발자의 관점에서 올바르게 구성된 API 프록시 내에서 Google 서비스를 호출하는 프로세스는 매끄럽게 처리됩니다.

API 프록시 구성 옵션

이 섹션에서는 <Authentication> XML 요소를 사용하여 Google OAuth 토큰이나 OpenID Connect 인증을 사용 설정할 수 있는 위치를 설명합니다.

구성 옵션	설명
ServiceCallout 정책	ServiceCallout 정책을 사용하면 API 프록시에서 다른 내부나 외부 서비스로 호출할 수 있습니다. 예를 들어 ServiceCallout을 사용하여 외부 Google 서비스나 커스텀 호스팅 서비스를 호출할 수 있습니다. 사용 세부정보 및 예시는 ServiceCallout 정책을 참조하세요.
ExternalCallout 정책	ExternalCallout 정책을 사용 설정하면 Apigee 정책으로 지원되지 않는 커스텀 동작을 구현하기 위해 gRPC 요청을 gRPC 서버로 전송할 수 있습니다. 사용 세부정보 및 예시는 ExternalCallout 정책을 참조하세요.
TargetEndpoint	Google 서비스 또는 커스텀 호스팅 서비스를 API 프록시 대상 엔드포인트로 지정합니다. 사용 세부정보 및 예시는 API 프록시 구성 참조를 참조하세요.

Google 인증 토큰 지원 컨텍스트

<Authentication> 요소에는 <GoogleAccessToken> 또는 <GoogleIDToken>이라는 2개의 하위 요소 구성이 포함됩니다. 다음 표에서는 이러한 요소가 지원되는 컨텍스트를 보여줍니다.

사용 기능	GoogleAccessToken	GoogleIDToken
ServiceCallout 정책	지원됨	지원됨
ExternalCallout 정책	지원되지 않음	지원됨
TargetEndpoint	지원됨	지원됨

배포 단계

이 섹션에서는 Google 인증을 사용하여 타겟팅된 Google 서비스나 커스텀 호스팅 서비스를 호출하는 API 프록시를 배포하는 방법을 설명합니다. Apigee와 Apigee Hybrid의 배포 단계를 따로 설명합니다.

참고: 공유 흐름 배포는 또한 지원되는 정책 및 TargetEndpoint 구성에서 Authentication 태그 사용을 지원합니다. 또한 공유 흐름 배포 API 문서를 참조하세요.

Apigee에 배포

다음 단계에서는 Apigee에서 API 프록시를 배포하는 방법을 설명합니다. 여기서 프록시는 Google 서비스 또는 커스텀 호스팅 서비스에 대해 인증된 호출을 수행하도록 구성됩니다. 이 단계에서는 이미 프록시를 만들었고 나열된 지원되는 컨텍스트 중 하나의 <Authentication> 요소를 포함한다고 가정합니다.

Apigee 조직이 생성된 동일한 Google Cloud 프로젝트에서 Google 서비스 계정을 만듭니다. Google 인증을 사용하도록 구성된 API 프록시를 배포할 때 이 서비스 계정의 이름을 제공해야 합니다. 그리고 생성되는 OAuth 토큰은 서비스 계정을 나타냅니다. Google Cloud Console 또는 gcloud 명령어를 사용하여 서비스 계정을 만들 수 있습니다. 서비스 계정 만들기 및 관리를 참조하세요.
배포를 수행하는 사용자(배포자)에게 서비스 계정에 대해 iam.serviceAccounts.actAs 권한을 부여합니다. 또한 서비스 계정 권한 정보를 참조하세요.
주의: 서비스 계정에 대해 서비스 계정 사용자 역할이 부여된 사용자는 이를 사용해서 서비스 계정이 액세스할 수 있는 모든 리소스에 간접적으로 액세스할 수 있습니다. 자세한 내용은 서비스 계정 사용자 역할을 참조하세요. 사용자 역할 할당으로 인한 영향을 최소화하기 위해 최소 권한으로 서비스 계정을 구성하는 것이 좋습니다.

참고: 배포자에게 이미 충분한 권한이 있으면 이 단계는 선택적일 수 있습니다. 예를 들어 UI를 통해 배포할 때 Google Cloud 사용자에게 프로젝트 소유자 역할이 있을 수 있습니다.
```
gcloud iam service-accounts add-iam-policy-binding \
SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member="MEMBER" \
  --role="roles/iam.serviceAccountUser"
```

각 항목의 의미는 다음과 같습니다.

PROJECT_ID: 프로젝트 ID입니다. ID는 조직 이름과 동일합니다.
SA_NAME: 서비스 계정을 만들 때 제공한 이름입니다.
MEMBER는 binding이 추가되는 구성원입니다. user|group|serviceAccount:email 또는 domain:domain 형식이어야 합니다.

대상으로 지정된 Google 서비스에 연결하는 데 필요한 권한을 서비스 계정에 부여합니다. 예를 들어 Google Logging 서비스를 호출하려는 경우에는 해당 서비스에 연결하는 데 필요한 권한이 이 서비스 계정에 포함되어야 합니다. 또한 역할 이해를 참조하세요.
Google 인증을 사용하도록 구성된 API 프록시를 배포하려면 먼저 다음이 필요합니다.
- 이전에 만든 서비스 계정의 이름입니다. 예를 들면 SA_NAME@PROJECT_ID.iam.gserviceaccount.com입니다.
- 배포를 수행하는 사용자(배포자)는 이미 서비스 계정에 대한 iam.serviceAccounts.actAs 권한이 있거나 권한을 부여받아야 합니다. 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.
구현한 Google 인증 구성을 포함하는 API 프록시를 배포합니다. Apigee UI 또는 API를 사용하여 프록시를 배포할 수 있습니다. 자세한 내용은 API 프록시 배포를 참조하세요.
- UI를 사용하는 경우 서비스 계정 이름을 제공하라는 메시지가 표시됩니다. 1단계에서 만든 프록시 서비스 계정의 이름을 사용합니다. 예를 들면 SA_NAME@PROJECT_ID.iam.gserviceaccount.com입니다.
- 다음은 Apigee 배포 API를 사용하여 프록시를 배포하려는 경우 사용할 수 있는 cURL 명령어의 예시입니다. 이 명령어에는 쿼리 매개변수로 서비스 계정 이름이 포함되어 있습니다. 1단계에서 만든 서비스 계정의 이름입니다.
```
curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
-H "Content-Type: application/json" -X POST
```
  각 항목의 의미는 다음과 같습니다.
  - TOKEN: Google 사용자 인증 정보 대신 가져와야 하는 OAuth 토큰입니다. 자세한 내용은 OAuth 2.0 액세스 토큰 가져오기를 참조하세요.
  - ORG_NAME: Apigee 조직 이름입니다.
  - ENV_NAME: API 프록시를 배포할 환경의 이름입니다.
  - SA_NAME: 서비스 계정을 만들었을 때 제공한 이름입니다.
  - PROJECT_ID: Google Cloud 프로젝트 ID(조직 이름과 동일)입니다.
배포가 완료되었으면 API 프록시를 테스트해서 Google 서비스가 필요한 응답을 반환하는지 확인합니다.

Apigee Hybrid에 배포

다음 단계에서는 Google 서비스에 대해 인증된 호출을 수행하도록 구성된 API 프록시를 Apigee Hybrid에 배포하는 방법을 설명합니다. 이 단계에서는 이미 프록시를 만들었고 나열된 지원되는 컨텍스트 중 하나의 <Authentication> 요소를 포함한다고 가정합니다.

다음 방법 중 하나를 사용하여 Apigee Hybrid 런타임 구성요소의 서비스 계정 및 키를 만듭니다.
참고: Apigee Hybrid를 설치할 때 apigee-runtime 서비스 계정을 이미 만든 경우 이 단계를 건너뛸 수 있습니다.
- Apigee Hybrid와 함께 제공되는 create-service-account 도구를 사용하여 apigee-runtime 서비스 계정을 만듭니다. 이 도구는 서비스 계정을 만들고 서비스 계정 키를 반환합니다. 자세한 내용은 create-service-account를 참조하세요.
- Google Cloud Console 또는 gcloud 명령어를 사용하여 서비스 계정을 만듭니다. 서비스 계정 만들기 및 관리를 참조하세요. 서비스 계정 키를 가져오려면 서비스 계정 키 만들기 및 관리를 참조하세요.
참고: 권한이 있는 모든 Google Cloud 프로젝트에서 런타임 서비스 계정을 만들 수 있습니다. Apigee 조직에 사용되는 것과 동일한 프로젝트에 만들 필요는 없습니다.
overrides.yaml 파일을 열고 Google 인증 기능을 필요로 하는 각 환경에 대해 서비스 계정 키 파일 경로를 지정합니다.
```
envs:
  - name: "ENVIRONMENT_NAME"
    serviceAccountPaths:
      runtime: "KEY_FILE_PATH"
```
참고: Google 인증 기능이 필요한 환경이 여러 개 있는 경우, 각 환경에 고유 서비스 계정을 지정하거나 모든 환경이 동일한 계정을 공유할 수 있습니다. 또한 서비스 계정 권한 정보를 참조하세요.

예를 들면 다음과 같습니다.
```
envs:
  - name: "test"
    serviceAccountPaths:
      runtime: "./service_accounts/my_runtime_sa.json"
```
apigeectl apply를 사용하여 재정의 파일을 클러스터에 적용합니다.
프록시 서비스 계정이라고 부르는 두 번째 서비스 계정을 만듭니다. 이 서비스 계정은 Apigee 조직을 만들기 위해 사용한 것과 동일한 Google Cloud 프로젝트에 있어야 합니다. Google 인증을 사용하도록 구성된 API 프록시를 배포할 때 이 서비스 계정의 이메일 주소를 제공해야 합니다. 그리고 생성되는 OAuth 토큰은 서비스 계정을 나타냅니다.
배포를 수행하는 사용자(배포자)에게 서비스 계정에 대해 iam.serviceAccounts.actAs 권한을 부여합니다. 또한 서비스 계정 권한 정보를 참조하세요.
주의: 서비스 계정에 대해 서비스 계정 사용자 역할이 부여된 사용자는 이를 사용해서 서비스 계정이 액세스할 수 있는 모든 리소스에 간접적으로 액세스할 수 있습니다. 자세한 내용은 서비스 계정 사용자 역할을 참조하세요. 사용자 역할 할당으로 인한 영향을 최소화하기 위해 최소 권한으로 서비스 계정을 구성하는 것이 좋습니다.

참고: 배포자에게 이미 충분한 권한이 있으면 이 단계는 선택적일 수 있습니다. 예를 들어 UI를 통해 배포할 때 Google Cloud 사용자에게 프로젝트 소유자 역할이 있을 수 있습니다.
```
gcloud iam service-accounts add-iam-policy-binding \
SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member="MEMBER" \
  --role="roles/iam.serviceAccountUser"
```

각 항목의 의미는 다음과 같습니다.

PROJECT_ID: 프로젝트 ID입니다. ID는 조직 이름과 동일합니다.
SA_NAME: 서비스 계정을 만들 때 제공한 이름입니다.
MEMBER는 binding이 추가되는 구성원입니다. user|group|serviceAccount:email 또는 domain:domain 형식이어야 합니다.

대상으로 지정된 Google 서비스에 연결하는 데 필요한 권한을 프록시 서비스 계정에 부여합니다. 예를 들어 Google Logging 서비스를 호출하려는 경우에는 해당 서비스에 연결하는 데 필요한 권한이 이 서비스 계정에 포함되어야 합니다. 또한 역할 이해를 참조하세요.
런타임에 프록시 서비스 계정을 가장하는 기능이 있는지 확인합니다. 이 기능을 제공하려면 런타임 서비스 계정에 프록시 서비스 계정에 대한 iam.serviceAccountTokenCreator 역할을 부여합니다. 또한 서비스 계정 권한 정보를 참조하세요. 예를 들면 다음과 같습니다.
```
gcloud iam service-accounts add-iam-policy-binding \
PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/iam.serviceAccountTokenCreator
```
각 항목의 의미는 다음과 같습니다.
- PROJECT_ID: 프로젝트 ID입니다. ID는 조직 이름과 동일합니다. 런타임 서비스 계정을 만들기 위해 조직과 연결된 프로젝트를 사용할 필요는 없습니다. 이 명령어에 사용한 프로젝트 ID가 올바른지만 확인하면 됩니다.
- PROXY_SA_NAME: 프록시 서비스 계정의 ID입니다.
- RUNTIME_SA_NAME: 런타임 서비스 계정의 ID입니다.
Google 인증을 사용하도록 구성된 API 프록시를 배포하려면 먼저 다음이 필요합니다.
- 이전에 만든 프록시서비스 계정의 이름입니다. 예를 들면 PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com입니다.
- 배포를 수행하는 사용자는 Apigee 조직이 프로비저닝된 Google Cloud 프로젝트에서 이미 iam.serviceAccounts.actAs 권한이 있거나 권한을 부여받아야 합니다. 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.
구현한 Google 인증 구성을 포함하는 API 프록시를 배포합니다. Apigee UI 또는 API를 사용하여 프록시를 배포할 수 있습니다. 자세한 내용은 API 프록시 배포를 참조하세요.
- UI를 사용하는 경우 서비스 계정 이름을 제공하라는 메시지가 표시됩니다. 이전에 만든 프록시서비스 계정의 이름을 사용합니다. 예를 들면 PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com입니다.
- 다음은 Apigee 배포 API를 사용하여 프록시를 배포하려는 경우 사용할 수 있는 cURL 명령어의 예시입니다. 이 명령어에는 쿼리 매개변수로 서비스 계정 이름이 포함되어 있습니다. 프록시 서비스 계정의 이름입니다.
```
curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
-H "Content-Type: application/json" -X POST
```
  각 항목의 의미는 다음과 같습니다.
  - TOKEN: Google 사용자 인증 정보 대신 가져와야 하는 OAuth 토큰입니다. 자세한 내용은 OAuth 2.0 액세스 토큰 가져오기를 참조하세요.
  - ORG_NAME: Apigee 조직 이름입니다.
  - ENV_NAME: API 프록시를 배포할 환경의 이름입니다.
  - PROXY_SA_NAME: 프록시 서비스 계정의 이름입니다.
  - PROJECT_ID: Google Cloud 프로젝트 ID(조직 이름과 동일)입니다.
배포가 완료되었으면 API 프록시를 테스트해서 Google 서비스가 필요한 응답을 반환하는지 확인합니다.

서비스 계정 권한 정보

Google 인증을 사용하도록 API 프록시를 구성하려면 다음 표에 설명된 대로 서비스 계정을 만들어야 합니다. 서비스 계정 만들기 및 관리도 참조하세요.

서비스 계정 필수 설명

프록시

Apigee 및 Apigee Hybrid

서비스 계정	필수	설명
프록시	Apigee 및 Apigee Hybrid	API 프록시에서 타겟팅된 Google 서비스에 인증된 호출을 수행하는 데 필요한 권한이 있습니다. Apigee 조직과 동일한 Google Cloud 프로젝트에 생성되어야 합니다. 배포를 수행하는 사용자(배포자)는 프록시 서비스 계정에 대한 `iam.serviceAccounts.actAs` 권한이 있거나 권한을 부여받아야 합니다. 특정 대상 Google 서비스에 연결하는 데 필요한 권한을 포함해야 합니다. 예를 들어 Google Logging 서비스를 호출하려는 경우에는 해당 서비스에 연결하는 데 필요한 권한이 이 서비스 계정에 포함되어야 합니다. 또한 역할 이해를 참조하세요. Google 인증을 사용하는 프록시를 배포할 때 서비스 계정 이름을 제공해야 합니다.
런타임	Apigee Hybrid에만 해당	Apigee 런타임이 API 프록시에서 요청된 Google 서비스에 대해 인증을 수행하기 위한 토큰을 생성하도록 허용합니다. 이 서비스 계정은 프록시 특정 서비스 계정을 '가장'하여 해당 계정을 대신해서 인증된 호출을 수행합니다. 프록시 서비스 계정을 가장하고 토큰을 만들 수 있으려면 런타임 서비스 계정에 프록시 서비스 계정에 대한 `roles/iam.serviceAccountTokenCreator` 역할이 부여되어야 합니다. 서비스 계정에 대한 액세스 관리를 참조하세요.

API 프록시에서 타겟팅된 Google 서비스에 인증된 호출을 수행하는 데 필요한 권한이 있습니다.

Apigee 조직과 동일한 Google Cloud 프로젝트에 생성되어야 합니다.
배포를 수행하는 사용자(배포자)는 프록시 서비스 계정에 대한 iam.serviceAccounts.actAs 권한이 있거나 권한을 부여받아야 합니다.
특정 대상 Google 서비스에 연결하는 데 필요한 권한을 포함해야 합니다. 예를 들어 Google Logging 서비스를 호출하려는 경우에는 해당 서비스에 연결하는 데 필요한 권한이 이 서비스 계정에 포함되어야 합니다. 또한 역할 이해를 참조하세요.
Google 인증을 사용하는 프록시를 배포할 때 서비스 계정 이름을 제공해야 합니다.

런타임

Apigee Hybrid에만 해당

Apigee 런타임이 API 프록시에서 요청된 Google 서비스에 대해 인증을 수행하기 위한 토큰을 생성하도록 허용합니다. 이 서비스 계정은 프록시 특정 서비스 계정을 '가장'하여 해당 계정을 대신해서 인증된 호출을 수행합니다.

프록시 서비스 계정을 가장하고 토큰을 만들 수 있으려면 런타임 서비스 계정에 프록시 서비스 계정에 대한 roles/iam.serviceAccountTokenCreator 역할이 부여되어야 합니다. 서비스 계정에 대한 액세스 관리를 참조하세요.