This page describes the Conditions feature of Identity and Access Management (IAM).You can use IAM Conditions to define and enforce conditional,attribute-based access control for Google Cloud resources.

Conditions and policy types

You can use conditions in the following places:

• Allow policy role bindings, including role bindings managed by Privileged Access Manager entitlements
• Deny policy rules
• Policy bindings for principal access boundary policies

The following sections describe how you can use conditions in each of theseplaces to enforce attribute-based access control.

Conditions in allow policies

Note: You cannot use conditions when you grantlegacy basic roles, including Owner (roles/owner), Editor (roles/editor), and Viewer (roles/viewer). Also, you cannot use conditions when you grant roles to all users (allUsers) or all authenticated users (allAuthenticatedUsers).

You can use conditions inallow policies to choose to grantaccess to principals only if specified conditions are met. For example, youcould grant temporary access to users so they can resolve a production issue, oryou could grant access only to employees making requests from your corporatenetwork.

Conditions are specified in the role bindings of a resource's allow policy. If arole binding has a condition, then the principals in the role are only grantedthe role if the condition expression evaluates totrue.

Note: Conditional role bindings do not override role bindings with no conditions. If a principal is bound to a role, and the role binding does not have a condition, then the principal always has that role. Adding the principal to a conditional binding for the same role has no effect.

To add a condition to a role binding, you define thecondition field:

"bindings":[{"role":"ROLE","members":["MEMBER_1","MEMBER_2"],"condition":{"title":"TITLE","description":"DESCRIPTION","expression":"EXPRESSION"}}]

To learn more about the fields in a condition, seeConditionstructure on this page.

Only some resource typesaccept conditions in role bindings.However, you cangrant conditional access to other resource types bygranting roles at the organization or project level.

As a best practice, don't add more than100 conditional role bindings to asingle allow policy. If you use a larger number of conditional role bindings,you might exceed the overall size limit for allow policies.

To learn how to add, modify, and remove conditional role bindings, seeManaging conditional role bindings.

Conditions in deny policies

You can use conditions indeny policies to apply a deny ruleonly if a certain condition is met. For example, you could deny a permissiononly if the resource that the principal is trying to access is tagged as a partof theprod environment.

Conditions are specified in the deny rules in a resource's deny policies. If thecondition evaluates totrue or cannot be evaluated, the deny rule applies andthe principals are unable to use the specified permissions. If the conditionevaluates tofalse, the deny rule does not apply and the principals can usethe specified permissions if they have them.

Conditions in deny policies have the same structure as conditions in allowpolicies; however, they only recognizeresource tagfunctions.

To add a condition to a deny rule, you define thedenialCondition field:

"rules":[{"denyRule":{"deniedPrincipals":["PRINCIPAL_1","PRINCIPAL_2"],"exceptionPrincipals":["EXCEPTION_PRINCIPAL_1","EXCEPTION_PRINCIPAL_2"],"deniedPermissions":["DENIED_PERMISSION_1","DENIED_PERMISSION_2"],"denialCondition":{"title":"TITLE","description":"DESCRIPTION","expression":"EXPRESSION"}}}]

To learn more about the fields in a condition, seeConditionstructure on this page.

To learn how to create and manage deny policies, seeDeny access.

Conditions in principal access boundary policy bindings

You can use conditions inpolicy bindings for principal access boundarypolicies to refine the principal set that theprincipal access boundary policy applies to. For example, you could only enforce apolicy for service accounts, or exemptsuper-admin@example.com from a policy.

Conditions are specified in each policy binding. If a policy binding has acondition, then the policy in the policy binding is enforced only if thecondition evaluates totrue.

To add a condition to a policy binding, you define thecondition field in thepolicy binding:

{"displayName":"DISPLAY_NAME","target":{"principalSet":"PRINCIPAL_SET"},"policyKind":"PRINCIPAL_ACCESS_BOUNDARY","policy":"PAB_POLICY","condition":{"title":"TITLE","description":"DESCRIPTION","expression":"EXPRESSION"}}

To learn more about the fields in a condition, seeConditionstructure on this page.

To learn how to create policy bindings for principal access boundary policies, seeApply a principal access boundary policy to a principal set.

Condition structure

Thecondition object has the following structure:

"condition":{"title":...,"description":...,"expression":...}

The condition'stitle is required, but thedescription is optional. Both thetitle and description are purely informational fields to help you identify anddescribe the condition.

Theexpression field is required. It defines anattribute-basedlogic expression using a subset of theCommon Expression Language (CEL).The condition expression can contain multiple statements; each statementevaluates one attribute. Statements are combined using logical operators,following the CEL language specification.

CEL for conditions

Common Expression Language, or CEL, is the expression language used to specifyan expression in IAM Conditions. It is tailored to expressattribute-based logic expressions. For more information, see theCEL spec and itslanguagedefinition.

In IAM Conditions, a subset of CEL is used to make booleanauthorization decisions based on attribute data. In general, a conditionexpression consists of one or more statements that are joined by logicaloperators (&&,||, or!).

Conditions in IAM Conditions use the following CEL features:

• Variables: Conditions usevariables to express a given attribute, such asrequest.time (of type Timestamp) orresource.name (of type String). Thesevariables are populated with value based on the context at runtime.
• Operators: Every data type, such as Timestamp or String, supports a setofoperators that can be used to create a logic expression. Most commonly,operators are used to compare the value contained in a variable with a literalvalue, such asresource.service == 'compute.googleapis.com'. In this example, if the inputvalue ofresource.service iscompute.googleapis.com, then the expressionevaluates totrue.
• Functions: A function is a compound operator for data types that supportmore complex operations. In condition expressions, there are predefinedfunctions that can be used with a given data type. For example,request.path.startsWith('/finance') uses a String prefixmatch function, and evaluates totrue if the value ofrequest.pathcontains a matching prefix, such as/finance.
• Logical operators: Conditions supports three logical operators that can beused to build complex logic expressions from basic expression statements:&&,||, and!. These logical operators make it possible to use multipleinput variables in a condition expression. For example:request.time.getFullYear() < 2020 && resource.service == 'compute.googleapis.com'joins two basic statements, and requires both statements to be met in orderto produce atrue overall evaluation result.

For more information about supported variables, operators, and functions, seetheattribute reference.

Condition attributes

Condition attributes are based on the requested resource—for example,its type or name—or on details about the request—for example, its timestamp ordestination IP address.

The condition attributes that you can use in a condition expression depend onthe policy type that you're writing conditions for. For a full list of conditionattributes and more information aboutthe attributes supported for each policy type, see theattributereference.

The following sections show examples of some of the attributes that you canuse in conditions.

Resource attributes

You can use resource attributes to write conditions that evaluate the resourcein the access request. The attributes that you can evaluate include thefollowing:

• The resource type
• The resource name
• The Google Cloud service being used
• The tags attached to the resource

You can use any of these attributes in allow policy role bindings. Additionally,you can use the resource tags attribute in deny policy deny rules.

For a complete list of resource attributes, see theresource attributes reference.

To learn how to use resource attributes to configure resource-based access, seeConfiguring resource-based access.

Example expressions

In a role binding, the following condition expression allows accessto Compute Engine VM instances, but no other type of resource:

resource.type == 'compute.googleapis.com/Instance'

In a role binding, the following condition expression allows accessto Cloud Storage resources, but no other service's resources:

resource.service == 'storage.googleapis.com'

In a role binding, the following condition expression allows accessonly to Cloud Storage objects inside a specific bucket:

resource.type == 'storage.googleapis.com/Object' &&resource.name.startsWith('projects/_/buckets/exampleco-site-assets/')

In a deny rule, the following condition expression denies access toGoogle Cloud resources that have the tagenv: prod:

resource.matchTag('123456789012/env', 'prod')

Principal attributes

The principal attributes let you write conditions based on the principal thatissued the request. The attributes that you can evaluate include the following:

• The type of principal in the request
• The identity of the principal in the request

You can use these attributes in policy bindings for principal access boundary policies.

For details, see theconditions attributereference.

Example expressions

In a principal access boundary policy binding, the following condition expressionensures that the policy in the binding is only enforced for service accounts:

principal.type == 'iam.googleapis.com/ServiceAccount'

In a principal access boundary policy binding, the following condition expressionensures that the policy in the binding isn't enforced forsuper-admin@example.com:

principal.subject != 'super-admin@example.com'

Request attributes

You can use request attributes to write conditions that evaluate details aboutthe request, such as the following:

• The access level
• The date and time
• The destination IP address and port (for IAP TCP tunneling)
• The expected URL host or path (for IAP)

You can use these attributes in allow policy role bindings.

Example access level expression (for IAP only)

In the following example, your organization defines an access level,CorpNet,that limits access to the range of IP addresses where traffic enters and exits acorporate network. Then, you add the following condition expression to a rolebinding to allow access only if the request meets theCorpNet access level:

'accessPolicies/199923665455/accessLevels/CorpNet' inrequest.auth.access_levels

Your organization defines access levels based on attributes of the request, suchas origin IP address, device attributes, the time of day, and more. For moredetails, see theAccess Context Manager documentation.

Example API attribute expression

In a role binding for a role with theiam.projects.setIamPolicypermission, the following condition expression allows a user to grant and revokeonly the Billing Account Administrator (roles/billing.admin) role on theproject:

api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', [])                 .hasOnly(['roles/billing.admin'])

To learn more about using API attributes to limit role granting, seeSetting limits on granting roles.

Example date/time expressions

In a role binding, the following condition expression allows accessuntil midnight on January 1st, 2021:

request.time < timestamp('2021-01-01T00:00:00Z')

In a role binding, the following condition expression allows accessonly during specified working hours, based on the time zone for Berlin, Germany:

request.time.getHours('Europe/Berlin') >= 9 &&request.time.getHours('Europe/Berlin') <= 17 &&// Days of the week range from 0 to 6, where 0 == Sunday and 6 == Saturday.request.time.getDayOfWeek('Europe/Berlin') >= 1 &&request.time.getDayOfWeek('Europe/Berlin') <= '

In a role binding, the following condition expression allows accessonly for June of 2020, based on the time zone for Berlin, Germany:

request.time.getFullYear('Europe/Berlin') == 2020request.time.getMonth('Europe/Berlin') < 6

To specify a timestamp, useRFC 3339format. To specify a time zone, use the identifiers in theIANA Time Zone Database.

For more details about date/time expressions, see theCEL specification.

To learn how to use date/time expressions to configure temporaryaccess, seeConfiguring temporary access.

Example destination IP and port expressions (for IAP TCP tunneling)

In a role binding, the following condition expression allows accessto an internal destination IP address or port number:

destination.ip == '14.0.0.1'destination.ip != '127.0.0.1'destination.port == 22destination.port > 21 && destination.port <= 23

Example forwarding rule expressions

In a role binding, the following condition expression allows accessfor a principal if the request is not creating a forwarding rule, or if therequest is creating a forwarding rule for an internal Google Cloud loadbalancer:

!compute.isForwardingRuleCreationOperation() || (  compute.isForwardingRuleCreationOperation() &&  compute.matchLoadBalancingSchemes([    'INTERNAL', 'INTERNAL_MANAGED', 'INTERNAL_SELF_MANAGED'  ]))

For details about load-balancing schemes, seeUsing IAM Conditions on Google Cloud load balancers.

Example URL host or path expressions (for IAP)

In a role binding, the following condition expression allows accessonly for certain subdomains or URL paths in the request:

request.host == 'hr.example.com'request.host.endsWith('.example.com')request.path == '/admin/payroll.js'request.path.startsWith('/admin')

Example expression with different types of attributes

In a role binding, the following condition expression allows accessif the request is made during a specific time, matching a resource name prefix,with the chosen access level, and for a specific resource type:

request.time > timestamp('2018-08-03T16:00:00-07:00') &&request.time < timestamp('2018-08-03T16:05:00-07:00') &&((resource.name.startsWith('projects/project-123/zones/us-east1-b/instances/dev') || (resource.name.startsWith('projects/project-123/zones/us-east1-b/instances/prod') &&  'accessPolicies/34569256/accessLevels/CorpNet' in request.auth.access_levels)) || resource.type != 'compute.googleapis.com/Instance')

What's next

• Get details about thecondition attributesthat you can use to manage access.
• Learn more aboutallow policies.
• Findresource types that accept conditional role bindings.