Attribute reference for Cloud IAM Conditions

This topic describes supported attributes in a condition expression.

Supported condition attributes

The following table summarizes the supported attributes and indicates which Google Cloud services recognize each attribute:

Attribute Usage summary Supported Google Cloud services

Access levels attribute

Restrict access via specific access level(s).

An access level is a calculated attribute based on raw attributes about the request and requester, such as origin IP address, device attributes, time of day, and more. For example, an onNetwork access level might require that the device making the request originates from a particular IP address range. Access levels are defined by organization's administrators.

Identity-Aware Proxy

Date/time attributes

Set expirable, scheduled, or limited-duration access to Google Cloud resources.

All Google Cloud services

Destination IP/port attributes

Restrictions on the expected destination IP address and/or port of a request. For example, a Compute Engine virtual machine (VM) instance might expose an external IP, such as 10.0.0.2, but port 22 might be exposed for administrative usage only.

Current usage is primarily for Identity-Aware Proxy TCP forwarding.

Identity-Aware Proxy

Forwarding rule attributes

Specify the types of forwarding rules that a member can create. For example, you could allow a member to create forwarding rules for internal Google Cloud load balancers, which handle traffic that originates inside a Google Cloud network, but not for external Google Cloud load balancers, which handle traffic that originates from the internet.

Resource attributes

The resource name, resource type, and resource service attributes are used to further restrict the scope of an access grant provided by the role binding, to a subset of resources under the Google Cloud resource where the Cloud IAM policy is attached.

  • Cloud Key Management Service
  • Cloud Spanner
  • Cloud Storage
  • Compute Engine

URL path/host attributes

Set restrictions on the expected URL path and/or host of a request. For example, a restriction could specify that https://example.com is the main application accessible by a general domain of users, while https://hr.example.com/admin is used to access a page in the application where only Human Resources admins can access this portion.

Identity-Aware Proxy

Some types of Google Cloud resources do not allow conditions in their Cloud IAM policies. However, you can add conditional role bindings at the organization, folder, or project level, and other resources will inherit those role bindings through the resource hierarchy. For details, see Resources that accept conditional role bindings.

When you use attributes at the organization, folder, or project level, keep in mind that if you send a request to a service, and the service does not recognize an attribute in a condition, the condition always evaluates to false. For example, the condition destination.port == 21 always evaluates to false for BigQuery, because BigQuery does not recognize the destination IP/port attributes.

To prevent this issue, use the resource attributes on this page to limit the scope of the condition. For example, the condition resource.service != "iap.googleapis.com" || destination.port == 21 evaluates to true for every service except Identity-Aware Proxy; in contrast, for Identity-Aware Proxy, the condition checks the destination port.

Access levels attribute

The access levels attribute enables users to set a condition requiring that a request meets specific access level(s) in order to be authorized.

The access level attribute is derived from attributes of the request, such as the origin IP address, device attributes, the time of day, and more. For example, an access level named fullyTrusted might require that the device making the request is owned by the company and has a screen lock. An onNetwork access level might require that the device making the request originates from a particular IP address range.

See the Access Context Manager docs for more information about access levels.

This attribute is available in Identity-Aware Proxy as a private beta.

request.auth.access_levels attribute

Attribute variable request.auth.access_levels
Attribute type List of Strings
Supported operators in
Supported operand String
Discussion

The variable request.auth.access_levels appears on the right side, and a String representing a full name of the defined access level appears on the left side of the in operator.

The full name of an access level has a name formatted in the following pattern:
"accessPolicies/<policyNumber>/accessLevels/<shortName>"

Note: The access level string is case sensitive, and it must match exactly what is configured in Access Context Manager to take the intended effect. For instance, "accessPolicies/199923665455/accessLevels/CorpNet" is a valid string literal to be used in the expression, however, "accessPolicies/199923665455/accesslevels/CorpNet" will not achieve the intended effect.

Example
"accessPolicies/199923665455/accessLevels/CorpNet"
in request.auth.access_levels

Date/time attribute

The date/time attribute is used to set expirable, scheduled, or limited-duration access to Google Cloud resources.

All Google Cloud services support this condition attribute.

Supported basic functions and operators

The attribute variable used for the date/time attribute is request.time, of type Timestamp. You can also convert strings to the Timestamp and Duration types.

Supported basic functions Type Description
date String --> Timestamp

Function: Convert a String to a Timestamp.
Parameter: String in the format YYYY-MM-DD, where YYYY is the year, MM is the two-digit month, and DD is the two-digit day. The resulting Timestamp contains the specified date and the time 00:00:00.000 UTC.

Example:

date("2020-02-01")
A timestamp that represents the date 2020-02-01 and the time 00:00:00.000 UTC.

duration String --> Duration

Function: Convert a String to a Duration.
Parameter: String containing a number of seconds, followed by s

Examples:

duration("90s")
A duration that represents 1.5 minutes.

duration("2592000s")
A duration that represents 30 days.

timestamp

String --> Timestamp

Function: Convert a String to a Timestamp.
Parameter: String adhering to UTC format (RFC 3339).

Examples:

timestamp("1985-04-12T23:20:50.52Z")
This represents the timestamp conversion for 20 minutes and 50.52 seconds after the 23rd hour of April 12th, 1985 in UTC.

timestamp("1996-12-19T16:39:57-08:00")
This represents the timestamp conversion for 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from UTC. Note that this is equivalent to 1996-12-20T00:39:57Z in UTC. This offset does not reflect timezone, for example, offset for Pacific Standard Time is -08:00 during winter, and it is -07:00 during summer to respect daylight saving.

Important Note:
The String must follow the format requirement for UTC string. Any string not compliant with UTC format will cause the timestamp() function to fail to convert to a timestamp value. As the result, the condition evaluation on the expression using timestamp() will result in denying access check.

<, <=, >, >=

(Timestamp, Timestamp) --> bool

Function: General comparison with Timestamp type.

Examples:

request.time < timestamp("2018-04-12T00:00:00.00Z")
request.time <= timestamp("2018-04-12T00:00:00.00Z")
request.time > timestamp("2018-04-12T00:00:00.00Z")
request.time >= timestamp("2018-04-12T00:00:00.00Z")
These expressions set the comparison of request time with a specific timestamp, which is April 12, 2018 in UTC. Commonly used for setting the "start time", or "expiration time", restriction to the role grant.

Note: Given the time precision to milliseconds, including the equality and inequality comparison (==, !=) does not have significant effect.

+, - (Timestamp, Duration) --> Timestamp

Function: Add or subtract a Duration from a Timestamp.

Examples:

timestamp("2018-04-12T14:30:00.00Z") + duration("1800s")
Finds the timestamp that falls 30 minutes after 14:30:00 GMT on 2018-04-12.

timestamp("2018-04-12T14:30:00.00Z") - duration("5184000s")
Find the timestamp that falls 60 days before 14:30:00 GMT on 2018-04-12.

Supported advanced functions and operators

The attribute variable used for the date/time attribute is request.time, of type Timestamp.

Supported advanced functions Type Description

<, <=, >, >=, ==, !=

(int, int) --> bool

Function: General comparison with int type.

Discussion:
This set of comparison operators for integers are mainly used for the remaining set of "advanced functions" with Timestamp functions. All these functions (defined in the rest of this table), convert a certain portion of the timestamp value to an int. Further examples are provided for each advanced function to suggest common usage.

getDate, getDayOfMonth, getDayOfWeek, getDayOfYear

Timestamp.() --> int

Timestamp.(string) --> int

Functions:
getDate: Get the day of month from the Timestamp value using one-based indexing. In other words, the first day of the month is 1.

getDayOfMonth: Get the day of month from the Timestamp value using zero-based indexing. In other words, the first day of the month is 0.

getDayOfWeek: Get the day of the week from the Timestamp value, zero-based on Sunday. In other words, Sunday(0), Monday(1), ..., Saturday(6).

getDayOfYear: Get the day of year from the Timestamp value using zero-based indexing. In other words, the first day of the year is 0.

Parameters:
String as time zone: conversion based on date with time zone. Note: when the time zone is unspecified, the conversion will be based on date in UTC.

For more information about valid timezone strings, see Supported Time Zone Values.

Example:

request.time.getDayOfWeek() > 0 && request.time.getDayOfWeek() < 6
This expression is evaluated to true if the incoming request is sent between Monday to Friday by UTC time.

Example:

request.time.getDayOfWeek("Europe/Berlin") > 0 && request.time.getDayOfWeek(Europe/Berlin") < 6
This expression is evaluated to true if the incoming request is sent between Monday to Friday in the Berlin timezone.

Example:

request.time.getDayOfYear("America/Los_Angeles") >= 0 && request.time.getDayOfYear("America/Los_Angeles") < 5
This expression is evaluated to true if the incoming request is sent within first 5 days of the year in the Los Angeles timezone.

getFullYear

Timestamp.() --> int

Timestamp.(string) --> int

Function: Gets the year from the date.

Parameters:
Version 1: No parameter; From the date in UTC.
Version 2: Timezone string; from the date in timezone.

For more information about valid timezone strings, see Supported Time Zone Values.

Example:

request.time.getFullYear("America/Los_Angeles") == 2018
This expression is evaluated to true if incoming request is sent within the year 2018, in the Los Angeles timezone.

Example:

request.time.getFullYear() < 2020
This expression is evaluated to true if incoming request is sent before the end of 2019 in UTC.

getHours

Timestamp.() --> int

Timestamp.(string) --> int

Function: Gets hours from the date; values range from 0 to 23.

Parameters:
Version 1: No parameter; From the date in UTC.
Version 2: Timezone string; from the date in timezone.

For more information about valid timezone strings, see Supported Time Zone Values.

Example:

request.time.getHours("Europe/Berlin") >= 9 && request.time.getHours("Europe/Berlin") <= 17
This expression specifies a work hour condition. It is evaluated to true if the request is sent between 9am to 5pm in the Berlin timezone.

Note:

Combining getHours() with getDayofWeek() could be used to set a condition on legal working hours, such as for meeting a jurisdiction requirement.

getMilliseconds

Timestamp.() --> int

Timestamp.(string) --> int

Function: Gets milliseconds within a second from the timestamp; values range from 0 to 999.

Parameters:
Version 1: No parameter; From the date in UTC.
Version 2: Timezone string; from the date in timezone.

For more information about valid timezone strings, see Supported Time Zone Values.

Note:

This function is less useful, given its limited usage semantically.

getMinutes

Timestamp.() --> int

Timestamp.(string) --> int

Function: Gets minutes within an hour from the Timestamp; values range from 0 to 59.

Parameters:
Version 1: No parameter; From the date in UTC.
Version 2: Timezone string; from the date in timezone.

For more information about valid timezone strings, see Supported Time Zone Values.

Note:

This function is less useful, given its limited usage semantically.

getMonth

Timestamp.() --> int

Timestamp.(string) --> int

Function: Gets months within a year from the Timestamp; values range from 0 to 11.

Parameters:
Version 1: No parameter; From the date in UTC.
Version 2: Timezone string; from the date in timezone.

For more information about valid timezone strings, see Supported Time Zone Values.

Example:

request.time.getMonth("America/Los_Angeles") == 3
This expression is evaluated to true if the incoming request is sent during April, in the Los Angeles timezone.

getSeconds

Timestamp.() --> int

Timestamp.(string) --> int

Function: Gets seconds within one minute from the Timestamp; values range from 0 to 59.

Parameters:
Version 1: No parameter; From the date in UTC.
Version 2: Timezone string; from the date in timezone.

For more information about valid timezone strings, see Supported Time Zone Values.

Note:

This function is less useful, given its limited usage semantically.

Destination IP/port attributes

The destination IP/port attribute enables users to set restrictions on the expected destination IP address and/or port of a request. For example, a Compute Engine VM instance might expose an external IP address 10.0.0.1 on port 3001 for general usage, and the IP address 10.0.0.2 and port 22 are exposed for administrative usage only.

See the Identity-Aware Proxy docs for more information about TCP forwarding.

This attribute is supported in Identity-Aware Proxy.

destination.ip attribute

Attribute variable destination.ip
Attribute type String
Supported operators ==, !=
Supported operand String
Discussion

The variable destination.ip is expected to be a String representing an IP address in IPv4 format.

Note: The startsWith(<prefix string of IP>) function and the endsWith(<suffix string of IP>) function are not intended to be used with the destination.ip attribute. While setting a condition such as destination.ip.startsWith(<prefix string of IP>) will not result in syntax error when executing a setIamPolicy operation, it is not recommended due to unexpected results. Prefix matching on the IP string is not recommended to perform an IP address range check on CIDRs.

Examples
destination.ip == "10.0.0.1"
destination.ip != "10.0.0.1"

destination.port attribute

Attribute variable destination.port
Attribute type Integer
Supported operators ==, !=, <, <=, >, >=
Supported operand Integer
Discussion

The variable destination.port is expected to be an Integer representing a TCP port number.

Examples
destination.port == 21
destination.port < 3001

Forwarding rule attributes

The forwarding rule attributes enable you to specify the types of forwarding rules that a member can create. For example, you could allow a member to create forwarding rules for internal Google Cloud load balancers, which handle traffic that originates inside a Google Cloud network, but not for external Google Cloud load balancers, which handle traffic that originates from the internet.

For Cloud Load Balancing, the forwarding rule attributes do not affect the ability to create other components of a Google Cloud load balancer, such as backend services, target proxies, health checks, and URL maps.

The forwarding rule attributes are supported in the following Google Cloud services:

Supported functions

Supported functions Type Description
compute.isForwardingRuleCreationOperation() () --> bool

Function: Check whether the request is creating a forwarding rule.

Examples: See the examples for compute.matchLoadBalancingSchemes().

compute.matchLoadBalancingSchemes() Array.(string) --> bool

Function: Check whether the request affects one of the specified types of load balancing scheme. To find the identifier for each load balancing scheme, as well as details about each scheme, see Using Cloud IAM Conditions on Google Cloud load balancers.

Parameters: Array of Strings

Example:

!compute.isForwardingRuleCreationOperation() || (
  compute.isForwardingRuleCreationOperation() &&
  compute.matchLoadBalancingSchemes([
    'INTERNAL', 'INTERNAL_MANAGED', 'INTERNAL_SELF_MANAGED'
  ]))
)
  • If the request is not creating a forwarding rule, grant the role to the member.
  • If the request is creating a forwarding rule, grant the role only if the forwarding rule affects an INTERNAL, INTERNAL_MANAGED, or INTERNAL_SELF_MANAGED load balancing scheme.

Resource attributes

The resource name, resource type, and resource service attributes are typically used to further restrict the scope of an access grant provided by the role binding. When a role contains permissions that apply to different resource-specific attributes, resource-based conditions can be used to grant a subset of the role's permissions for specific type(s) or for specific service(s).

The resource attributes are supported in the following Google Cloud services:

  • Cloud Spanner
  • Cloud Storage
  • Compute Engine
  • Identity-Aware Proxy
  • Cloud Key Management Service
  • Resource Manager (resource type and resource service only)

For details about the resource attributes that you can use for each service, see Resource attributes for Cloud IAM Conditions.

Extracting values from resource names

You can use the extract() function to extract a value from a resource name. This function enables condition expressions to refer to an arbitrary part of the resource name.

To extract a value, you use the extract() function and provide an extraction template, which specifies the part of the resource name to extract. For example, you might use the template projects/{project}/ to extract a project ID from the resource name of a Compute Engine VM instance.

An extraction template contains the following parts:

  • An identifier, enclosed in curly braces, that identifies the substring to extract. Choose a short, meaningful identifier that makes it clear what value you want to extract. You can use uppercase and lowercase letters from A to Z; numeric digits; dashes (-); and underscores (_).

    In the template projects/{project}/, the identifier is project.

  • (Optional) A prefix, which must appear before the substring to extract.

    In the template projects/{project}/, the prefix is projects/.

  • (Optional) A suffix, which must appear after the substring to extract.

    In the template projects/{project}/, the suffix is /.

The extract() function returns different values depending on whether the extraction template has a prefix, a suffix, or both:

Has prefix Has suffix Extracted value
The entire resource name
check The characters after the first occurrence of the prefix, or an empty string if there are no characters after the prefix
check The characters before the first occurrence of the suffix, or an empty string if there are no characters before the suffix
check check The characters between the first occurrence of the prefix and the first subsequent occurrence of the suffix, or an empty string if there are no characters between the prefix and the suffix

If you specify a prefix or suffix that do not appear in the resource name, or if the suffix appears only before the prefix, the extract() function returns null.

The following examples show the output from several different extraction templates. In these examples, the resource is a Cloud Storage object named projects/_/buckets/acme-orders-aaa/data_lake/orders/order_date=2019-11-03/aef87g87ae0876:

Extraction template Output
/order_date={date}/ 2019-11-03
buckets/{name}/ acme-orders-aaa
/orders/{empty}order_date Empty string
{start}/data_lake projects/_/buckets/acme-orders-aaa
orders/{end} order_date=2019-11-03/aef87g87ae0876
{all} projects/_/buckets/acme-orders-aaa/data_lake/orders/order_date=2019-11-03/aef87g87ae0876
/orders/{none}/order_date= null
/orders/order_date=2019-11-03/{id}/data_lake null

You can also use the date/time functions and operators on this page to convert the extracted value to a Timestamp. For examples, see Configuring resource-based access.

resource.name attribute

Attribute variable resource.name
Attribute type String
Supported operators startsWith(), endsWith(), extract(), ==, !=
Supported operand

String

Each resource type uses a specific format for the resource name. For a list of formats, see Resource name format.

Discussion

The resource.name contains the relative resource name for the target resource in the request. The relative resource name is a URI path without a leading forward slash (/).

The startsWith() function takes the prefix string literal to be evaluted against resource.name.

The endsWith() function takes the suffix string literal to be evaluated against resource.name.

The extract() function uses an extraction template to extract part of resource.name. For details, see Extracting values from resource names on this page.

The == and != operators are for comparison with the entire resource.name, or an extracted portion of the resource.name.

Examples

Example 1 (for a Compute Engine VM instance):

resource.name.startsWith("projects/project-123/zones/us-east1-b/instances/prod-")

Example 2 (for a Cloud Storage bucket):

resource.name.startsWith("projects/_/buckets/my_bucket/objects/test-object-")

Example 3 (for a Cloud Storage object):

resource.name.endsWith(".jpg")

Example 4 (for multiple resource types):

resource.name.extract("projects/{project}/")

Example 5 (for a Cloud Storage bucket):

resource.name != "projects/_/buckets/secret-bucket-123"

resource.service attribute

Attribute variable resource.service
Attribute type String
Supported operators ==, !=
Supported operand String


For a list of all supported resource service string literals, see Resource attributes for Cloud IAM Conditions.

Discussion The variable resource.service, if used, is intended for equality or inequality comparisons.

Note: The .startsWith(<prefix string>), and .endsWith(<suffix string>) functions are not intended to be used with the resource.service attribute. It is not recommended due to unexpected evaluation results.

Examples

Example 1:

resource.service == "compute.googleapis.com"

resource.type attribute

Attribute variable resource.type
Attribute type String
Supported operators ==, !=
Supported operand String


For a list of all supported resource type string literals, see Resource attributes for Cloud IAM Conditions.

Discussion The variable resource.type, if used, is intended for equality or inequality comparisons.

Note: The .startsWith(<prefix string>), and .endsWith(<suffix string>) functions are not intended to be used with the resource.type attribute. It is not recommended due to unexpected evaluation results.

Examples

Example 1:

resource.type != "compute.googleapis.com/Image"

Example 2:

(resource.type == "compute.googleapis.com/Image" ||
resource.type == "compute.googleapis.com/Disk")

URL path/host attribute

The URL path/host attribute enables users to set restrictions on the expected URL path and/or host of a request. For example, a restriction could specify that https://example.com is the main application accessible by a general domain of users, while https://hr.example.com/admin is used to access a page in the application where only Human Resources admins can access this portion.

This attribute is supported in Identity-Aware Proxy.

request.path attribute

Attribute variable request.path
Attribute type String
Supported operators ==, startsWith(), endsWith()
Suppoted operands/parameters
  • String: ==
  • Constant prefix string: startsWith()
  • Constant suffix string: endsWith()
Discussions Note: The != operator is not recommended for use. Instead of negative comparison, such as,
request.path != "/admin"
, the recommended usage is prefix match, for instance
! request.path.startsWith("/admin")
. This way, URL paths parented by "/admin", such as "/admin/payroll/", are all protected against unintended access.
Examples

Example 1:

request.path == "/admin"
request.path == "/admin/payroll"

The String used in the equality (==) comparison in the two examples above is expected to be formatted according to URL path standards.

Example 2:

request.path.startsWith("/admin")

A String that represents the prefix of a URL path is used in the function.

Example 3:

request.path.endsWith("/payroll.js")

A String that represents the suffix of a URL path is used in the function.

request.host attribute

Attribute variable request.host
Attribute type String
Supported operators ==, endsWith()
Supported operands/parameters
  • String: ==
  • Constant suffix string: endsWith()
Discussion The .startsWith(<prefix string>) function is not intended to be used with the request.host attribute. While setting a condition such as request.host.startsWith(<prefix string>) will not result in syntax errors when executing a setIamPolicy operation, it is not recommended due to unexpected results. Similarly != is not recommended for use.
Examples

Example 1:

request.host == "www.example.com"
request.host == "hr.example.com"

The String used in the equality (==) comparison in the two examples above is expected to be formatted according to URL string standards for the hostname of a website.

Example 2:

request.host.endsWith("example.com")

A String that represents the suffix of a hostname of a website.