이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Cloud Run용 IAP 구성

이 페이지에서는 Cloud Run에서 IAP(Identity-Aware Proxy)를 사용 설정하고 인증을 위해 IAP로 라우팅하여 Cloud Run 서비스로 향하는 트래픽을 보호하는 방법을 설명합니다. Cloud Run에서 IAP를 사용 설정하면 기본 run.app URL 및 부하 분산기를 비롯한 모든 인그레스 경로에서 클릭 한 번으로 트래픽을 라우팅할 수 있습니다.

알려진 제한사항

프로젝트가 조직 내에 있어야 합니다.
ID가 동일한 조직 내에 있어야 합니다.
부하 분산기와 Cloud Run 서비스 모두에서 IAP를 구성할 수는 없습니다.
IAP가 사용 설정된 경우 Pub/Sub와 같은 일부 통합이 작동하지 않을 수 있습니다.

시작하기 전에

IAP API를 사용 설정합니다.

IAP API 사용 설정

필요한 역할

IAP를 사용 설정하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

프로젝트에 대한 Cloud Run 관리자 (roles/run.admin) 역할
IAP 지원 서비스에 대한 액세스 권한 부여: 프로젝트의 IAP 정책 관리자 (roles/iap.admin)
IAP 지원 서비스를 만들거나 기존 서비스를 업데이트하여 IAP를 사용 설정합니다.
- 배포된 컨테이너 이미지에 대한 Artifact Registry 리더 (roles/artifactregistry.reader)
- 서비스 ID에 대한 서비스 계정 사용자 (roles/iam.serviceAccountUser) 역할

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Cloud Run에서 IAP 사용 설정

Cloud Run에서 직접 IAP를 사용 설정하는 것이 좋습니다.

동일한 Cloud Run 서비스에서 IAP와 ID 및 액세스 관리 (IAM)를 모두 사용하는 경우 다음 조건을 참고하세요.

IAP 및 IAM 검사가 모두 실행됩니다.
IAP 검사가 먼저 이루어지며 IAP 구성에 따라 요청을 수락하거나 차단합니다.
요청이 IAP 검사를 통과하면 IAP는 자체 서비스 계정을 사용하여 Cloud Run의 IAM 검사에 인증합니다.
IAP 검사가 먼저 실행되므로 Pub/Sub와 같은 일부 서비스가 올바르게 인증되지 않을 수 있습니다.

Google Cloud 콘솔, Google Cloud CLI 또는 Terraform을 사용하여 Cloud Run에서 IAP를 사용 설정합니다.

콘솔

Cloud Run에 IAP를 사용 설정하면 IAP에서 Cloud Run 서비스를 호출할 수 있는 권한이 필요합니다. Google Cloud 콘솔을 사용하여 IAP를 사용 설정하는 경우 IAP 서비스 에이전트에 Cloud Run 호출자 역할(roles/run.invoker)을 할당하여 이 권한이 자동으로 부여됩니다.

Cloud Run에서 IAP를 사용 설정하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Cloud Run 페이지로 이동합니다.

Cloud Run으로 이동
새 서비스를 구성하고 배포하는 경우 컨테이너 배포를 선택한 다음 서비스를 선택합니다. 기존 서비스를 구성하고 배포하는 경우 서비스를 클릭한 후 새 버전 수정 및 배포를 클릭합니다.
새 서비스를 구성하는 경우 필요에 따라 초기 서비스 설정 페이지를 작성한 후 인증 필요를 선택합니다. IAP (Identity-Aware Proxy)를 선택합니다.
기존 서비스를 구성하고 배포하는 경우 서비스를 클릭한 후 인증 필요를 선택합니다. IAP (Identity-Aware Proxy)를 선택합니다.
정책 수정을 클릭하여 컨텍스트 인식 액세스 정책을 만듭니다.
- 하나 이상의 주 구성원을 추가하고, 원하는 경우 각 주 구성원이 애플리케이션 액세스를 위해 충족해야 하는 액세스 수준을 추가합니다.
- 저장을 클릭합니다.
저장을 클릭합니다.

gcloud

Cloud Run에서 직접 IAP를 사용 설정하려면 앱을 배포할 때 --iap 플래그를 추가하고 IAP 서비스 에이전트에 호출자 권한을 부여하세요.

다음 명령어 중 하나를 사용하여 Cloud Run 서비스를 배포합니다.

새 서비스의 경우 다음을 수행합니다.
```
gcloud beta run deploy SERVICE_NAME \
--region=REGION \
--image=IMAGE_URL \
--no-allow-unauthenticated \
--iap
```
기존 서비스의 경우 다음을 따르세요.
```
gcloud beta run services update SERVICE_NAME \
--region=REGION \
--iap
```
다음을 바꿉니다.
- SERVICE_NAME: Cloud Run 서비스의 이름
- REGION: Cloud Run 리전의 이름 예를 들면 europe-west1입니다.
- IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 형식을 따릅니다.
- PROJECT_NUMBER: Google Cloud 프로젝트 번호.
IAP 서비스 에이전트에 호출자 권한을 부여합니다.
```
gcloud run services add-iam-policy-binding SERVICE_NAME \
--region=REGION \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com \
--role=roles/run.invoker
```
다음을 바꿉니다.
- SERVICE_NAME: Cloud Run 서비스의 이름
- REGION: Cloud Run 리전의 이름 예를 들면 europe-west1입니다.
- PROJECT_NUMBER: Google Cloud 프로젝트 번호.
IAP가 사용 설정된 서비스가 구성되어 있는지 확인하려면 다음 명령어를 실행합니다.
```
gcloud beta run services describe SERVICE_NAME
```
출력에 다음 문자열이 포함됩니다.
```
Iap Enabled: true
```

이제 구성된 Cloud Run 서비스로 향하는 모든 트래픽을 컨테이너에 전달하기 전에 인증을 위해 IAP로 라우팅합니다.

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요.

Terraform을 사용하여 IAP를 사용 설정하려면 서비스 정의를 업데이트하고 호출자 권한을 IAP에 부여하는 IAM 정책 바인딩을 추가해야 합니다.

Terraform 구성의 google_cloud_run_v2_service 리소스에 iap_enabled = true를 추가하여 서비스에서 IAP를 사용 설정합니다.

resource "google_cloud_run_v2_service" "default" {
  provider = google-beta
  name     = "cloudrun-iap-service"
  location = "europe-west1"
  ingress      = "INGRESS_TRAFFIC_ALL"
  launch_stage = "BETA"
  iap_enabled  = true

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

다음과 같이 추가하여 IAP 서비스 에이전트에 roles/run.invoker 역할을 부여합니다.

resource "google_cloud_run_v2_service_iam_member" "iap_invoker" {
  provider = google-beta
  project = google_cloud_run_v2_service.default.project
  location = google_cloud_run_v2_service.default.location
  name = google_cloud_run_v2_service.default.name
  role   = "roles/run.invoker"
  member = "serviceAccount:service-"PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com"
}

여기에서 PROJECT_NUMBER를 프로젝트 번호로 바꿉니다.

(선택사항) 현재 IAM 정책 데이터를 가져오려면 Terraform 구성의 google_cloud_run_v2_service_iam_policy 리소스에 다음을 추가합니다.

data "google_cloud_run_v2_service_iam_policy" "policy" {
  project = google_cloud_run_v2_service.default.project
  location = google_cloud_run_v2_service.default.location
  name = google_cloud_run_v2_service.default.name
}

Cloud Run에서 IAP 중지

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 IAP를 중지할 수 있습니다.

콘솔

Cloud Run에서 IAP를 중지하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Cloud Run 페이지로 이동합니다.

Cloud Run으로 이동
수정하려는 기존 서비스를 클릭합니다.
보안을 클릭하고 공개 액세스 허용을 선택합니다.
저장을 클릭합니다.

gcloud

Cloud Run에서 직접 IAP를 중지하려면 앱을 배포할 때 --no-iap 플래그를 추가하세요.

다음 명령어 중 하나를 사용하여 Cloud Run 서비스를 배포합니다.

새 서비스의 경우 다음을 수행합니다.
```
gcloud beta run deploy SERVICE_NAME \
--region=REGION \
--image=IMAGE_URL \
--no-iap
```
기존 서비스의 경우 다음을 따르세요.
```
gcloud beta run services update SERVICE_NAME \
--region=REGION \
--no-iap
```
다음을 바꿉니다.
- SERVICE_NAME: Cloud Run 서비스의 이름
- REGION: Cloud Run 리전의 이름
- IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 형식을 따릅니다.
IAP가 사용 설정된 서비스가 더 이상 구성되어 있지 않은지 확인하려면 다음 명령어를 실행합니다.
```
gcloud beta run services describe SERVICE_NAME
```
출력에 다음 문자열이 더 이상 포함되지 않아야 합니다.
```
Iap Enabled: true
```

더 이상 구성된 Cloud Run 서비스로 향하는 모든 트래픽을 컨테이너에 전달하기 전에 인증을 위해 IAP로 라우팅하지 않습니다.

사용자 또는 그룹 액세스 관리

기본적으로 Cloud Run용 IAP는 Google 계정을 사용하여 조직 내 ID를 사용합니다. Google Cloud 콘솔 또는 gcloud CLI를 사용하여 Cloud Run 서비스에 대한 액세스 권한을 추가하거나 삭제할 수 있습니다.

콘솔

액세스 권한을 추가하거나 삭제하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Cloud Run 페이지로 이동합니다.

Cloud Run으로 이동
수정하려는 기존 서비스를 클릭한 다음 보안을 클릭합니다.
IAP에서 정책 수정을 클릭합니다.
액세스 권한을 추가하려면 주 구성원을 입력하고 원하는 경우 추가할 액세스 수준을 입력합니다.
기존 주 구성원의 액세스 권한을 삭제하려면 액세스 수준 옆에 있는 정책 삭제 아이콘을 클릭합니다.
저장을 클릭합니다.

gcloud

조직 내 개별 사용자 또는 그룹의 Cloud Run 서비스 액세스 권한을 추가하거나 삭제하려면 다음 명령어 중 하나를 실행합니다.

액세스 권한 추가:

gcloud beta iap web add-iam-policy-binding \
--member=user:USER_EMAIL \
--role=roles/iap.httpsResourceAccessor \
--region=REGION \
--resource-type=cloud-run \
--service=SERVICE_NAME

액세스 권한 삭제:

gcloud beta iap web remove-iam-policy-binding \
--member=user:USER_EMAIL \
--role=roles/iap.httpsResourceAccessor \
--region=REGION \
--resource-type=cloud-run \
--service=SERVICE_NAME

액세스 권한 보기:

gcloud beta iap web get-iam-policy \
--region=REGION \
--resource-type=cloud-run \
--service=SERVICE_NAME

다음을 바꿉니다.

USER_EMAIL: 사용자의 이메일 주소입니다.
REGION: Cloud Run 리전의 이름
SERVICE_NAME: Cloud Run 서비스의 이름

문제 해결

서비스 에이전트 오류로 인해 IAM 설정 오류가 발생함

새 프로젝트에서 IAP를 처음 사용 설정하면 다음 오류가 발생할 수 있습니다.

Setting IAM permissions failed

Cloud Run 서비스 에이전트가 실패했기 때문입니다. 이 문제를 해결하려면 다시 IAP를 사용 설정하거나 IAM 정책을 수동으로 설정하세요.

다음 단계

백엔드 서비스 또는 부하 분산기에서 IAP를 사용 설정하는 방법은 Cloud Run용 IAP 사용 설정을 참고하세요.
Cloud Run용 IAP를 사용 설정하는 데 문제가 있는 경우 오류 문제 해결을 참조하세요.
외부 ID 사용 설정
OAuth 구성 사용 설정
IAP 보안 리소스에 대한 액세스 관리
조직 정책을 사용하여 IAP 사용 설정 제어

Cloud Run용 IAP 구성 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

알려진 제한사항

시작하기 전에

필요한 역할

Cloud Run에서 IAP 사용 설정

콘솔

gcloud

Terraform

Cloud Run에서 IAP 중지

콘솔

gcloud

사용자 또는 그룹 액세스 관리

콘솔

gcloud

문제 해결

서비스 에이전트 오류로 인해 IAM 설정 오류가 발생함

다음 단계

Cloud Run용 IAP 구성