Managing conditional role bindings

This topic describes how to add, modify, and remove conditional role bindings in your Identity and Access Management (IAM) policies.

Before you begin

Adding a conditional role binding to a policy

Conditional role bindings can be added to new or existing IAM policies to further control access to Google Cloud resources. This section shows you how to add a simple time-based condition to an existing policy using the Cloud Console, the gcloud command-line tool, and the REST API.

To add a conditional role binding to an existing policy:

Console

  1. In the Cloud Console, go to the IAM page.

    Go to the IAM page

  2. From the list of members, locate the desired member and click the button.

  3. From the Edit permissions panel, locate the desired role to configure a condition for. Then under Condition, click Add condition.

  4. In the Edit condition panel, enter a title and optional description for the condition.

  5. You can add a condition expression using either the Condition Builder or the Condition Editor. The condition builder provides an interactive interface to select your desired condition type, operator, and other applicable details about the expression. The condition editor provides a text-based interface to manually enter an expression using CEL syntax.

    Condition Builder:

    1. From the Condition type drop-down, select Expiring Access.
    2. From the Operator drop-down, select by.
    3. From the Time drop-down, click the button to select from a date and time range.
    4. Click Save to apply the condition.
    5. Once the Edit condition panel is closed, click Save again from the Edit permissions panel to update your IAM policy.

    Condition Editor:

    1. Click the Condition Editor tab and enter the following expression (replacing the timestamp with your own):

      request.time < timestamp("2019-12-31T12:00:00.000Z")
    2. After entering your expression, you can optionally choose to validate the CEL syntax by clicking Run Linter above the text box on the top-right.

    3. Click Save to apply the condition.

    4. Once the Edit condition panel is closed, click Save again from the Edit permissions panel to update your IAM policy.

gcloud

IAM policies are set using the read-modify-write pattern.

Execute the gcloud projects get-iam-policy command to get the current IAM policy for the project. In the following example, the JSON version of the policy is downloaded to a path on disk.

Command:

gcloud projects get-iam-policy project-id --format json > file-path

The JSON format of the IAM policy is downloaded:

{
  "bindings": [
    {
      "members": [
        "user:project-owner@example.com"
      ],
      "role": "roles/owner"
    },
    {
      "members": [
        "user:travis@example.com"
      ],
      "role": "roles/iam.securityReviewer"
    }
  ],
  "etag": "BwWKmjvelug=",
  "version": 1
}

Note the policy's current version, which is 1. To configure the policy with expirable access, add the following highlighted condition expression (replacing the timestamp with your own). The gcloud tool updates the version automatically:

{
  "bindings": [
    {
      "members": [
        "user:project-owner@example.com"
      ],
      "role": "roles/owner"
    },
    {
      "members": [
        "user:travis@example.com"
      ],
      "role": "roles/iam.securityReviewer",
      "condition": {
          "title": "Expires_2019",
          "description": "Expires at noon on 2019-12-31",
          "expression":
            "request.time < timestamp('2019-12-31T12:00:00Z')"
      }
    }
  ],
  "etag": "BwWKmjvelug=",
  "version": 3
}

Next, set the new policy by executing the gcloud projects set-iam-policy command:

gcloud projects set-iam-policy project-id file-path

The new policy is applied, and travis@example.com's role binding will expire at the specified time.

REST

Use the read-modify-write pattern to allow access until a specific time.

First, read the IAM policy for the project:

The Resource Manager API's projects.getIamPolicy method gets a project's IAM policy.

Before using any of the request data below, make the following replacements:

HTTP method and URL:

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:getIamPolicy

Request JSON body:

{
  "options": {
    "requestedPolicyVersion": policy-version
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:project-owner@example.com"
      ]
    },
    {
      "role": "roles/iam.securityReviewer",
      "members": [
        "user:travis@example.com"
      ]
    }
  ]
}

Note the policy's current version, which is 1.

Next, modify the policy so that it allows access until a specific time. Make sure to change the version field to the value 3:

{
  "etag": "BwWKmjvelug=",
  "version": 3,
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:project-owner@example.com"
      ]
    },
    {
      "role": "roles/iam.securityReviewer",
      "condition": {
        "title": "Expires_2019",
        "description": "Expires at noon on 2019-12-31",
        "expression": "request.time < timestamp('2019-12-31T12:00:00Z')"
      },
      "members": [
        "user:travis@example.com"
      ]
    }
  ]
}

Finally, write the updated policy:

The Resource Manager API's projects.setIamPolicy method sets the policy in the request as the project's new IAM policy.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.

HTTP method and URL:

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:setIamPolicy

Request JSON body:

{
  "policy": {
    "version": 3,
    "etag": "BwWKmjvelug=",
    "bindings": [
      {
        "role": "roles/owner",
        "members": [
          "user:project-owner@example.com"
        ]
      },
      {
        "role": "roles/iam.securityReviewer",
        "members": [
          "user:travis@example.com"
        ],
        "condition": {
          "title": "Expires_July_1_2020",
          "description": "Expires on July 1, 2020",
          "expression":
            "request.time < timestamp('2020-07-01T00:00:00.000Z')"
        }
      }
    ]
  }
}

To send your request, expand one of these options:

The response contains the updated policy.


Modify an existing conditional role binding

After you create a conditional role binding, you can change the condition expression at any time. This section shows you how to update a time-based condition in an existing policy using the Cloud Console, the gcloud command-line tool, and the REST API.

To modify a conditional role binding in an existing policy:

Console

  1. In the Cloud Console, go to the IAM page.

    Go to the IAM page

  2. From the list of members, locate the desired member and click the button.

  3. From the Edit permissions panel, locate the desired role to configure a condition for. Then under Condition, click the name of the existing condition to edit it.

  4. In the Edit condition panel, you can either keep or update the existing title and description for the condition.

  5. You can either edit the existing condition expression or add a new one using either the Condition Builder or the Condition Editor. The condition builder provides an interactive interface to select your desired condition type, operator, and other applicable details about the expression. The condition editor provides a text-based interface to manually enter an expression using CEL syntax.

    Condition Builder:

    1. Add a new condition expression or modify the existing condition expression.
    2. Click Save to apply the condition.
    3. Once the Edit condition panel is closed, click Save again from the Edit permissions panel to update your IAM policy.

    Condition Editor:

    1. Click the Condition Editor tab and either add a new condition expression or modify the existing condition expression.
    2. After entering your expression, you can optionally choose to validate the CEL syntax by clicking Run Linter above the text box on the top-right.
    3. Click Save to apply the condition.
    4. Once the Edit condition panel is closed, click Save again from the Edit permissions panel to update your IAM policy.

gcloud

IAM policies are set using the read-modify-write pattern.

Execute the gcloud projects get-iam-policy command to get the current IAM policy for the project. In the following example, the JSON version of the policy is downloaded to a path on disk.

Command:

gcloud projects get-iam-policy project-id --format json > file-path

The JSON format of the IAM policy is downloaded:

{
  "bindings": [
    {
      "members": [
        "user:project-owner@example.com"
      ],
      "role": "roles/owner"
    },
    {
      "members": [
        "user:fatima@example.com"
      ],
      "role": "roles/bigquery.dataViewer",
      "condition": {
        "title": "Duration_3_months",
        "description": "Expires in 3 months on 2019-10-12",
        "expression":
          "request.time > timestamp(\"2019-07-12T07:00:00.000Z\") && request.time < timestamp(\"2019-10-12T07:00:00.000Z\")"
      }
    }
  ],
  "etag": "BwWKmjvelug=",
  "version": 3
}

In this example, we will update the title, description, and timestamp values in the expression to change the duration of the scheduled access condition. Update the following highlighted portion of the condition (replacing the values with your own):

{
  "bindings": [
    {
      "members": [
        "user:project-owner@example.com"
      ],
      "role": "roles/owner"
    },
    {
      "members": [
        "user:fatima@example.com"
      ],
      "role": "roles/bigquery.dataViewer",
      "condition": {
        "title": "Duration_5_months",
        "description": "Expires in 5 months on 2020-01-12",
        "expression":
          "request.time > timestamp('2019-07-12T07:00:00.000Z') && request.time < timestamp('2020-01-12T07:00:00.000Z')"
      }
    }
  ],
  "etag": "BwWKmjvelug=",
  "version": 3
}

Next, set the new policy by executing the gcloud projects set-iam-policy command.

gcloud projects set-iam-policy project-id file-path

The updated policy is applied, and fatima@example.com's role binding will expire at the new time.

REST

Use the read-modify-write pattern to modify the conditional role binding.

First, read the IAM policy for the project:

The Resource Manager API's projects.getIamPolicy method gets a project's IAM policy.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.

HTTP method and URL:

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:getIamPolicy

Request JSON body:

{
  "options": {
    "requestedPolicyVersion": 3
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "etag": "BwWKmjvelug=",
  "version": 3,
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:project-owner@example.com"
      ]
    },
    {
      "role": "roles/bigquery.dataViewer",
      "condition": {
        "title": "Duration_3_months",
        "description": "Expires in 3 months on 2019-10-12",
        "expression":
          "request.time > timestamp(\"2019-07-12T07:00:00.000Z\") && request.time < timestamp(\"2019-10-12T07:00:00.000Z\")"
      },
      "members": [
        "user:fatima@example.com"
      ]
    }
  ]
}

Next, modify the conditional role binding in the policy. In this example, we will update the timestamp values to change the duration of the scheduled access condition. Update the following highlighted portion of the condition expression (replacing the timestamp with your own):

{
  "etag": "BwWKmjvelug=",
  "version": 3,
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:project-owner@example.com"
      ]
    },
    {
      "role": "roles/bigquery.dataViewer",
      "condition": {
        "title": "Duration_5_months",
        "description": "Expires in 5 months on 2020-01-12",
        "expression":
          "request.time > timestamp('2019-07-12T07:00:00.000Z') && request.time < timestamp('2020-01-12T07:00:00.000Z')"
      },
      "members": [
        "user:fatima@example.com"
      ]
    }
  ]
}

Finally, write the updated policy:

The Resource Manager API's projects.setIamPolicy method sets the policy in the request as the project's new IAM policy.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.

HTTP method and URL:

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:setIamPolicy

Request JSON body:

{
  "policy": {
    "etag": "BwWKmjvelug=",
    "version": 3,
    "bindings": [
      {
        "role": "roles/owner",
        "members": [
          "user:project-owner@example.com"
        ]
      },
      {
        "role": "roles/bigquery.dataViewer",
        "condition": {
          "title": "Duration_5_months",
          "description": "Expires in 5 months on 2020-01-12",
          "expression":
            "request.time > timestamp('2019-07-12T07:00:00.000Z') && request.time < timestamp('2020-01-12T07:00:00.000Z')"
        },
        "members": [
          "user:fatima@example.com"
        ],
      }
    ]
  }
}

To send your request, expand one of these options:

The response contains the updated policy.


Removing a conditional role binding

When you remove the conditional role binding in an IAM policy, access to the resource is scoped to the role binding alone. This section shows you how to remove a time-based condition in a policy using the Cloud Console, the gcloud command-line tool, and the REST API.

To remove a condition from a role binding in a policy:

Console

  1. In the Cloud Console, go to the IAM page.

    Go to the IAM page

  2. From the list of members, locate the desired member and click the button.

  3. From the Edit permissions panel, locate the desired role binding. Then under Condition, click the name of an existing condition.

  4. In the Edit condition panel, click the button to remove the condition. You will be prompted to confirm deletion of the condition.

  5. Once the Edit condition panel is closed, click Save again from the Edit permissions panel to update your IAM policy.

gcloud

IAM policies are set using the read-modify-write pattern.

Execute the gcloud projects get-iam-policy command to get the current IAM policy for the project. In the following example, the JSON version of the policy is downloaded to a path on disk.

Command:

gcloud projects get-iam-policy project-id --format json > file-path

The JSON format of the IAM policy is downloaded:

{
  "bindings": [
    {
      "members": [
        "user:project-owner@example.com"
      ],
      "role": "roles/owner"
    },
    {
      "members": [
        "user:fatima@example.com"
      ],
      "role": "roles/bigquery.dataViewer",
      "condition": {
        "title": "Duration_3_months",
        "description": "Expires in 3 months on 2019-10-12",
        "expression":
          "request.time > timestamp(\"2019-07-12T07:00:00.000Z\") && request.time < timestamp(\"2019-10-12T07:00:00.000Z\")"
      }
    }
  ],
  "etag": "BwWKmjvelug=",
  "version": 3
}

To remove the conditional role binding from the policy, remove the condition block as shown below:

{
  "bindings": [
    {
      "members": [
        "user:project-owner@example.com"
      ],
      "role": "roles/owner"
    },
    {
      "members": [
        "user:fatima@example.com"
      ],
      "role": "roles/bigquery.dataViewer",
    }
  ],
  "etag": "BwWKmjvelug=",
  "version": 3
}

Note that the version is still set to 3, despite the fact that unconditional role bindings only require policy version 1. We recommend that you always use the highest policy version number when setting a policy, both for conditional role bindings and unconditional role bindings. See version requirements for more information. The gcloud tool updates the policy version number automatically.

Next, set the updated policy by executing the gcloud projects set-iam-policy command:

gcloud projects set-iam-policy project-id file-path

The updated policy is applied, removing the conditional role binding for fatima@example.com. The role binding will no longer expire.

REST

Use the read-modify-write pattern to remove the conditional role binding.

First, read the IAM policy for the project:

The Resource Manager API's projects.getIamPolicy method gets a project's IAM policy.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.

HTTP method and URL:

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:getIamPolicy

Request JSON body:

{
  "options": {
    "requestedPolicyVersion": 3
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "etag": "BwWKmjvelug=",
  "version": 3,
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:project-owner@example.com"
      ]
    },
    {
      "role": "roles/bigquery.dataViewer",
      "condition": {
        "title": "Duration_3_months",
        "description": "Expires in 3 months on 2019-10-12",
        "expression":
          "request.time > timestamp(\"2019-07-12T07:00:00.000Z\") && request.time < timestamp(\"2019-10-12T07:00:00.000Z\")"
      },
      "members": [
        "user:fatima@example.com"
      ]
    }
  ]
}

Next, modify the policy by removing the conditional role binding:

{
  "etag": "BwWKmjvelug=",
  "version": 3,
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:project-owner@example.com"
      ]
    },
    {
      "role": "roles/bigquery.dataViewer",
      "members": [
        "user:fatima@example.com"
      ]
    }
  ]
}

Note that the version is still set to 3, despite the fact that unconditional role bindings only require policy version 1. We recommend that you always use the highest policy version number when setting a policy, both for conditional role bindings and unconditional role bindings. See version requirements for more information.

Finally, write the updated policy:

The Resource Manager API's projects.setIamPolicy method sets the policy in the request as the project's new IAM policy.

Before using any of the request data below, make the following replacements:

  • project-id: Your Google Cloud project ID.

HTTP method and URL:

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:setIamPolicy

Request JSON body:

{
  "policy": {
    "etag": "BwWKmjvelug=",
    "version": 3,
    "bindings": [
      {
        "role": "roles/owner",
        "members": [
          "user:project-owner@example.com"
        ]
      },
      {
        "role": "roles/bigquery.dataViewer",
        "members": [
          "user:fatima@example.com"
        ]
      }
    ]
  }
}

To send your request, expand one of these options:

The response contains the updated policy.