IAM policy types

Identity and Access Management (IAM) offers several types of policies to help you control which resources principals can access. This page helps you understand the differences between how you use and manage these policy types.

IAM policy types

IAM offers the following types of policies:

• Allow policies
• Deny policies
• Principal access boundary (PAB) policies

The following table summarizes the differences between these policy types:

Policy	Policy function	API used to manage the policy	Relationship between policies and targets	Method of attaching policies to target	Policy's parent resource
Allow policies	Grant principals access to resources	The API for the resource that you want to manage allow policies for	One-to-one relationship Each allow policy is attached to one resource; each resource can only have one allow policy	Specify resource when creating the policy	Same as the resource that the allow policy is attached to
Deny policies	Ensure that principals can't use specific permissions	The IAM v2 API	One-to-many relationship Each deny policy is attached to one resource; each resource can have up to 500 deny policies	Specify resource when creating the deny policy	Same as the resource that the deny policy is attached to
PAB policies	Restrict the resources a principal is eligible to access	The IAM v3 API	Many-to-many relationship Each PAB policy can be attached to an unlimited number of principal sets; each principal set can have up to 10 PAB policies bound to it	Create a policy binding that attaches the PAB policy to a principal set	The organization

The following sections provide details about each policy type.

Policies to grant access to principals

To grant principals access to resources, use IAM allow policies.

Allow policies let you grant access to resources in Google Cloud. Allow policies are made up of role bindings and metadata. Role bindings specify which principals should have a certain role on the resource.

Allow policies are always attached to a single resource. After you attach an allow policy to a resource, the policy is inherited by that resource's descendants.

To create and apply an allow policy, you identify a resource that accepts allow policies, then use that resource's setIamPolicy method to create the allow policy. All principals in the allow policy are granted the specified roles on the resource and all of the resource's descendants. Each resource can have only one allow policy attached to it.

For more information about allow policies, see Understanding allow policies.

Policies to deny access to principals

To deny principals access to resources, use IAM deny policies. IAM deny policies are available in the IAM v2 API.

Deny policies, like allow policies, are always attached to a single resource. You can attach a deny policy to a project, folder, or organization. This project, folder, or organization also acts as the policy's parent in the resource hierarchy. After you attach a deny policy to a resource, the policy is inherited by that resource's descendants.

To create and apply deny policies, you use the IAM v2 API. When you create a deny policy, you specify the resource that the deny policy is attached to. All principals in the deny policy are prevented from using the specified permissions to access that resource and any of that resource's descendants. Each resource can have up to 500 deny policies attached to it.

For more information about deny policies, see Deny policies.

Policies to restrict the resources a principal can access

Preview — principal access boundary policies

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To restrict the resources that a principal is eligible to access, use a principal access boundary policy. Principal access boundary policies are available in the IAM v3 API.

To create and apply a principal access boundary policy, you create a principal access boundary policy, and then create a policy binding to connect that policy to a principal set.

Principal access boundary policies are always children of your organization. Policy bindings for principal access boundary policies are children of the project, folder, or organization that is closest to the principal set referenced in the policy binding.

Each policy binding binds one principal access boundary policy to one principal set. A principal access boundary policy can be bound to any number of principal sets. Each principal set can have up to 10 principal access boundary policies bound to it. When a principal access boundary policy is deleted, all of the policy bindings related to that policy are also deleted.

For more information about principal access boundary policies, see Principal access boundary policies.

Policy evaluation

When a principal tries to access a resource, IAM evaluates all relevant allow, deny, and principal access boundary policies to see if the principal is allowed to access the resource. If any of these policies indicates that the principal shouldn't be able to access the resource, then IAM prevents access.

In reality, IAM evaluates all policy types simultaneously, then compiles the results to determine whether the principal can access the resource. However, it can be helpful to think of this policy evaluation taking place in the following stages:

1. IAM checks all relevant principal access boundary policies to see if the principal is eligible to access the resource. A principal access boundary policy is relevant if the following are true:

   • The policy is bound to a principal set that includes the principal
   • The principal access boundary policy blocks the permission that the principal is trying to use. The permissions that a principal access boundary policy blocks depends on the principal access boundary policy version. You specify the policy version when you create the principal access boundary policy. For more information, see Principal access boundary policy versions.

   After checking the relevant principal access boundary policies, IAM does one of the following:

   • If the relevant principal access boundary policies don't include the resource that the principal is trying to access, then IAM prevents them from accessing the resource.
   • If the relevant principal access boundary policies include the resource that the principal is trying to access, then IAM continues to the next step.
   • If there are no relevant principal access boundary policies, or if IAM can't evaluate the relevant principal access boundary policies, then IAM continues to the next step.

2. IAM checks all relevant deny policies to see if the principal has been denied the permission. Relevant deny policies are the deny policies attached to the resource, as well as any inherited deny policies.

   • If any of these deny policies prevent the principal from using a required permission, then IAM prevents them from accessing the resource.
   • If no deny policies prevent the principal from using a required permission, then IAM continues to the next step.

3. IAM checks all relevant allow policies to see if the principal has the required permissions. Relevant allow policies are the allow policies attached to the resource, as well as any inherited allow policies.

   • If the principal does not have the required permissions, then IAM prevents them from accessing the resource.
   • If the principal has the required permissions, then IAM lets them access the resource.

The following diagram shows this policy evaluation flow:

What's next

• Learn more about allow policies.
• Learn more about deny policies.
• Learn more about principal access boundary policies.