Overview of Cloud IAM Conditions

Important: This is a Private Beta release of Cloud IAM Conditions. This feature might be changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA or deprecation policy.

Introduction

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

With Cloud 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 Cloud 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.

Cloud IAM policies with conditions

Cloud IAM policies are comprised of 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. A role binding with no condition object is considered as an unconditional grant, as no condition check is necessary. 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 attributes, and statements are combined using logic operators, following CEL language specification.

CEL for conditions

Common Expression Language, or CEL, is the expression language used to specify an expression in Cloud IAM Condition. It is tailored to express attribute-based logic expressions. For more information, see the CEL spec and its language definition.

In Cloud 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 logic 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 condititions are described below:

• Variables: Conditions use variables to express a given attribute, such as request.time (of type Timestamp) or resource.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 of resource.service is compute.googleapis.com, then the expression evaluates to true.
• 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 to true if the value of request.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 a true overall evaluation result.

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 instance). Expression examples using these attributes are provided below.

Note: In order to use the Conditions feature in Cloud IAM policies set on a Cloud Storage bucket, you must first enable Bucket Policy Only on the bucket.

Resource attributes

Resource attributes provide restrictions based on the resource in the access request, such as the resource type, resource name, or the GCP service being used.

Example expressions

Note: The resource type format is subject to change in future releases of Cloud IAM Conditions.

Allow access to compute 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 resources whose names start with a specified prefix string:

resource.name.startsWith("projects/_/buckets/exampleco-site-assets-")

Request attributes

Request attributes provide restrictions based on details about the access request, such as its date/time, the expected URL host/path (for Cloud IAP), destination IP address and port (for Cloud IAP TCP tunneling), or access levels. Access levels are derived from an organization's configuration, and currently allow for restrictions on permitted origin IP addresses.

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:

request.time.getHours("Europe/Berlin") >= 9 &&
request.time.getHours("Europe/Berlin") <= 17 &&
request.time.getDayOfWeek("Europe/Berlin") >= 1 &&
request.time.getDayOfWeek("Europe/Berlin") <= 5

Allow access only for a specified month and year:

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

Valid formats include:

• Timestamps: RFC 3339 format
• Timezones: IANA Database format

Example URL host/path expressions (for Cloud 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")

Example destination IP/port expressions (for Cloud IAP TCP tunneling)

Allow access for certain destination IP or port in the request:

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

Example access level expression

Allow access only if request meets a customer-defined access level; in this case, the IP ranges of the corporate network are specified in the "TrustedCorpNet" access level:

"accessPolicies/199923665455/accessLevels/TrustedCorpNet" in
request.auth.access_levels

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/CorpNetwork2" in request.auth.access_levels)) ||
 resource.type != "compute.googleapis.com/Instance")

Known limitations

The following known limitations exist for the beta release of Cloud IAM Conditions:

• Primitive roles (roles/Owner, roles/Editor, roles/Viewer) are unsupported; if you attempt to set a condition in a role binding that uses a primitive role, the setIamPolicy operation will fail.
• The allUsers and allAuthenticatedUsers values are unsupported member types in a conditional role binding. If you specify one of these member types, the setIamPolicy 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 logic operators in one condition expression. If you exceed this number, the setIamPolicy operation will fail.

Next steps

• Learn more about Cloud IAM policies.