게시 액세스 권한 관리

Identity and Access Management (IAM)는 주 구성원이 액세스할 수 있는 리소스를 제어하는 데 도움이 되는 여러 가지 정책 유형을 제공합니다. 이 가이드에서는 Eventarc Advanced 버스에 이벤트 메시지를 게시할 때 액세스 정책을 사용하여 액세스를 제어하는 방법을 설명합니다.

IAM 액세스 정책은 리소스에 대한 액세스를 허용하거나 거부할 수 있습니다. 하지만 액세스 정책은 IAM 허용 및 거부 정책과 달리 이벤트 메시지 우선순위와 같은 특정 이벤트 컨텍스트 속성을 기반으로 액세스를 허용하거나 거부할 수 있습니다.

각 액세스 정책은 주 구성원을 식별하고, 규칙의 적용 가능성을 결정하는 조건을 정의하고, 세부적인 액세스 제어를 사용 설정할 수 있는 일련의 규칙입니다. 예를 들어 이벤트 컨텍스트 속성에 적용된 Common Expression Language (CEL) 표현식의 평가에 따라 Eventarc Advanced 버스에 이벤트 메시지의 하위 집합을 게시할 권한을 허용하거나 거부할 수 있습니다.

이 가이드에서는 먼저 액세스 정책을 만든 다음 정책 바인딩을 만들어 해당 정책을 Google Cloud 프로젝트에 연결하여 액세스 정책을 만들고 적용하는 방법을 설명합니다.

시작하기 전에

액세스 정책을 만들고 적용하기 전에 이벤트 메시지를 게시할 수 있는 Eventarc Advanced 버스를 만들어야 합니다.

  1. 다음 사항을 고려해야 합니다.

    • 액세스 정책은 Google Cloud 프로젝트에 적용되거나 바인딩되어야 합니다. 각 액세스 정책은 최대 5개의 프로젝트에 연결할 수 있으며 각 프로젝트에는 최대 5개의 액세스 정책을 연결할 수 있습니다. 지원되는 리전별Google Cloud 프로젝트당 버스 1개를 만들 수 있습니다. 프로젝트에 연결된 액세스 정책은 해당 프로젝트의 모든 Eventarc Advanced 버스에 대한 게시 액세스를 제어합니다.

    • 액세스 정책을 사용하여 Eventarc Advanced 버스에 대한 게시 액세스를 제어할 수 있지만 특정 버스의 메시지 구독에 대한 액세스는 제어할 수 없습니다. 지원되는 권한은 eventarc.messageBuses.publish입니다.

    • 액세스 제어는 이벤트 페이로드 콘텐츠가 아닌 이벤트 컨텍스트 속성에만 기반할 수 있습니다.

    • Google 소스에서 게시되고 거부된 이벤트 메시지는 삭제됩니다. 주 구성원이 이벤트 메시지를 직접 게시하면 Event published successfully 로그 메시지가 이를 나타냅니다. 하지만 액세스 정책의 조건에 의해 이벤트 메시지가 거부되면 다음과 유사한 오류가 발생합니다.

      ERROR: (gcloud.beta.eventarc.message-buses.publish)
PERMISSION_DENIED: Permission 'eventarc.googleapis.com/messageBuses.publish' denied on resource due to an IAM Access Policy.
This command is authenticated as user@example.com which is the active account specified by the [core/account] property.
'@type': type.googleapis.com/google.rpc.ErrorInfo
domain: iam.googleapis.com
metadata:
permission: eventarc.googleapis.com/messageBuses.publish
reason: IAM_PERMISSION_DENIED

  2. 아직 사용 설정하지 않았다면 Eventarc 및 IAM API를 사용 설정합니다.

    gcloud services enable eventarc.googleapis.com \
    eventarcpublishing.googleapis.com \
    iam.googleapis.com

  3. 인증을 설정합니다.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST API

    로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

      Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

    필요한 역할

    IAM 역할에는 Google Cloud 리소스에 특정 작업을 실행할 수 있는 권한 집합이 포함되어 있습니다.

    게시 액세스를 제어하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대해 다음 IAM 역할을 부여해 달라고 요청하세요.

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

    이러한 사전 정의된 역할에는 게시 액세스를 제어하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

    필수 권한

    게시 액세스 권한을 제어하려면 다음 권한이 필요합니다.

    • 액세스 정책을 만듭니다. iam.accessPolicies.create
    • 액세스 정책 적용:
      • iam.accessPolicies.bind
      • resourcemanager.projects.createPolicyBinding

    커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

    액세스 정책 만들기

    프로젝트의 Eventarc Advanced 버스에 게시할 때 액세스를 제어하는 액세스 정책을 만듭니다.

    Google Cloud CLI를 사용하거나 IAM v3 API에 직접 요청하여 액세스 정책을 만들 수 있습니다.

    gcloud

    gcloud beta iam access-policies create 명령어를 실행하여 액세스 정책을 만들 수 있습니다.

    gcloud beta iam access-policies create POLICY_ID \
    --project=POLICY_PROJECT_ID \
    --location=global \
    --details-rules=description="POLICY_DESCRIPTION",effect=EFFECT, \
    principals=[PRINCIPALS],excludedPrincipals=[EXCLUDED_PRINCIPALS], \
    permissions=[eventarc.googleapis.com/messageBuses.publish], \
    activationConditions={eventarc.googleapis.com={celCondition={expression="CEL_EXPRESSION"}}}

    다음을 바꿉니다.

    • POLICY_ID: 액세스 정책의 고유한 이름(예: my-access-policy)
    • POLICY_PROJECT_ID: 정책이 생성될 프로젝트의 Google Cloud 프로젝트 ID입니다.
    • POLICY_DESCRIPTION: 정책에 대한 설명입니다 (선택사항, 최대 256자).
    • EFFECT: 규칙의 효과 (ALLOW 또는 DENY)
    • PRINCIPALS: 이 규칙이 적용되는 ID입니다. 식별자 형식은 참조하려는 주 구성원 유형에 따라 다릅니다. 자세한 내용은 액세스 정책의 주 구성원 유형을 참고하세요.
    • EXCLUDED_PRINCIPALS: principals에 나열된 경우에도 규칙 적용에서 제외되는 ID입니다. 예를 들어 Google 그룹을 principals에 추가한 다음 해당 그룹에 속하는 특정 사용자를 제외할 수 있습니다.
    • CEL_EXPRESSION: 규칙 적용 가능성을 확인하기 위해 평가되는 CEL 표현식입니다(예: message.version != \"v1\"). 자세한 내용은 Common Expression Language 사용을 참고하세요.

    다음에 유의하세요.

    • --location 플래그는 액세스 정책의 위치를 지정하며 global여야 합니다.

    • --details-rules 플래그는 JSON 또는 YAML로 작성할 수 있는 액세스 정책 파일의 경로를 지정할 수 있습니다(예: --details-rules=path_to_file.json).

      여러 규칙을 구성할 때 플래그를 반복할 수도 있습니다. 각 규칙은 독립적으로 평가됩니다.

      액세스 정책에는 다음 형식이 사용됩니다.

      {
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ],
        "activationConditions": {
          "eventarc.googleapis.com": {
            "celCondition": {
              "expression": "CEL_EXPRESSION"
            }
          }
        }
      }
    ]
  }
}

    응답에는 요청에 해당하는 장기 실행 작업이 포함됩니다. 장기 실행 작업의 상태를 가져오는 방법을 알아보려면 이 문서의 장기 실행 작업의 상태 확인을 참고하세요.

    예

    다음 명령어는 지정된 주 구성원이 버스에 이벤트 메시지를 게시하도록 허용하지만 데이터 미디어 유형이 JSON인 경우에는 게시를 거부하는 액세스 정책을 만듭니다.

    gcloud beta iam access-policies create my-access-policy \
    --project=my-project-id \
    --location=global \
    --details-rules=description="Allow publishing to bus",effect=ALLOW,principals=[principal://goog/subject/user@example.com],permissions=[eventarc.googleapis.com/messageBuses.publish] \
    --details-rules=description="Deny publishing to bus if media type is JSON",effect=DENY,principals=[principal://goog/subject/user@example.com],permissions=[eventarc.googleapis.com/messageBuses.publish],activationConditions={eventarc.googleapis.com={celCondition={expression="message.datacontenttype=='application/json'"}}}

    REST API

    projects.locations.accessPolicies.create method를 사용하여 액세스 정책을 만들 수 있습니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • POLICY_DISPLAY_NAME: 선택사항입니다. 액세스 정책의 사람이 읽을 수 있는 이름입니다(예: '예시 정책'). 표시 이름은 최대 63자까지 가능합니다.
    • POLICY_DESCRIPTION: 선택사항입니다. 액세스 정책에 대한 인간이 읽을 수 있는 설명입니다(예: '설명 예'). 설명은 최대 256자까지 가능합니다.
    • EFFECT: 규칙의 효과입니다(ALLOW 또는 DENY).
    • PRINCIPALS: 이 규칙이 적용되는 ID입니다. 식별자 형식은 참조하려는 주 구성원 유형에 따라 다릅니다. 자세한 내용은 액세스 정책의 주 구성원 유형을 참고하세요.
    • EXCLUDED_PRINCIPALS: principals에 나열되어 있더라도 규칙 적용에서 제외되는 ID입니다. 예를 들어 Google 그룹을 principals에 추가한 다음 해당 그룹에 속하는 특정 사용자를 제외할 수 있습니다.
    • CEL_EXPRESSION: 규칙 적용 가능성을 확인하기 위해 평가되는 CEL 표현식입니다. 자세한 내용은 Common Expression Language 사용을 참고하세요.
    • POLICY_PROJECT_ID: 정책이 생성될 프로젝트의 Google Cloud 프로젝트 ID입니다.
    • POLICY_ID: 액세스 정책의 고유 이름입니다(예: my-access-policy).

    여러 규칙을 나열할 수 있습니다. 각 규칙은 독립적으로 평가됩니다. 한 규칙이 적용되지 않더라도 다른 규칙이 적용될 수 있습니다.

    JSON 요청 본문: 

    {
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ],
        "activationConditions": {
          "eventarc.googleapis.com": {
            "celCondition": {
              "expression": "CEL_EXPRESSION"
            }
          }
        }
      }
    ]
  }
}

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    응답에는 요청에 해당하는 장기 실행 작업이 포함됩니다. 장기 실행 작업의 상태를 가져오는 방법을 알아보려면 이 문서의 이 페이지에서 장기 실행 작업의 상태 확인을 참고하세요. 

    {
  "name": "projects/POLICY_PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-25T17:17:45.782370139Z",
    "target": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

    예

    다음 액세스 정책은 지정된 주 구성원이 버스에 이벤트 메시지를 게시하도록 허용하지만 메시지 우선순위가 HIGH인 경우에는 게시를 거부합니다.

    cat > request.json << 'EOF'
{
"displayName": "Eventarc Advanced access policy",
"details": {
  "rules": [
  {
    "description": "Allow publishing to bus",
    "effect": "ALLOW",
    "principals": [
      "principal://goog/subject/user@example.com"
    ],
    "permissions": [
      "eventarc.googleapis.com/messageBuses.publish"
    ]
  },
    {
      "description": "Deny publishing to bus if message priority is HIGH",
      "effect": "DENY",
      "principals": [
        "principal://goog/subject/user@example.com"
      ],
      "permissions": [
        "eventarc.googleapis.com/messageBuses.publish"
      ],
      "activationConditions": {
        "eventarc.googleapis.com": {
          "celCondition": {
            "expression": "message.priority == \"HIGH\""
          }
        }
      }
    }
  ]
}
}
EOF

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v3/projects/POLICY_PROJECT_ID/locations/global/accessPolicies?access_policy_id=POLICY_ID"

    액세스 정책 적용

    액세스 정책을 Google Cloud 프로젝트에 적용하기 위한 정책 바인딩을 만듭니다. 각 정책 바인딩은 액세스 정책 하나를 리소스 하나에 바인딩합니다.

    Google Cloud CLI를 사용하거나 IAM v3 API에 직접 요청하여 액세스 정책을 적용할 수 있습니다.

    gcloud

    gcloud beta iam policy-bindings create 명령어를 실행하여 정책 바인딩을 만들고 액세스 정책을 적용할 수 있습니다.

    gcloud beta iam policy-bindings create BINDING_ID \
    --project=BINDING_PROJECT_ID \
    --location=global \
    --policy=projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID \
    --target-resource=//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID

    다음을 바꿉니다.

    • BINDING_ID: 정책 바인딩의 고유 이름(예: my-access-policy-binding)
    • BINDING_PROJECT_ID: 바인딩이 생성될 프로젝트의 Google Cloud 프로젝트 ID입니다. Eventarc Advanced 버스가 생성된 프로젝트의 ID와 동일해야 하며 바인딩의 타겟을 나타냅니다.

    --location 플래그는 정책 바인딩의 위치를 지정하며 global이어야 합니다.

    응답에는 요청에 해당하는 장기 실행 작업이 포함됩니다. 장기 실행 작업의 상태를 가져오는 방법을 알아보려면 이 문서의 장기 실행 작업의 상태 확인을 참고하세요.

    예

    다음 명령어는 지정된 액세스 정책을 Google Cloud 프로젝트에 적용하는 정책 바인딩을 만듭니다.

    gcloud beta iam policy-bindings create my-access-policy-binding \
    --project=my-project-id \
    --location=global \
    --policy=projects/my-project-id/locations/global/accessPolicies/my-access-policy \
    --target-resource=//cloudresourcemanager.googleapis.com/projects/my-project-id

    REST API

    projects.locations.policyBindings.create method을 사용하여 정책 바인딩을 만들고 액세스 정책을 적용할 수 있습니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • BINDING_DISPLAY_NAME: 선택사항. 정책 바인딩의 사람이 읽을 수 있는 이름입니다(예: 'Example binding'). 표시 이름은 최대 63자까지 가능합니다.
    • BINDING_PROJECT_ID: 바인딩이 생성될 프로젝트의 Google Cloud 프로젝트 ID입니다. Eventarc Advanced 버스가 생성된 프로젝트의 ID와 동일해야 하며 바인딩의 타겟을 나타냅니다.
    • POLICY_PROJECT_ID: 정책이 생성된 프로젝트의 Google Cloud 프로젝트 ID입니다.
    • POLICY_ID: 바인딩할 액세스 정책의 이름입니다(예: my-access-policy).

    JSON 요청 본문: 

    {
  "display_name": "BINDING_DISPLAY_NAME",
  "target": {"resource": "//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID"},
  "policy_kind": "ACCESS",
  "policy": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID"
}

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    응답에는 요청에 해당하는 장기 실행 작업이 포함됩니다. 장기 실행 작업의 상태를 가져오는 방법을 알아보려면 이 문서의 이 페이지에서 장기 실행 작업의 상태 확인을 참고하세요. 

    {
  "name": "projects/BINDING_PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-25T17:17:45.782370139Z",
    "target": "projects/BINDING_PROJECT_ID/locations/global/policyBindings/POLICY_ID-binding",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

    장기 실행 작업의 상태 확인

    IAM REST API를 사용할 때 액세스 정책 또는 바인딩을 변경하는 메서드는 장기 실행 작업 (LRO)을 반환합니다. 장기 실행 작업은 요청의 상태를 추적하고 정책이나 바인딩 변경이 완료되었는지 여부를 나타냅니다.

    operations.get 메서드는 장기 실행 작업 상태를 반환합니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • OPERATION_NAME: 작업의 전체 이름입니다. 원래 요청에 대한 응답으로 이 이름이 수신됩니다.

      작업 이름은 다음 형식입니다.

      projects/PROJECT_ID/locations/global/operations/OPERATION_ID
    • PROJECT_ID: 작업이 반환되는 프로젝트의 Google Cloud 프로젝트 ID입니다.

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    다음과 비슷한 JSON 응답이 표시됩니다.

    {
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-28T00:05:12.006289686Z",
    "endTime": "2025-01-28T00:05:12.192141801Z",
    "target": "projects/PROJECT_ID/locations/global/accessPolicies/POLICY_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": true,
  "response": {
    ACCESS_POLICY
  }
}

    작업의 done 필드가 없으면 작업을 반복적으로 가져와서 해당 상태를 계속 모니터링합니다. 잘린 지수 백오프를 사용하여 각 요청 간에 지연을 일으킵니다. done 필드가 true로 설정되었으면 작업이 완료되었고 작업 가져오기를 중지할 수 있습니다.

    다음 단계