This page describes the Conditions feature of Identity and Access Management (IAM). This feature allows you to define and enforce conditional, attribute-based access control for Google Cloud resources.
With IAM Conditions, you can choose to grant resource access to identities (members) only if configured conditions are met. For example, this could be done to configure temporary access for users in the event of a production issue or to limit access to resources only for employees making requests from your corporate office.
Conditions are specified in the role bindings of a resource's IAM
policy. When a condition exists, the access request is only granted if the
condition expression evaluates to true
. Each condition expression is defined
as a set of logic statements allowing you to specify one or more attributes to
check.
IAM policies with conditions
IAM policies comprise one or more role bindings, which have the following structure:
"bindings": [ { "role": ... "members": ... "condition": ... }, ... ]
The condition
object is optional, and each role binding can contain zero or
one condition. If a role binding does not have a condition
object, the members
in that role binding always have the specified role on the resource.
The condition
object has the following structure:
"condition": { "title": ... "description": ... "expression": ... }
The condition's title
is required, but the description
is optional. Both the
title and description are purely informational fields to help you identify and
describe the condition.
The expression
field is required. It defines an
attribute-based logic expression using a subset of the
Common Expression Language (CEL). CEL
is described in more detail in the section below. The condition expression
can
contain multiple statements, each uses one attribute, and statements are
combined using logical operators, following CEL language specification.
To learn how to add, modify, and remove conditional role bindings, see Managing conditional role bindings.
CEL for conditions
Common Expression Language, or CEL, is the expression language used to specify an expression in IAM Condition. It is tailored to express attribute-based logic expressions. For more information, see the CEL spec and its language definition.
In IAM Conditions, a subset of CEL is used for the purpose of
achieving boolean authorization decisions based on attribute data. In general, a
condition expression consists of one or more statements that are joined using
logical operators (&&
, ||
, or !
). Each statement expresses an
attribute-based control rule that applies to the role binding, and ultimately
determine whether authorization is allowed.
The most important CEL features related to conditions are described below:
- Variables: Conditions use variables to express a given attribute, such as
request.time
(of type Timestamp) orresource.name
(of type String). These variables are populated with value based on the context at runtime. - Operators: Every data type, such as Timestamp or String, supports a set
of operators that can be used to create a logic expression. Most commonly,
operators are used to compare the value contained in a variable with a literal
value, such as
resource.service == "compute.googleapis.com"
. In this example, if the input value ofresource.service
iscompute.googleapis.com
, then the expression evaluates totrue
. - Functions: A function is a "compound" operator for data types that support
more complex operations. In condition expressions, there are predefined
functions that can be used in conjunction with a given data type. For example,
request.path.startsWith("/finance")
uses a String prefix match function, and evaluates totrue
if the value ofrequest.path
contains a matching prefix, such as "/finance". - Logical operators: Conditions supports three logical operators that can be
used to build complex logic expressions from simple expression statements:
&&
,||
, and!
. These logical operators make it possible to use multiple input variables in a condition expression. For example:request.time.getFullYear() < 2020 && resource.service == "compute.googleapis.com"
joins two simple statements, and requires both statements to be met in order to produce atrue
overall evaluation result.
For more information about supported variables, operators, and functions, see the attribute reference.
Condition attributes
Condition attributes are either based on the requested resource (e.g., its type or name) or based on details about the request (e.g., its timestamp, originating IP address, or destination IP address of the target Compute Engine virtual machine (VM) instance). Expression examples using these attributes are provided below.
Resource attributes
Resource attributes enable you to create conditions that evaluate the resource in the access request, including the resource type, the resource name, and the Google Cloud service being used.
For a complete list of resource attributes, see the Resource attributes reference.
To learn how to use resource attributes to configure resource-based access, see Configuring resource-based access.
Example expressions
Allow access to Compute Engine VM instances, but no other type of resource:
resource.type == "compute.googleapis.com/Instance"
Allow access to Cloud Storage resources, but no other service's resources:
resource.service == "storage.googleapis.com"
Allow access only to Cloud Storage buckets whose names start with a specified prefix:
resource.type == "storage.googleapis.com/Bucket" &&
resource.name.startsWith("projects/_/buckets/exampleco-site-assets-")
Request attributes
Request attributes enable you to create conditions that evaluate details about the request, such as its access level, its date/time, the destination IP address and port (for IAP TCP tunneling), or the expected URL host/path (for IAP).
Example access level expression (for IAP only)
Allow access only if request meets an organization-defined access level; in the
following example, the organization defined an access level, CorpNet
, that
limits access to the range of IP addresses where traffic enters and exits a
corporate network:
"accessPolicies/199923665455/accessLevels/CorpNet" in
request.auth.access_levels
Access levels are defined by your organization. They are assigned based on attributes of the request, such as origin IP address, device attributes, the time of day, and more. See the Access Context Manager documentation for more information about access levels.
Example date/time expressions
Allow access temporarily until a specified expiration date/time:
request.time < timestamp("2021-01-01T00:00:00Z")
Allow access only 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") <= 5
Allow access only for a specified month and year, based on the time zone for Berlin, Germany:
request.time.getFullYear("Europe/Berlin") == 2020
request.time.getMonth("Europe/Berlin") < 6
To specify a timestamp, use RFC 3339 format. To specify a time zone, use the identifiers in the IANA Time Zone Database.
For more details about date/time expressions, see the CEL specification.
To learn how to use date/time expressions to configure temporary access, see Configuring temporary access.
Example destination IP/port expressions (for IAP TCP tunneling)
Allow access to an internal destination IP address or port number:
destination.ip == "14.0.0.1"
destination.ip != "127.0.0.1"
destination.port == 22
destination.port > 21 && destination.port <= 23
Example forwarding rule expressions
Allow access for a member if the request is not creating a forwarding rule, or if the request is creating a forwarding rule for an internal Google Cloud load balancer:
!compute.isForwardingRuleCreationOperation() || (
compute.isForwardingRuleCreationOperation() &&
compute.matchLoadBalancingSchemes([
'INTERNAL', 'INTERNAL_MANAGED', 'INTERNAL_SELF_MANAGED'
]))
)
Example URL host/path expressions (for IAP)
Allow access only 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")
For details about load balancing schemes, see Using IAM Conditions on Google Cloud load balancers.
Example expression with different types of attributes
Allow access if the request is made during a specific time, matching a resource name prefix, with the desired 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")
Resource types that accept conditional role bindings
You can add conditions to IAM policies for the following types of Google Cloud resources:
Google Cloud service | Resource types |
---|---|
Cloud Key Management Service (Cloud KMS) |
|
Cloud Storage | Buckets 1, 2 |
Compute Engine |
|
Identity-Aware Proxy (IAP) |
|
Resource Manager |
|
Secret Manager |
|
1 Available for buckets that use uniform bucket-level access. If you cannot enable uniform bucket-level access, you can add conditions to the IAM policy for a higher-level resource, such as the project.
2 You can use the
|
Other types of resources do not allow conditions in their IAM policies. However, you can add conditional role bindings at the organization or project level, and other resources will inherit those role bindings through the resource hierarchy.
For details about which attributes affect which resource types, see the attribute reference.
Limits
The following limits apply to IAM Conditions:
- As described in the details about supported services on this page, you can add conditions to role bindings only for selected Google Cloud services. In addition, most condition attributes are compatible with a limited number of services.
- Basic roles (
roles/owner
,roles/editor
,roles/viewer
) are unsupported; if you attempt to set a condition in a role binding that uses a basic role, thesetIamPolicy
operation will fail. - The
allUsers
andallAuthenticatedUsers
values are unsupported member types in a conditional role binding. If you specify one of these member types, thesetIamPolicy
operation will fail. - We recommend that each policy contains no more than 100 conditional role bindings. There is an underlying storage size limitation for one policy. Policies comprising many conditional role binding may exceed the size limit and might be rejected.
- We recommend that you set only a few different conditional role bindings for the
same member for the same role (different conditions). However, you can include
the maximum of 20 role bindings for
same role and same member. If you exceed this number, the
setIamPolicy
operation will fail. - You can use a maximum of 12 logical operators in
one condition expression. If you exceed this number, the
setIamPolicy
operation will fail.
Next steps
- Learn more about IAM policies.