This page shows you how to use Organization Policy Service custom constraints to restrictspecific operations on the following Google Cloud resources:

• iam.googleapis.com/AllowPolicy

To learn more about Organization Policy, seeCustom organization policies.

About organization policies and constraints

The Google Cloud Organization Policy Service gives you centralized, programmaticcontrol over your organization's resources. As theorganization policy administrator, you can define an organizationpolicy, which is a set of restrictions calledconstraints that apply toGoogle Cloud resources and descendants of those resources in theGoogle Cloud resource hierarchy. You can enforce organizationpolicies at the organization, folder, or project level.

Organization Policy provides built-inmanaged constraintsfor various Google Cloud services. However, if you want more granular,customizable control over the specific fields that are restricted in yourorganization policies, you can also createcustom constraints and use thosecustom constraints in an organization policy.

Policy inheritance

By default, organization policies are inherited by the descendants of theresources on which you enforce the policy. For example, if you enforce a policyon a folder, Google Cloud enforces the policy on all projects in thefolder. To learn more about this behavior and how to change it, refer toHierarchy evaluation rules.

Benefits

You can use custom organization policies that reference IAMattributes to control how your allow policies can be modified. Specifically,you can control the following:

• Who can be granted roles
• Who can have their roles revoked
• Which roles can be granted
• Which roles can be revoked

For example, you can prevent roles that contain the wordadmin from beinggranted to principals whose email addresses end in@gmail.com.

Limitations

• Custom organization policies indry-runmode thatreferenceIAM attributes have some limitations. Namely, audit logs forviolations that involve thesetIamPolicy method might be missing thefollowing fields:

  • resourceName
  • serviceName
  • methodName

• Audit logs aren't generated for all IAM-related customorganization policy violations. Namely, if a custom organization policy causesasetIamPolicy operation on the organization resource to fail, thenGoogle Cloud doesn't generate an audit log for that event.

• Custom organization policies that reference IAM attributesdon't affect the following:

  • Default grants byCloud StorageACLs.
  • Automatic role grants forCloud Storage conveniencevalues andBigQuery default datasetaccess.
  • Roles granted bydefault allowpolicies—for example, a project creatorautomatically being granted the Owner role (roles/owner) on the project.

• Users can be sent invitations to become owners, even if you have acustom organization policy that prevents the Owner role (roles/owner) frombeing granted. However, while the custom organization policy doesn't preventan invitation from being sent, it does prevent invited users from beinggranted the Owner role. If invited users try to accept the invitation, they'llencounter an error and won't be granted the Owner role.

• Some actions in Google Cloud, such as creating resources or enablingAPIs, involve automatically granting a role to aserviceagent ordefault serviceaccount. If an action involvesautomatically granting a role and an organization policy prevents that rolefrom being granted, then the entire operation might fail.

  If you encounter this issue, you can usetagsto temporarily disable the constraint that prevents the role grant. Then,perform the action. After the action finishes, re-enable the constraint.

Before you begin

• If you want to test out custom organization policies that reference IAM resources, create a new project. Testing these organization policies in an existing project could disrupt security workflows.

  1. In the Google Cloud console, go to the project selector page.

     Go to project selector

  2. Select or create a Google Cloud project.

     Roles required to select or create a project

     • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
     • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.
     Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Required roles

To get the permissions that you need to manage organization policies, ask your administrator to grant you the following IAM roles:

• Organization Policy Administrator (roles/orgpolicy.policyAdmin) on the organization
• Test the organization policies described on this page:Project IAM Admin (roles/resourcemanager.projectIamAdmin) on the project

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to manage organization policies. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Set up a custom constraint

A custom constraint is defined in a YAML file by the resources, methods,conditions, and actions that are supported by the service on which you areenforcing the organization policy. Conditions for your custom constraints aredefined usingCommon Expression Language (CEL). For more information about how to buildconditions in custom constraints using CEL, see the CEL section ofCreating and managing custom constraints.

Enforce a custom organization policy

Test the custom organization policy

Optionally, you can test the organization policy by setting the policy and thentrying to take an action that the policy should prevent.

Create the constraint

1. Save the following file asconstraint-deny-project-iam-admin.

   name:organizations/ORG_ID/customConstraints/custom.denyProjectIAMAdminresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.exists(binding,RoleNameMatches(binding.role,['roles/resourcemanager.projectIamAdmin'])&&binding.members.exists(member,MemberSubjectMatches(member,['user:EMAIL_ADDRESS'])))"actionType:DENYdisplayName:Do not allowEMAIL_ADDRESS to be granted the Project IAM Admin role.

   Replace the following values:

   • ORG_ID: the numeric ID of yourGoogle Cloud organization.
   • MEMBER_EMAIL_ADDRESS: the email address of theprincipal that you want to use to test the custom constraint. While theconstraint is active, this principal won't be able to be granted theProject IAM Admin role (roles/resourcemanager.projectIamAdmin) on theproject that you enforce the constraint for.

2. Apply the constraint:

   gcloudorg-policiesset-custom-constraint~/constraint-deny-project-iam-admin.yaml

3. Verify that the constraint exists:

   gcloudorg-policieslist-custom-constraints--organization=ORGANIZATION_ID

Create the policy

1. Save the following file aspolicy-deny-project-iam-admin.yaml:

   name:projects/PROJECT_ID/policies/custom.denyProjectIamAdminspec:rules:-enforce:true

   ReplacePROJECT_ID with your project ID.

2. Apply the policy:

   gcloudorg-policiesset-policy~/policy-deny-project-iam-admin.yaml

3. Verify that the policy exists:

   gcloudorg-policieslist--project=PROJECT_ID

After you apply the policy, wait for about two minutes for Google Cloud tostart enforcing the policy.

Test the policy

Try to grant the Project IAM Admin role(roles/resourcemanager.projectIamAdmin) to the principal whose email addressyou included in the custom constraint. Before running the command, replace thefollowing values:

• PROJECT_ID: The ID of the Google Cloudproject where you enforced the constraint
• EMAIL_ADDRESS: The email address of the principalthat you specified when you created the organization policy constraint.

gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=user:EMAIL_ADDRESS--role=roles/resourcemanager.projectIamAdmin

The output is the following:

Operation denied by custom org policies: ["customConstraints/custom.denyProjectIAMAdmin": "EMAIL_ADDRESS can't be granted the Project IAM Admin role."]

Example custom organization policies for common use cases

The following table provides the syntax of some custom constraints for commonuse cases.

The following examples use the CEL macrosall andexists. For moreinformation about these macros, seeMacros to evaluate lists.

name:organizations/ORG_ID/customConstraints/custom.denyRoleresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.exists(binding,RoleNameMatches(binding.role,['ROLE']))"actionType:DENYdisplayName:Do not allow theROLE role to be granted

name:organizations/ORG_ID/customConstraints/custom.specificRolesOnlyresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.all(binding,RoleNameMatches(binding.role,['ROLE_1','ROLE_2']))"actionType:ALLOWdisplayName:Only allow theROLE_1 role andROLE_2 role to be granted

name:organizations/ORG_ID/customConstraints/custom.dontgrantStorageRolesresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.exists(binding,RoleNameStartsWith(binding.role,['roles/storage.']))"actionType:DENYdisplayName:Prevent roles that start with "roles/storage." from being granted

name:organizations/ORG_ID/customConstraints/custom.dontRevokeAdminRolesresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-REMOVE_GRANTcondition:"resource.bindings.exists(binding,RoleNameContains(binding.role,['admin']))"actionType:DENYdisplayName:Prevent roles with "admin" in their names from being revoked

name:organizations/ORG_ID/customConstraints/custom.allowSpecificPrincipalsresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.all(binding,binding.members.all(member,MemberSubjectMatches(member,['user:USER','serviceAccount:SERVICE_ACCOUNT'])))"actionType:ALLOWdisplayName:Only allow roles to be granted toUSER andSERVICE_ACCOUNT

name:organizations/ORG_ID/customConstraints/custom.denyRemovalOfSpecificPrincipalsresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-REMOVE_GRANTcondition:"resource.bindings.exists(binding,binding.members.exists(member,MemberSubjectMatches(member,['user:USER_1','user:USER_2'])))"actionType:DENYdisplayName:Do not allow roles to be revoked fromUSER_1 orUSER_2

name:organizations/ORG_ID/customConstraints/custom.dontGrantToGmailresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.exists(binding,binding.members.exists(member,MemberSubjectEndsWith(member,['@gmail.com'])))"actionType:DENYdisplayName:Do not allow members whose email addresses end with "@gmail.com" to be granted roles

name:organizations/ORG_ID/customConstraints/custom.allowSpecificRolesAndPrincipalsresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.all(binding,RoleNameMatches(binding.role,['ROLE_1','ROLE_2'])&&binding.members.all(member,MemberSubjectMatches(member,['serviceAccount:SERVICE_ACCOUNT','group:GROUP'])))"actionType:ALLOWdisplayName:Only allowROLE_1 andROLE_2 to be granted toSERVICE_ACCOUNT andGROUP

name:organizations/ORG_ID/customConstraints/custom.denyStorageRolesForPrincipalAllUsersresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.exists(binding,RoleNameStartsWith(binding.role,['roles/storage.'])&&binding.members.exists(member,MemberSubjectMatches(member,['allUsers','allAuthenticatedUsers'])))"actionType:DENYdisplayName:Do not allow storage roles to be granted to allUsers or allAuthenticatedUsers

name:organizations/ORG_ID/customConstraints/custom.allowInternaldentitiesOnlyresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.all(binding,binding.members.all(member,MemberInPrincipalSet(member,['//cloudresourcemanager.googleapis.com/organizations/ORG_ID'])))"actionType:ALLOWdisplayName:Only allow organization members to be granted roles

name:organizations/ORG_ID/customConstraints/custom.allowServiceAccountsOnlyresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.all(binding,binding.members.all(member,MemberTypeMatches(member,['iam.googleapis.com/ServiceAccount'])))"actionType:ALLOWdisplayName:Only allow service accounts to be granted roles

name:organizations/ORG_ID/customConstraints/custom.denyRemovalOfGoogleManagedServiceAgentsresource_types:iam.googleapis.com/AllowPolicymethod_types:-REMOVE_GRANTcondition:|-resource.bindings.all(binding,binding.members.all(member,MemberTypeMatches(member, ['iam.googleapis.com/ServiceAgent'])))action_type:DENYdisplay_name:Deny Removal Of Google-Managed Service Agentsdescription:Restricts the removal of Google-managed service agents from role bindings. Please reach out to your organization admins for if you have any questions.

Conditional organization policies

You can make a custom organization policy conditional usingtags.For example, imagine that you wrote the following custom constraint to preventany roles that start withroles/storage. from being granted:

name:organizations/ORG_ID/customConstraints/custom.dontgrantStorageRolesresourceTypes:iam.googleapis.com/AllowPolicymethodTypes:-CREATE-UPDATEcondition:"resource.bindings.exists(binding,RoleNameStartsWith(binding.role,['roles/storage.']))"actionType:DENYdisplayName:Prevent roles that start with "roles/storage." from being granted

To enforce the constraint conditionally, you could create an organization policylike the following:

name:organizations/ORG_ID/policies/custom.dontgrantStorageRolesspec:rules:-condition:expression:"resource.matchTag('ORG_ID/environment','dev')"enforce:true-enforce:false

This organization policy prevents roles that start withroles/storage. frombeing granted on any resource that also has the tagenvironment=dev.

Identity and Access Management supported resources

IAM supports theAllowPolicy resource. This resource hasthe attributeresources.bindings attribute, which is returned for all methodsthat modify a resource's allow policy. All of the methods that modify aresource's allow policy end withsetIamPolicy.

Theresource.bindings attribute has the following structure, whereBINDINGS is an array of role bindings that were modifiedduring a change to an allow policy:

{"bindings":{BINDINGS}}

Each binding inresource.bindings has the following structure, whereROLE is the name of the role in the role binding andMEMBERS is a list of identifiers for all principals thatwere added to or removed from the role binding:

{"role":"ROLE""members":{MEMBERS}}

To see the formats that principal identifiers can have, seePrincipalidentifiers.

You can only evaluate theresource.bindings attribute and its fields using thesupported functions. Other operators andfunctions—like==,!=,in,contains,startsWith, andendsWith—are not supported.

Supported functions

You can use the following CEL functions to evaluate individual roles and membersin a binding.

To evaluate all bindings in thebindings array or all members in themembersarray, use theall andexists macros. For more information, seeMacrosto evaluate lists on this page.

You can also use the logical operators&& (and) and|| (or) to writemultipart conditions.

Macros to evaluate lists

Use theall andexists macros to evaluate a condition expression for alist of items.

Conditions with nested lists

In general, if your condition includes nested lists, you should use the samemacro for all lists in the condition.

Consider the following examples:

• If your policy has theactionTypeALLOW, then use theall macro for boththemembers list and thebindings list to ensure that policy modificationsare only allowed ifall members inall modified bindings satisfy thecondition.
• If your policy has theactionTypeDENY, then use theexists macro forboth themembers list and thebindings list to ensure that policymodifications aren't allowed ifany member inany modified bindingsatisfies the condition.

Mixing macros in a single condition might result in a condition that doesn'tbehave how you intended.

For example, imagine that you want to prevent roles from being granted tomembers outside of theexample.com organization. Theexample.comorganization has the ID123456789012.

To accomplish this goal, you write the following condition:

Not recommended — misconfigured condition

"resource.bindings.all(  binding,  binding.members.exists(member,    MemberInPrincipalSet(member, ['//cloudresourcemanager.googleapis.com/organizations/123456789012'])  ))"

This condition appears to prevent roles from being granted to members outside oftheexample.com organization. However, the condition evaluates totrue ifany member in each of the modified role bindings is in theexample.comorganization. As a result, you can still grant roles to members outside of theexample.com organization if you also grant the same role to a member in theexample.com organization.

For example, the condition evaluates totrue for the following set ofbindings, even though one of the members isn't in theexample.comorganization:

"bindings":[{"members":["user:raha@altostrat.com","user:jie@example.com"],"role":"roles/resourcemanager.projectCreator"}],

Instead, you should write a condition like the following:

Recommended — correctly configured condition

"resource.bindings.all(  binding,  binding.members.all(member,    MemberInPrincipalSet(member, ['//cloudresourcemanager.googleapis.com/organizations/123456789012'])  ))"

Using theall macro for both themembers.bindings array and theresource.bindings array ensures that the condition evaluates totrue onlyifall members inall bindings are in theexample.com principal set.

Supported principal types forMemberTypeMatches

TheMemberTypeMatches function requires you to specify which principal typethe specified member must match.

The following table lists the principal types that you can enter and adescription of what the principal type represents. It also lists the principalidentifiers that correspond with each principal type. These identifiers are thevalues that are used in IAM policies.

What's next

• Learn more aboutOrganization Policy Service.
• Learn more about how tocreate and manage organization policies.
• See the full list of managedorganization policy constraints.