통합 액세스 정책(UAP)을 사용하면 주 구성원에게Google Cloud 리소스에 대한 액세스 권한을 부여하거나 거부할 수 있습니다. 이 문서에서는 기존 UAP를 수정하고 UAP가 적용되는 리소스를 수정하는 방법을 설명합니다.
시작하기 전에
인증을 설정합니다.
이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.
콘솔
Google Cloud 콘솔을 사용하여 Google Cloud 서비스 및 API에 액세스하는 경우 인증을 설정할 필요가 없습니다.
gcloud
Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.
Google Cloud 콘솔 하단에서 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.
REST
로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.
Google Cloud CLI를 설치합니다.
외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.
(선택사항) UAP 개요를 읽어봅니다.
필요한 역할
UAP를 수정하는 데 필요한 권한을 얻으려면 관리자에게 수정하려는 UAP를 소유한 프로젝트, 폴더 또는 조직에 대한 액세스 정책 관리자(roles/iam.accessPolicyAdmin) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 UAP를 수정하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
UAP를 수정하려면 다음 권한이 필요합니다.
-
iam.accesspolicies.update -
Google Cloud 콘솔에서 UAP를 수정합니다.
-
iam.accesspolicies.get -
iam.accessPolicies.list
-
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
기존 통합 액세스 정책 수정
UAP를 수정하여 표시 이름 또는 규칙을 업데이트할 수 있습니다.
Google Cloud 콘솔, gcloud CLI 또는 IAM REST API를 사용하여 UAP를 수정할 수 있습니다.
콘솔
-
Google Cloud 콘솔에서 통합 액세스 정책 페이지로 이동합니다.
통합 액세스 정책으로 이동 - 수정하려는 UAP를 소유한 프로젝트, 폴더 또는 조직을 선택합니다.
- 수정하려는 UAP의 정책 ID를 클릭합니다.
-
규칙을 추가하려면 광고 규칙 추가를 클릭한 후 규칙 세부정보를 추가합니다. 규칙을 저장하려면 규칙 추가를 클릭합니다.
규칙의 필드에 대한 자세한 내용은 UAP 만들기를 참조하세요.
- UAP의 다른 필드를 수정하려면 정책 수정을 클릭합니다.
-
다음 필드를 수정합니다.
- 정책 이름: UAP의 새 표시 이름을 입력합니다.
- 규칙: UAP에서 규칙을 업데이트, 추가 또는 삭제합니다.
- UAP 수정을 완료하면 정책 업데이트를 클릭합니다.
gcloud
gcloud iam access-policies update 명령어는 기존 UAP를 업데이트합니다.
아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
-
UAP_ID: 업데이트하려는 UAP의 ID입니다(예:example-policy). -
UAP_PARENT_RESOURCE_TYPE: 업데이트하려는 UAP를 소유하는 Resource Manager 리소스(프로젝트, 폴더 또는 조직)의 유형입니다.project,folder,organization값을 사용합니다. -
UAP_PARENT_RESOURCE_ID: 업데이트하려는 UAP를 소유한 프로젝트, 폴더 또는 조직의 ID입니다. 프로젝트 ID는my-project같은 영숫자 문자열입니다. 폴더 및 조직 ID는123456789012와 같은 숫자입니다. -
FIELD_TO_UPDATE=UPDATED_VALUE: 업데이트할 필드와 업데이트된 해당 값입니다.다음은 정책의 필드를 업데이트하는 데 사용할 수 있는 플래그 예시입니다.
-
--display-name=DISPLAY_NAME: UAP의 표시 이름을 지정된 이름으로 바꿉니다. -
--details-rules=RULES_FILE: UAP 규칙을 지정된 파일의 규칙으로 바꿉니다. 파일의 각 규칙은 다음 형식이어야 합니다.{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
다음 값을 바꿉니다.
-
DESCRIPTION: 인간이 읽을 수 있는 규칙에 대한 설명입니다. -
EFFECT: 규칙이 액세스에 미치는 영향입니다. 지원되는 값은ALLOW및DENY입니다.-
ALLOW: 지정된 주 구성원에게 지정된 권한을 부여합니다. -
DENY: 지정된 주 구성원이 지정된 권한을 사용하지 못하도록 방지합니다.
-
-
다음 값을 바꿔 규칙에 포함된 주 구성원을 지정합니다.
-
INCLUDED_PRINCIPALS: 규칙에 포함할 주 구성원입니다. -
EXCLUDED_PRINCIPALS: 선택사항. 포함된 주 구성원 목록에 있더라도 규칙에서 제외할 주 구성원입니다. 예를 들어 포함된 주 구성원 목록에 Google 그룹을 추가한 다음 해당 그룹에 속한 특정 사용자를 제외할 수 있습니다.
지원되는 주 구성원 식별자 목록은 UAP의 주 구성원 유형을 참조하세요.
-
-
다음 값을 바꿔 규칙에 포함할 권한을 지정합니다.
-
INCLUDED_PERMISSIONS: 규칙에 포함할 권한입니다. -
EXCLUDED_PERMISSIONS: 선택사항. 포함된 권한 목록에 있더라도 규칙에서 제외할 권한입니다. 예를 들어 포함된 권한 목록에 역할을 추가한 다음 해당 역할에서 특정 권한을 제외할 수 있습니다.
이러한 권한 목록을 만들 때 권한 이름, 역할 이름, 권한 그룹을 참조할 수 있습니다. 자세한 내용은 UAP 규칙의 역할 및 권한을 참조하세요.
-
-
CONDITIONS: 선택사항. 규칙이 적용되는 조건입니다. 다음 형식을 사용합니다."conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
다음 값을 바꿉니다.
-
SERVICE: 조건 표현식에 사용되는 속성을 제공하는 서비스입니다. -
CONDITION_TITLE: 선택사항. 조건 목적에 대한 간단한 요약입니다. -
CONDITION_DESCRIPTION: 선택사항. 조건에 대한 자세한 설명입니다. -
CONDITION_EXPRESSION: 액세스 시도에서 리소스에 연결된 태그와 같은 액세스 시도의 속성을 참조하는 불리언 표현식입니다. 표현식이true로 평가되면 액세스 시도에 규칙이 적용됩니다.false로 평가되면 액세스 시도에 규칙이 적용되지 않습니다.
지원되는 속성 및 해당 서비스 목록은 지원되는 조건 속성을 참조하세요.
-
-
-
--add-details-rules=RULES_FILE: 지정된 파일의 규칙을 UAP의 기존 규칙에 추가합니다. -
--remove-details-rules=RULES_FILE: 지정된 파일의 규칙을 UAP의 기존 규칙에서 삭제합니다. 지정된 파일의 규칙 중 하나와 정확하게 일치하는 규칙만 삭제됩니다. -
--clear-details-rules: UAP에서 모든 규칙을 삭제합니다.
UAP를 업데이트하는 데 사용할 수 있는 전체 플래그 목록은
gcloud iam access-policies update명령어 참조를 확인하세요. 일부 플래그는 상호 배타적입니다. -
FORMAT: 응답 형식입니다.json또는yaml을 사용합니다.
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud iam access-policies update UAP_ID \ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID \ --location=global --FIELD_TO_UPDATE=UPDATED_VALUE \ --format=FORMAT
Windows(PowerShell)
gcloud iam access-policies update UAP_ID ` --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ` --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ` --format=FORMAT
Windows(cmd.exe)
gcloud iam access-policies update UAP_ID ^ --UAP_PARENT_RESOURCE_TYPE=UAP_PARENT_RESOURCE_ID ^ --location=global --FIELD_TO_UPDATE=UPDATED_VALUE ^ --format=FORMAT
응답에는 요청에 해당하는 장기 실행 작업이 포함됩니다. 작업이 완료되면 응답에서 업데이트된 UAP를 출력합니다.
Request issued for: [example-policy]
Waiting for operation [organizations/123456789012/locations/global/operations/operation-1715374208720-6181fae5e2034-2d8a712b-5c92e5b9] to complete...done.
Updated accessPolicy [example-policy].
{
"createTime": "2026-08-31T21:43:39.822441Z",
"details": {
"rules": [
{
"conditions": {
"iam.googleapis.com": {
"expression": "resource.matchTag('environment', 'prod')"
}
},
"description": "Grant non-delete compute permissions to compute admins in prod",
"effect": "ALLOW",
"excludedPrincipals": [
"principal://goog/subject/access-restricted@example.com"
],
"operation": {
"excludedPermissions": [
"*/*.delete"
],
"permissions": [
"role:roles/compute.admin"
]
},
"principals": [
"principalSet://goog/group/compute-admins@example.com"
]
}
]
},
"displayName": "Updated display name",
"etag": "W/\"YZtdQgtulCVzvTwlBTFjPQ==\"",
"name": "projects/0123456789012/locations/global/accessPolicies/example-policy",
"uid": "puid_0123456789012345678",
"updateTime": "2026-08-31T21:43:39.822441Z"
}
REST
accessPolicies.patch 메서드는 기존 UAP를 업데이트합니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
-
UAP_PARENT_RESOURCE_TYPE: 업데이트하려는 UAP를 소유하는 Resource Manager 리소스(프로젝트, 폴더 또는 조직)의 유형입니다.projects,folders,organizations값을 사용합니다. -
UAP_PARENT_RESOURCE_ID: 업데이트하려는 UAP를 소유한 프로젝트, 폴더 또는 조직의 ID입니다. 프로젝트 ID는my-project같은 영숫자 문자열입니다. 폴더 및 조직 ID는123456789012와 같은 숫자입니다. -
UAP_ID: 업데이트하려는 UAP의 ID입니다(예:example-policy). DISPLAY_NAME: 선택사항. 인간이 읽을 수 있는 UAP에 대한 설명입니다(예:Example policy). 표시 이름은 최대 63자까지 가능합니다.-
UAP_RULES: 부여하거나 거부할 액세스 권한과 액세스 권한을 부여하거나 거부할 주 구성원을 정의하는 UAP 규칙 목록입니다. UAP에는 규칙이 최대 100개까지 있을 수 있습니다. 각 규칙의 형식은 다음과 같습니다.{ "description": "DESCRIPTION", "effect": "EFFECT", "principals": [ INCLUDED_PRINCIPALS ], "excludedPrincipals": [ EXCLUDED_PRINCIPALS ], "operation": { "permissions": [ INCLUDED_PERMISSIONS ], "excludedPermissions": [ EXCLUDED_PERMISSIONS ] }, CONDITIONS }
다음 값을 바꿉니다.
-
DESCRIPTION: 인간이 읽을 수 있는 규칙에 대한 설명입니다. -
EFFECT: 규칙이 액세스에 미치는 영향입니다. 지원되는 값은ALLOW및DENY입니다.-
ALLOW: 지정된 주 구성원에게 지정된 권한을 부여합니다. -
DENY: 지정된 주 구성원이 지정된 권한을 사용하지 못하도록 방지합니다.
-
-
다음 값을 바꿔 규칙에 포함된 주 구성원을 지정합니다.
-
INCLUDED_PRINCIPALS: 규칙에 포함할 주 구성원입니다. -
EXCLUDED_PRINCIPALS: 선택사항. 포함된 주 구성원 목록에 있더라도 규칙에서 제외할 주 구성원입니다. 예를 들어 포함된 주 구성원 목록에 Google 그룹을 추가한 다음 해당 그룹에 속한 특정 사용자를 제외할 수 있습니다.
지원되는 주 구성원 식별자 목록은 UAP의 주 구성원 유형을 참조하세요.
-
-
다음 값을 바꿔 규칙에 포함할 권한을 지정합니다.
-
INCLUDED_PERMISSIONS: 규칙에 포함할 권한입니다. -
EXCLUDED_PERMISSIONS: 선택사항. 포함된 권한 목록에 있더라도 규칙에서 제외할 권한입니다. 예를 들어 포함된 권한 목록에 역할을 추가한 다음 해당 역할에서 특정 권한을 제외할 수 있습니다.
이러한 권한 목록을 만들 때 권한 이름, 역할 이름, 권한 그룹을 참조할 수 있습니다. 자세한 내용은 UAP 규칙의 역할 및 권한을 참조하세요.
-
-
CONDITIONS: 선택사항. 규칙이 적용되는 조건입니다. 다음 형식을 사용합니다."conditions": { "SERVICE": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
다음 값을 바꿉니다.
-
SERVICE: 조건 표현식에 사용되는 속성을 제공하는 서비스입니다. -
CONDITION_TITLE: 선택사항. 조건 목적에 대한 간단한 요약입니다. -
CONDITION_DESCRIPTION: 선택사항. 조건에 대한 자세한 설명입니다. -
CONDITION_EXPRESSION: 액세스 시도에서 리소스에 연결된 태그와 같은 액세스 시도의 속성을 참조하는 불리언 표현식입니다. 표현식이true로 평가되면 액세스 시도에 규칙이 적용됩니다.false로 평가되면 액세스 시도에 규칙이 적용되지 않습니다.
지원되는 속성 및 해당 서비스 목록은 지원되는 조건 속성을 참조하세요.
-
-
HTTP 메서드 및 URL:
PATCH https://iam.googleapis.com/v3/UAP_PARENT_RESOURCE_TYPE/UAP_PARENT_RESOURCE_ID/locations/global/accessPolicies/UAP_ID
JSON 요청 본문:
{
"displayName": "DISPLAY_NAME",
"details": {
"rules": [
UAP_RULES
]
}
}
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
응답에는 요청에 해당하는 장기 실행 작업이 포함됩니다. 장기 실행 작업의 상태를 가져오는 방법을 알아보려면 이 페이지의 장기 실행 작업의 상태 확인을 참조하세요.
{
"name": "organizations/123456789012/locations/global/operations/operation-1715626721931-6185a7953ef76-76f80ee4-19cd1bf7",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2026-05-13T18:58:43.721277235Z",
"target": "organizations/123456789012/locations/global/accessPolicies/example-policy",
"verb": "update",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": false
}
정책이 적용되는 리소스 변경
UAP의 바인딩을 만든 후에는 바인딩에서 정책 ID 또는 리소스를 변경할 수 없습니다. 따라서 UAP가 적용되는 리소스를 변경하려면 다음 중 하나를 수행해야 합니다.
- UAP를 다른 리소스에 적용하려면 UAP를 해당 리소스에 바인딩하는 새 바인딩을 만듭니다.
- 리소스에서 UAP를 삭제하려면 UAP를 리소스에 바인딩하는 바인딩을 삭제합니다.
장기 실행 작업의 상태 확인
REST API 또는 클라이언트 라이브러리를 사용할 때 정책 또는 바인딩을 변경하는 메서드는 장기 실행 작업(LRO)을 반환합니다. 장기 실행 작업은 요청의 상태를 추적하고 정책이나 바인딩 변경이 완료되었는지 여부를 나타냅니다.
REST
operations.get 메서드는 장기 실행 작업 상태를 반환합니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
-
OPERATION_NAME: 작업의 전체 이름입니다. 원래 요청에 대한 응답으로 이 이름을 받습니다.작업 이름은 다음 형식입니다.
RESOURCE_TYPE/RESOURCE_ID/locations/global/operations/OPERATION_ID
HTTP 메서드 및 URL:
GET https://iam.googleapis.com/v3/OPERATION_NAME
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{
"name": "organizations/314340013352/locations/global/operations/operation-1732752311821-627edd607a3df-9a62cdea-2a7d9f07",
"metadata": {
"@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
"createTime": "2024-11-28T00:05:12.006289686Z",
"endTime": "2024-11-28T00:05:12.192141801Z",
"target": "organizations/314340013352/locations/global/POLICY_TYPE/POLICY_ID",
"verb": "create",
"requestedCancellation": false,
"apiVersion": "v3"
},
"done": true,
"response": {
POLICY
}
}
작업의 done 필드가 없으면 작업을 반복적으로 가져와서 해당 상태를 계속 모니터링합니다. 잘린 지수 백오프를 사용하여 각 요청 간에 지연을 일으킵니다. done 필드가 true로 설정되었으면 작업이 완료되었고 작업 가져오기를 중지할 수 있습니다.