HTTP 대상에 인증 사용

적절한 사용자 인증 정보가 있는 연결된 서비스 계정을 설정하면 Cloud Scheduler에서 인증이 필요한 HTTP 대상을 호출할 수 있습니다.

서비스 계정 설정

  1. HTTP 대상이 있는 Cloud Scheduler 작업에 사용할 서비스 계정이 아직 없으면 새 서비스 계정을 만듭니다. 다음에 유의하세요.

    • 서비스 계정은 Cloud Scheduler 작업이 생성된 프로젝트에 속해야 합니다.

    • 기본 Cloud Scheduler 서비스 계정(service-YOUR_PROJECT_NUMBER@gcp-sa-cloudscheduler.iam.gserviceaccount.com)을 사용하지 마세요. 이 Google 관리 서비스 계정(서비스 에이전트라고도 함)을 이 용도로 사용할 수 없습니다.

    • 프로젝트나 Cloud Scheduler Service Agent (roles/cloudscheduler.serviceAgent) 역할에서 기본 Cloud Scheduler 서비스 계정을 삭제하지 마세요. 삭제하면 작업의 서비스 계정에 적절한 역할이 있더라도 인증이 필요한 엔드포인트에 대한 403 응답이 발생합니다.

  2. 대상이 Google Cloud 내에 있으면 필요한 IAM 역할을 서비스 계정에 부여합니다. Google Cloud 내 각 서비스에는 특정 역할이 필요하며 수신 서비스는 자동으로 생성된 토큰을 확인합니다. 예를 들어 Cloud Run 및 2세대 Cloud Functions 함수의 경우 Cloud Run Invoker 역할을 추가해야 합니다.

    사용자 관리 서비스 계정으로 리소스를 배포하려면 배포자에게 해당 서비스 계정에 대한 iam.serviceAccounts.actAs 권한이 있어야 합니다. 서비스 계정을 만든 경우 이 권한이 자동으로 부여됩니다. 그렇지 않으면 올바른 권한이 있는 사용자가 서비스 계정에 대한 이 권한을 부여해야 합니다.

    권장사항: 이전 단계에서 Cloud Scheduler 작업이 타겟팅하는 서비스를 호출하기 위해 특별히 서비스 계정을 만든 경우 대상 서비스에 계정 및 호출자 권한을 바인딩하여 최소 권한의 원칙(보안 권장사항)을 따르는 것이 좋습니다. Google Cloud 콘솔 또는 gcloud CLI를 사용하여 이 작업을 수행할 수도 있습니다.

    콘솔

    1. Google Cloud 콘솔을 엽니다.

    콘솔로 이동

    2. 프로젝트를 선택합니다.

    3. 호출하려는 리소스 유형의 페이지로 이동합니다. 예를 들어 Cloud Run 서비스를 호출하는 경우 Cloud Run 서비스가 나열된 페이지로 이동합니다.

    4. 호출하려는 서비스 왼쪽에 있는 체크박스를 선택합니다. 서비스 자체를 클릭하지 마세요.

    5. 권한 탭을 클릭합니다. 정보 창이 표시되지 않으면 정보 패널 표시를 클릭한 후 권한을 클릭해야 할 수 있습니다.

    6. 주 구성원 추가를 클릭합니다.

    7. 주 구성원 추가 아래에 만든 서비스 계정의 이메일 주소를 입력합니다.

    8. 역할 할당 아래의 드롭다운 목록에서 부여할 역할을 선택합니다. 주 구성원에 필요한 권한만 포함된 역할을 선택하여 최소 권한의 원칙을 따르세요.

    9. 저장을 클릭합니다.

    gcloud

    add-iam-policy-binding 명령어를 실행합니다.

    gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member=PRINCIPAL --role=ROLE

    다음과 같이 바꿉니다.

    • RESOURCE_TYPE: 대상의 리소스 유형입니다. 예를 들어 Cloud Run 대상의 경우 run입니다.
    • RESOURCE_ID: 대상의 식별자입니다. 예를 들어 Cloud Run 대상의 서비스 이름입니다.
    • PRINCIPAL: 서비스 계정의 식별자입니다. serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS 형식을 사용합니다. 예를 들면 serviceAccount:my-service-account@my-project.iam.gserviceaccount.com입니다.
    • ROLE: 대상 서비스에서 호출하는 데 필요한 역할의 이름입니다. 예를 들어 Cloud Run 또는 2세대 Cloud Functions 대상의 경우 roles/run.invoker입니다.

    예:

    • Cloud Run 대상: 다음 명령어는 Cloud Run 서비스 my-service의 서비스 계정 my-service-account@my-project.iam.gserviceaccount.com에 Cloud Run 호출자 역할을 부여합니다.

      gcloud run add-iam-policy-binding my-service \
--member=my-service-account@my-project.iam.gserviceaccount.com \
--role=roles/run.invoker

    • Cloud Functions 대상: 다음 명령어는 2세대 Cloud Functions 함수 my-gen2-function의 서비스 계정 my-service-account@my-project.iam.gserviceaccount.com에 대한 2세대 Cloud Functions 함수에 필요한 Cloud Run 호출자 역할을 부여합니다.

      gcloud functions add-iam-policy-binding my-gen2-function \
--member=my-service-account@my-project.iam.gserviceaccount.com \
--role=roles/run.invoker --gen2

  3. 대상이 Google Cloud 외부에 있으면 수신 서비스가 수동으로 토큰을 확인해야 합니다.

  4. Cloud Scheduler API를 사용 설정하면 기본 Cloud Scheduler 서비스 계정이 자동으로 설정됩니다. 단, 이 2019년 3월 19일 이전에 사용 설정했으면 Cloud Scheduler Service Agent 역할을 수동으로 추가해야 합니다. 클라이언트 서비스 계정을 대신하여 대상을 인증하려면 헤더 토큰을 생성할 수 있어야 하기 때문입니다.

    프로젝트의 현재 액세스 권한을 봐서 프로젝트에 기본 Cloud Scheduler 서비스 계정이 설정되어 있고 Cloud Scheduler Service Agent 역할이 부여되어 있는지 확인할 수 있습니다. Google Cloud 콘솔을 사용하여 프로젝트의 액세스 권한을 보는 경우 Google 제공 역할 부여 포함 체크박스를 선택해야 합니다.

인증을 사용하여 스케줄러 작업 만들기

인증을 사용하는 작업을 만들려면 토큰 유형과 클라이언트 서비스 계정을 식별하는 이메일 주소를 create-job 요청에 추가해야 합니다.

Console

  1. 빈도를 평소대로 지정합니다.
  2. 대상 유형으로 HTTP를 지정합니다.
  3. URL 및 HTTP 메서드를 평소대로 지정합니다.
  4. 인증 헤더 목록에서 토큰 유형을 선택합니다. 일반적으로 OIDC(ID 토큰)가 사용되지만 *.googleapis.com에서 이러한 API로 호스팅되는 Google API에는 예외적으로 OAuth 액세스 토큰이 필요합니다.
  5. 서비스 계정에 클라이언트 서비스 계정 이메일을 지정합니다.
  6. 대상은 선택사항이며 OIDC 토큰의 수신자를 제한합니다. 일반적으로 작업의 대상 URL입니다(URL 매개변수 없음). 지정되지 않으면 기본적으로 전체 URL이 대상으로 사용됩니다(요청 매개변수 포함).

gcloud 

gcloud scheduler jobs create http JOB_ID \
  --schedule="FREQUENCY" --uri=URI \
  --oidc-service-account-email=CLIENT_SERVICE_ACCOUNT_EMAIL

다음을 바꿉니다.

  • JOB_ID: 작업 이름. 프로젝트 내에서 고유해야 합니다. 연결된 작업을 삭제하더라도 프로젝트에서 작업 이름을 다시 사용할 수 없습니다.
  • FREQUENCY: 작업 간격은 작업이 실행되는 빈도입니다(예: every 3 hours 또는 every 10 mins). Crontab 호환 문자열을 여기에 제공할 수 있습니다. (더 이상 사용하지 않는 것이 좋지만 기존 작업에는 계속 기존 App Engine 크론 구문이 지원됩니다.)
  • URI: 엔드포인트의 정규화된 URL
  • --oidc-service-account-email 또는 --oauth-service-account-email: 토큰 유형을 정의합니다. 일반적으로 OIDC가 사용되지만 *.googleapis.com에 이러한 API로 호스팅된 Google API에는 예외적으로 OAuth 토큰이 필요합니다.
  • CLIENT_SERVICE_ACCOUNT_EMAIL: 클라이언트 서비스 계정의 이메일.
  • 사용할 수 있는 다른 선택적 매개변수는 gcloud 명령줄 참조에 설명되어 있습니다.

토큰 유형 선택

Cloud Scheduler와 HTTP 대상 간에 인증하도록 Cloud 스케줄러에서 이메일로 식별되는 클라이언트 서비스 계정을 기반으로 헤더 토큰을 만들고 HTTPS를 사용하여 대상으로 보냅니다. 이때 ID(OIDC) 토큰 또는 OAuth(액세스) 토큰을 사용할 수 있습니다. 일반적으로 OIDC가 사용되지만 *.googleapis.com에 이러한 API로 호스팅된 Google API에는 예외적으로 OAuth 토큰이 필요합니다.

수동으로 Cloud Scheduler 서비스 계정에 Cloud Scheduler 서비스 에이전트 역할 추가

다음 중 하나가 참인 경우에만 필요합니다.

  • 2019년 3월 19일 이전에 Cloud Scheduler API를 사용 설정했습니다.
  • 서비스 계정에서 Cloud Scheduler 서비스 에이전트 역할 삭제

Cloud Scheduler 서비스 계정에는 Cloud Scheduler 서비스 에이전트 역할이 필요합니다. 이 역할이 없으면 Cloud Scheduler 작업이 실패합니다. Google Cloud 콘솔에서 또는 gcloud CLI를 사용하여 Cloud Scheduler 서비스 에이전트 역할을 Cloud Scheduler 서비스 계정에 추가할 수 있습니다.

콘솔

  1. Google Cloud 콘솔에서 Cloud Scheduler API 페이지로 이동합니다.

    Cloud Scheduler API로 이동

    상태 필드가 표시되고 상태가 사용 설정됨으로 표시되면 계속 진행합니다. 그렇지 않으면 사용 설정을 클릭합니다.

  2. Google Cloud 콘솔에서 설정 페이지로 이동합니다.

    설정으로 이동

  3. 프로젝트 번호를 찾아 복사합니다.

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

    IAM으로 이동

  5. 액세스 권한 부여를 클릭합니다. 액세스 권한 부여 창이 열립니다.

  6. 새 주 구성원 필드에 다음 형식의 이메일 주소를 추가합니다.

    service-PROJECT_NUMBER@gcp-sa-cloudscheduler.iam.gserviceaccount.com

    PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다.

  7. 역할 선택 목록에서 Cloud Scheduler 서비스 에이전트를 검색하여 선택합니다.

  8. 저장을 클릭합니다.

gcloud

  1. 프로젝트에 Cloud Scheduler API가 사용 설정되었는지 확인합니다.

    gcloud services list --enabled \
 --filter=cloudscheduler.googleapis.com

    • 다음 출력이 표시되면 API가 사용 설정된 것입니다.

      NAME: cloudscheduler.googleapis.com
TITLE: Cloud Scheduler API

    • 그렇지 않은 경우(예: Listed 0 items.가 표시되는 경우) API를 사용 설정합니다.

      gcloud services enable cloudscheduler.googleapis.com

  2. 프로젝트 번호를 찾습니다.

    gcloud projects describe PROJECT_ID --format='table(projectNumber)'

    PROJECT_ID를 프로젝트 ID로 바꿉니다.

  3. 번호를 복사합니다.

  4. Cloud Scheduler 서비스 계정에 Cloud Scheduler Service Agent 역할을 부여합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudscheduler.iam.gserviceaccount.com \
   --role roles/cloudscheduler.serviceAgent

    다음을 바꿉니다.

    • PROJECT_ID: 프로젝트 ID입니다.
    • PROJECT_NUMBER: 이전에 복사한 프로젝트 번호