Deny policies

Stay organized with collections Save and categorize content based on your preferences.

Identity and Access Management (IAM) deny policies let you set guardrails on access to Google Cloud resources. With deny policies, you can define deny rules that prevent certain principals from using certain permissions, regardless of the roles they're granted.

This page provides an overview of deny policies and deny rules. To learn how to create and update deny policies, see Deny access to resources.

How deny policies work

Deny policies are made up of deny rules. Each deny rule specifies the following:

  • A set of principals that are denied permissions
  • The permissions that the principals are denied, or unable to use
  • Optional: The condition that must be true for the permission to be denied

When a principal is denied a permission, they can't do anything that requires that permission, regardless of the IAM roles they've been granted. This is because IAM always checks relevant deny policies before checking relevant allow policies. For details, see policy evaluation.

To specify where you want a deny policy to apply, you attach it to a project, folder, or organization. When a deny policy is attached to one of these resources, the principals in the policy can't use the specified permissions to access the resource, or any of the resource's descendants.

Each project, folder, and organization can have up to 5 deny policies attached to it. This lets you create separate deny policies for different types of deny rules. For example, you could put compliance-related deny rules in one policy, then use another policy for other deny rules. Each deny policy is evaluated independently of all other deny policies.

Policy evaluation

When a principal tries to access to a resource, IAM evaluates all relevant allow and deny policies to see if the principal is allowed to access the resource. It evaluates the policies in this order:

  1. 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, IAM prevents them from accessing the resource.

    If no deny policies prevent the principal from using a required permission, IAM continues to the next step.

  2. 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 has the required permissions, IAM lets them access the resource.

    If the principal does not have the required permissions, IAM prevents them from accessing the resource.

The following diagram shows this policy evaluation flow:

Deny policy inheritance

Deny policies, like allow policies, are inherited through the resource hierarchy. When you attach a deny policy to a project, folder, or organization, the policy is also effective for all resources inside that project, folder, or organization.

For example, if a deny policy for an organization says that a principal cannot use a specific permission, then the principal cannot use that permission for any resource within the organization. This rule applies even if the folders and projects within that organization have more permissive deny policies.

Similarly, if a deny policy for a project says that a principal cannot use a specific permission, then the principal cannot use that permission for any resource within the project. This rule applies even if the parent organization and folders have more permissive deny policies.

Denial conditions

Denial conditions specify the conditions that must be met in order for a deny rule to apply. If the condition evaluates to true or cannot be evaluated, the deny rule applies and the principals are unable to use the specified permissions. If the condition evaluates to false, the deny rule does not apply and the principals can use the specified permissions if they have them.

Denial conditions have the same structure as IAM Conditions. However, denial conditions only recognize resource tag functions.

To learn how to write conditions, see overview of IAM Conditions.

Structure of a deny policy

A deny policy is a collection of metadata and deny rules. A deny rule associates a set of principals with a set of permissions that the principals are denied, or unable to use. Each rule can also specify a condition that determines when the permission is denied.

For example, the following deny policy blocks all principals from deleting projects, unless the principal is a member of project-admins@example.com or the project being deleted has a tag with the value test.

{
  "name": "policies/cloudresourcemanager.googleapis.com%2Fprojects%2F253519172624/denypolicies/limit-project-deletion",
  "uid": "06ccd2eb-d2a5-5dd1-a746-eaf4c6g3f816",
  "kind": "DenyPolicy",
  "displayName": "Only project admins can delete projects.",
  "etag": "MTc1MTkzMjY0MjUyMTExODMxMDQ=",
  "createTime": "2021-09-07T23:15:35.258319Z",
  "updateTime": "2021-09-07T23:15:35.258319Z",
  "rules": [
    {
      "denyRule": {
        "deniedPrincipals": [
          "principalSet://goog/public:all"
        ],
        "exceptionPrincipals": [
          "principalSet://goog/group/project-admins@example.com"
        ],
        "deniedPermissions": [
          "cloudresourcemanager.googleapis.com/projects.delete"
        ],
        "denialCondition": {
          "title":  "Only for non-test projects",
          "expression": "!resource.matchTag('12345678/env', 'test')"
        }
      }
    }
  ]
}

The following sections describe the fields in a deny policy's metadata and deny rules.

Metadata

Deny policies contain the following metadata:

  • name: The name of the deny policy. This name has the format policies/ATTACHMENT_POINT/denypolicies/POLICY_ID, where ATTACHMENT_POINT is the project, folder, or organization that the deny policy is attached to and POLICY_ID is the deny policy's alphanumeric ID.
  • uid: A unique ID assigned to the deny policy by Google.
  • kind: The type of policy. The kind for a deny policy is always DenyPolicy.
  • displayName: Optional. A human-readable name for the deny policy.
  • etag: An identifier for a version of the policy. To prevent conflicting updates, the etag value must match the value that is stored in IAM. If the etag values do not match, the request fails.
  • createTime: The time when the deny policy was created.
  • updateTime: The last time that the deny policy was updated.

Deny rules

Each deny rule can have the following fields:

  • deniedPrincipals: The principals that are denied permissions. You can list individual principals and sets of principals. Individual principal types include user accounts and service accounts. Sets of principals include Google groups, Cloud Identity domains, and all users on the internet.

    For a list of valid principal types and identifiers, see IAM v2beta API principal identifiers.

  • exceptionPrincipals: Optional. The principals that are excluded from the deny rule. These principals are not denied the specified permissions even if they are listed in deniedPrincipals, or are part of a group listed in deniedPrincipals.

    You can list individual principals and sets of principals. Individual principal types include user accounts and service accounts. Sets of principals include Google groups and Cloud Identity domains.

    For a list of valid principal types and identifiers, see IAM v2beta API principal identifiers.

  • deniedPermissions: The permissions that the specified principals are unable to use, or denied. These permissions use the IAM v2beta permission format, which uses fully qualified domain names (FQDNs) to identify the service. The format is SERVICE_FQDN/RESOURCE.ACTION. Google APIs use the domain *.googleapis.com. For example, iam.googleapis.com/roles.delete.

  • denialConditions: Optional. A logic expression that affects when the deny rule applies. If the condition evaluates to true or cannot be evaluated, the permission is denied. If the condition evaluates to false, the permission is not denied. For more information, see Denial conditions on this page.

Common use cases

The following are common situations where you might want to use deny policies, and examples of the deny rules you might create in each situation. To learn how to create and update deny policies, see Deny access to resources.

Centralizing administrative privileges

You can use deny policies to restrict certain types of administrative activities to a specific set of principals.

For example, imagine you want to limit custom role management for your organization to a single central team. To do so, you create a deny rule that denies the permissions required for custom role management to all users, except users in the administrative group (custom-role-admins@example.com):

{
  "deniedPrincipals": [
    "principalSet://goog/public:all"
  ],
  "exceptionPrincipals": [
    "principalSet://goog/group/custom-role-admins@example.com"
  ],
  "deniedPermissions": [
    "iam.googleapis.com/roles.create",
    "iam.googleapis.com/roles.delete",
    "iam.googleapis.com/roles.update",
  ]
}

Then, you attach the deny policy to your organization.

Now, only members of the custom-role-admins@example.com group are able to manage custom roles, even if other users have the required permissions.

For example, imagine that both yuri@example.com and tal@example.com have the Organization Role Administrator role (roles/iam.organizationRoleAdmin). However, yuri@example.com is a member of custom-role-admins@example.com, and tal@example.com is not. With this deny policy, only yuri@example.com is able to create, delete, and update roles.

Creating exceptions to access grants

You can use deny policies to deny inherited permissions. This capability gives you the option to grant a role at a high level in the resource hierarchy, and then deny the role's permissions on individual lower-level resources if necessary.

For example, imagine that you have a folder, Engineering, that contains multiple projects. You want to give a group, eng@example.com, the permissions in the Service Account Key Admin role (roles/iam.serviceAccountKeyAdmin) on almost all of the projects in the folder. However, you don't want the group to gain the ability to create and delete service account keys in one specific project in the folder, example-prod.

Instead of granting the Service Account Key Admin role on each individual project, you create the following deny rule, which denies create and delete permissions in the Service Account Key Admin role to the principals in eng@example.com:

{
  "deniedPrincipals": [
    "principalSet://goog/group/eng@example.com"
  ],
  "deniedPermissions": [
    "iam.googleapis.com/serviceAccountKeys.create",
    "iam.googleapis.com/serviceAccountKeys.delete"
  ]
}

Then, you add this deny rule to a deny policy and attach the policy to the project example-prod.

After you attach the deny policy to the project, you can grant the Service Account Key Admin role to eng@example.com on the Engineering folder without letting the group create or delete service account keys in example-prod.

Members of eng@example.com are then able to create and delete service account keys in all projects except example-prod. For example, if izumi@example.com is a member of eng@example.com, they can create and delete keys for service accounts in example-dev and example-test, but not in example-prod.

However, imagine that you actually want a subset of eng@example.com to be able to create and delete service account keys in example-prod. This subset is represented by the group eng-prod@example.com. To allow the members of eng-prod@example.com to create and delete service account keys in example-prod, you can add the group as an exception principal in the deny rule:

{
  "deniedPrincipals": [
    "principalSet://goog/group/eng@example.com"
  ],
  "exceptionPrincipals": [
    "principalSet://goog/group/eng-prod@example.com"
  ],
  "deniedPermissions": [
    "iam.googleapis.com/serviceAccountKeys.create",
    "iam.googleapis.com/serviceAccountKeys.delete"
  ]
}

With this revised deny policy, members of eng-prod@example.com can create and delete service account keys in all projects, including example-prod. For example, if charlie@example.com is a member of eng-prod@example.com, they can create and delete keys in example-dev, example-test, and example-prod, even if they are also a member of eng@example.com.

Blocking access based on tags

A tag is a key-value pair that can be attached to an organization, folder, or project. You can use deny policies to deny permissions based on tags without adding an IAM Condition to every role grant.

For example, imagine that you tag all of your projects as dev, test, or prod. You want only members of project-admins@example.com to be able to delete projects that are tagged prod.

To solve this problem, you create a deny rule that denies the cloudresourcemanager.googleapis.com/projects.delete permission to everyone except project-admins@example.com for resources that are tagged prod:

{
  "displayName": "Only project admins can delete production projects.",
  "rules": [
    {
      "denyRule": {
        "deniedPrincipals": [
          "principalSet://goog/public:all"
        ],
        "exceptionPrincipals": [
          "principalSet://goog/group/project-admins@example.com"
        ],
        "deniedPermissions": [
          "cloudresourcemanager.googleapis.com/projects.delete"
        ],
        "denialCondition": {
          "title":  "Only for prod projects",
          "expression": "resource.matchTag('12345678/env', 'prod')"
        }
      }
    }
  ]
}

Then, you add this deny rule to a deny policy and attach the policy to your organization.

Because of this deny rule, you can limit principals' access without adding a condition to their role grants. Instead, you can grant principals roles that contain the cloudresourcemanager.googleapis.com/projects.delete permission, and rely on the deny rule to prevent principals outside of project-admins@example.com from deleting any projects tagged prod.

For example, consider two users, bola@example.com and kiran@example.com. Both users have the Project Deleter role (roles/resourcemanager.projectDeleter). Additionally, kiran@example.com is a member of project-admins@example.com. With this deny policy, bola@example.com can only delete projects that have the tag dev or test. kiran@example.com can delete all projects, regardless of their tags.

What's next