Overview of Cloud IAM Conditions

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 permissions 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 located in your corporate office.

Conditions are specified in the role bindings of a resource’s Cloud IAM policy. When a condition exists, the role 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 many 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 only one. However, the condition expression can contain multiple statements that evaluate many different attributes. A role binding with no condition object will always be granted to the specified members, 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 defines an attribute-based logic expression using a subset of the Common Expression Language (CEL). For more information, see the CEL specification and its language definition.

In general, a condition expression consists of one or more clauses that are joined using logic operators (&&, ||, or !). Each clause expresses an attribute-based control rule that applies to the binding.

Condition Attributes

For this Private Beta release, supported 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 or originating IP address). Examples and a description of both attribute types are described below.

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

Allow access to compute instances, but no other type of resource:

resource.type == “google.cloud.compute.Instance”

Allow access to Cloud Storage resources, but no other service's resources:

resource.service == “google.cloud.storage”

Allow access only to resources whose names start with a specified 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), 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.

Example Date/Time Expressions

Allow access temporarily until a specified expiration date/time:

request.time < timestamp("2019-01-01T07: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") == 2018
request.time.getMonth("Europe/Berlin") < 6

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 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 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 != "google.cloud.compute.Instance")

How to Set Conditions

Conditional role bindings are set using the same setIamPolicy method that is used to configure any other role bindings. For example, to set a role binding with a condition on a project, you can use the REST API, gcloud command-line tool, or the IAM page in the Cloud Console.

The following JSON example demonstrates a condition in the context of a complete Cloud IAM policy:

{
  "bindings": [
    {
      "role": "roles/storage.objectViewer",
      "members": "user:jane@example.com",
      "condition": {
          "title": "expires_end_of_2018",
          "description": "Expires at midnight on 2018-12-31",
          "expression": "request.time < timestamp(\"2019-01-01T00:00:00Z\")"
      }
    }
  ]
}

Signing Up for the Private Beta

Currently, in order to use Cloud IAM Conditions, you must be accepted into the Private Beta. Fill out this form to apply.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Identity and Access Management Documentation