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, including a brief usage description, and supported Google Cloud services for each attribute.

If you try to access a service through a conditional role binding that contains an attribute unsupported by the service, access will be forbidden. The services supported for each attribute are documented below.

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.	Cloud Load Balancing Cloud VPN Compute Engine protocol forwarding Traffic Director
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

Refer to the following descriptions of each row in the tables below to better understand how to use each attribute:

Attribute variable: The attribute's syntactic name.
Attribute type: The data type of the attribute, such as a String, Integer, etc.
Supported operator(s): The commonly supported operators that should be used with the attribute, such as ==, !=, etc.
Supported Operand(s): The commonly supported type of the operand.
Discussion: Additional detail about the attribute, including its intended semantic usage and behavior.
Example(s): Examples demonstrating the intended usage of the attribute.

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.

Beta-level support for this attribute is available in Identity-Aware Proxy.

`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.

Supported basic functions Type Description

Supported basic functions	Type	Description
`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

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.

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:

Cloud Load Balancing
Cloud VPN
Compute Engine protocol forwarding
Traffic Director

Supported functions

Supported functions Type Description

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. Note: In general, if you use this function in a condition expression, you should also use `compute.isForwardingRuleCreationOperation()`. See the examples below. 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.

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.

Note: In general, if you use this function in a condition expression, you should also use compute.isForwardingRuleCreationOperation(). See the examples below.

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

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

`resource.name` attribute

Attribute variable	`resource.name`
Attribute type	String
Supported operators	`startsWith()`, `endsWith()`, `==`, `!=`
Supported operand	String For the format of a list of supported resource name strings, see Resource attributes for Cloud IAM Conditions.
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 `==` and `!=` operators are for comparison with the entire `resource.name`.
Examples	Example 1: `resource.name.startsWith("projects/project-123/zones/us-east1-b/instances/prod-")` Example 2: `resource.name.startsWith("projects/_/buckets/my_bucket/objects/test-object-")` Note: This example contains an underscore (`_`) in the resource name: `projects/_/buckets/{bucketName}`. The underscore character is used in place of the project ID for paths to Cloud Storage buckets and objects only. For other types of resources, use the actual project ID in the path. Example 3: `resource.name.endsWith(".jpg")` Example 4: `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.