Control access to resources with IAM
This document describes how to view the current access policy of a resource, how to grant access to a resource, and how to revoke access to a resource.
This document assumes familiarity with the Identity and Access Management (IAM) system in Google Cloud.
Required roles
To get the permissions that you need to modify IAM policies for resources,
ask your administrator to grant you the
BigQuery Data Owner (roles/bigquery.dataOwner
) IAM role on the project.
For more information about granting roles, see
Manage access.
This predefined role contains the permissions required to modify IAM policies for resources. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
-
To get a dataset's access policy:
bigquery.datasets.get
-
To set a dataset's access policy:
bigquery.datasets.update
-
To get a dataset's access policy (Google Cloud console only):
bigquery.datasets.getIamPolicy
-
To set a dataset's access policy (console only):
bigquery.datasets.setIamPolicy
-
To get a table or view's policy:
bigquery.tables.getIamPolicy
-
To set a table or view's policy:
bigquery.tables.setIamPolicy
-
To create
bq
tool or SQL BigQuery jobs (optional):bigquery.jobs.create
You might also be able to get these permissions with custom roles or other predefined roles.
View the access policy of a resource
The following sections describe how to view the access policies of different resources.
View the access policy of a dataset
Select one of the following options:
Console
Go to the BigQuery page.
In the Explorer pane, expand your project and select a dataset.
Click > Permissions.
SharingThe dataset access policies appear in the Dataset Permissions pane.
bq
To get an existing policy and output it to a local file in JSON, use the
bq show
command
in Cloud Shell:
bq show \ --format=prettyjson \ PROJECT_ID:DATASET > PATH_TO_FILE
Replace the following:
- PROJECT_ID: your project ID
- DATASET: the name of your dataset
- PATH_TO_FILE: the path to the JSON file on your local machine
API
To apply access controls when the dataset is created, call
datasets.insert
with a defined
dataset resource
.
To update your access controls, call
datasets.patch
and use the access
property in the Dataset
resource.
Because the datasets.update
method replaces the entire
dataset resource, datasets.patch
is the preferred method for updating
access controls.
View the access policy of a table or view
Select one of the following options:
Console
Go to the BigQuery page.
In the Explorer pane, expand your project and select a table or view.
Click
Share.The table or view access policies appear in the Share pane.
bq
To get an existing access policy and output it to a local file in JSON, use the
bq get-iam-policy
command
in Cloud Shell:
bq get-iam-policy \ --table=true \ PROJECT_ID:DATASET.RESOURCE > PATH_TO_FILE
Replace the following:
- PROJECT_ID: your project ID
- DATASET: the name of your dataset
- RESOURCE: the name of the table or view whose policy you want to view
- PATH_TO_FILE: the path to the JSON file on your local machine
API
To retrieve the current policy, call the
tables.getIamPolicy
method.
Grant access to a resource
The following sections describe how to grant access to different resources.
Grant access to a dataset
Select one of the following options:
Console
Go to the BigQuery page.
In the Explorer pane, expand your project and select a dataset to share.
Click > Permissions.
SharingClick
Add principal.In the New principals field, enter a principal.
In the Select a role list, select a predefined role or a custom role.
Click Save.
To return to the dataset info, click Close.
SQL
To grant principals access to datasets, use the
GRANT
DCL statement:
In the Google Cloud console, go to the BigQuery page.
In the query editor, enter the following statement:
GRANT ROLE_LIST ON RESOURCE_TYPE RESOURCE_NAME TO "USER_LIST"
Replace the following:
ROLE_LIST
: a role or list of comma-separated roles that you want to grantRESOURCE_TYPE
: the type of resource that the role is applied toSupported values include
SCHEMA
(equivalent to dataset),TABLE
,VIEW
, andEXTERNAL TABLE
.RESOURCE_NAME
: the name of the resource that you want to grant the permission onUSER_LIST
: a comma-separated list of users that the role is granted toFor a list of valid formats, see
user_list
.
Click
Run.
For more information about how to run queries, see Running interactive queries.
bq
To write the existing dataset information (including access controls) to a JSON file, use the
bq show
command:bq show \ --format=prettyjson \ PROJECT_ID:DATASET > PATH_TO_FILE
Replace the following:
- PROJECT_ID: your project ID
- DATASET: the name of your dataset
- PATH_TO_FILE: the path to the JSON file on your local machine
Make changes to the
access
section of the JSON file. You can add to any of thespecialGroup
entries:projectOwners
,projectWriters
,projectReaders
, andallAuthenticatedUsers
. You can also add any of the following:userByEmail
,groupByEmail
, anddomain
.For example, the
access
section of a dataset's JSON file would look like the following:{ "access": [ { "role": "READER", "specialGroup": "projectReaders" }, { "role": "WRITER", "specialGroup": "projectWriters" }, { "role": "OWNER", "specialGroup": "projectOwners" }, { "role": "READER", "specialGroup": "allAuthenticatedUsers" }, { "role": "READER", "domain": "domain_name" }, { "role": "WRITER", "userByEmail": "user_email" }, { "role": "READER", "groupByEmail": "group_email" } ], ... }
When your edits are complete, use the
bq update
command and include the JSON file using the--source
flag. If the dataset is in a project other than your default project, add the project ID to the dataset name in the following format:PROJECT_ID:DATASET
.bq update \ --source PATH_TO_FILE \ PROJECT_ID:DATASET
To verify your access control changes, use the
bq show
command again without writing the information to a file:bq show --format=prettyjson PROJECT_ID:DATASET
API
To apply access controls when the dataset is created, call the
datasets.insert
method
with a defined
dataset resource.
To update your access controls, call the
datasets.patch
method and use
the access
property in the Dataset
resource.
Because the datasets.update
method replaces the entire dataset resource,
datasets.patch
is the preferred method for updating access controls.
Go
Before trying this sample, follow the Go setup instructions in the
BigQuery quickstart using
client libraries.
For more information, see the
BigQuery Go API
reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the
BigQuery quickstart using
client libraries.
For more information, see the
BigQuery Java API
reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the
BigQuery quickstart using
client libraries.
For more information, see the
BigQuery Python API
reference documentation.
dataset.access_entries
property
with the access controls for a dataset. Then call the
client.update_dataset()
function to update the property.
Grant access to a table or view
Select one of the following options:
Console
Go to the BigQuery page.
In the Explorer pane, expand your project and select a table or view to share.
Click
Share.Click
Add principal.In the New principals field, enter a principal.
In the Select a role list, select a predefined role or a custom role.
Click Save.
To return to the table or view details, click Close.
SQL
To grant principals access to tables or views, use the
GRANT
DCL statement:
In the Google Cloud console, go to the BigQuery page.
In the query editor, enter the following statement:
GRANT ROLE_LIST ON RESOURCE_TYPE RESOURCE_NAME TO "USER_LIST"
Replace the following:
ROLE_LIST
: a role or list of comma-separated roles that you want to grantRESOURCE_TYPE
: the type of resource that the role is applied toSupported values include
SCHEMA
(equivalent to dataset),TABLE
,VIEW
, andEXTERNAL TABLE
.RESOURCE_NAME
: the name of the resource that you want to grant the permission onUSER_LIST
: a comma-separated list of users that the role is granted toFor a list of valid formats, see
user_list
.
Click
Run.
For more information about how to run queries, see Running interactive queries.
bq
To write the existing table or view information (including access controls) to a JSON file, use the
bq get-iam-policy
command:bq get-iam-policy \ PROJECT_ID:DATASET.TABLE_OR_VIEW \ > PATH_TO_FILE
Replace the following:
- PROJECT_ID: your project ID
- DATASET: the name of the dataset that contains the table or view that you want to update
- TABLE_OR_VIEW: the name of the resource to update
- PATH_TO_FILE: the path to the JSON file on your local machine
Make changes to the
access
section of the JSON file. You can add to any of thespecialGroup
entries:projectOwners
,projectWriters
,projectReaders
, andallAuthenticatedUsers
. You can also add any of the following:userByEmail
,groupByEmail
, anddomain
. For example, theaccess
section of a table or view's JSON file would look like the following:{ "access": [ { "role": "READER", "specialGroup": "projectReaders" }, { "role": "WRITER", "specialGroup": "projectWriters" }, { "role": "OWNER", "specialGroup": "projectOwners" }, { "role": "READER", "specialGroup": "allAuthenticatedUsers" }, { "role": "READER", "domain": "domain_name" }, { "role": "WRITER", "userByEmail": "user_email" }, { "role": "READER", "groupByEmail": "group_email" } ], ... }
Use the
set-iam-policy
command to update the policy:bq set-iam-policy \ PROJECT_ID:DATASET.TABLE_OR_VIEW \ > PATH_TO_FILE
To verify your access control changes, use the
bq get-iam-policy
command again without writing the information to a file:bq get-iam-policy --format=prettyjson \ PROJECT_ID:DATASET.TABLE_OR_VIEW
API
- To retrieve the current policy, call the
tables.getIamPolicy
method. Edit the policy to add members and/or bindings. For the format required for the policy, see the Policy reference topic.
Java
Before trying this sample, follow the Java setup instructions in the
BigQuery quickstart using
client libraries.
For more information, see the
BigQuery Java API
reference documentation.
Revoke access to a resource
The following sections describe how to revoke access to different resources.
Revoke access to a dataset
Select one of the following options:
Console
Go to the BigQuery page.
In the Explorer panel, expand your project and select a dataset.
In the details panel, click Sharing > Permissions.
In the Dataset Permissions dialog, expand the principal whose access you want to revoke.
Click
Remove principal.In the Remove role from principal? dialog, click Remove.
To return to dataset details, click Close.
SQL
To remove access to datasets from principals, use the
REVOKE
DCL statement:
In the Google Cloud console, go to the BigQuery page.
In the query editor, enter the following statement:
REVOKE ROLE_LIST ON RESOURCE_TYPE RESOURCE_NAME TO "USER_LIST"
Replace the following:
ROLE_LIST
: a role or list of comma-separated roles that you want to revokeRESOURCE_TYPE
: the type of resource that the role is revoked fromSupported values include
SCHEMA
(equivalent to dataset),TABLE
,VIEW
, andEXTERNAL TABLE
.RESOURCE_NAME
: the name of the resource that you want to revoke permission onUSER_LIST
: a comma-separated list of users who will have their roles revokedFor a list of valid formats, see
user_list
.
Click
Run.
For more information about how to run queries, see Running interactive queries.
bq
To write the existing dataset information (including access controls) to a JSON file, use the
bq show
command:bq show \ --format=prettyjson \ PROJECT_ID:DATASET > PATH_TO_FILE
Replace the following:
- PROJECT_ID: your project ID
- DATASET: the name of your dataset
- PATH_TO_FILE: the path to the JSON file on your local machine
Make changes to the
access
section of the JSON file. You can remove any of thespecialGroup
entries:projectOwners
,projectWriters
,projectReaders
, andallAuthenticatedUsers
. You can also remove any of the following:userByEmail
,groupByEmail
, anddomain
.For example, the
access
section of a dataset's JSON file would look like the following:{ "access": [ { "role": "READER", "specialGroup": "projectReaders" }, { "role": "WRITER", "specialGroup": "projectWriters" }, { "role": "OWNER", "specialGroup": "projectOwners" }, { "role": "READER", "specialGroup": "allAuthenticatedUsers" }, { "role": "READER", "domain": "domain_name" }, { "role": "WRITER", "userByEmail": "user_email" }, { "role": "READER", "groupByEmail": "group_email" } ], ... }
When your edits are complete, use the
bq update
command and include the JSON file using the--source
flag. If the dataset is in a project other than your default project, add the project ID to the dataset name in the following format:PROJECT_ID:DATASET
.bq update \ --source PATH_TO_FILE \ PROJECT_ID:DATASET
To verify your access control changes, use the
show
command again without writing the information to a file:bq show --format=prettyjson PROJECT_ID:DATASET
API
Call datasets.patch
and
use the access
property in the Dataset
resource to update your access controls.
Because the datasets.update
method replaces the entire dataset resource,
datasets.patch
is the preferred method for updating access controls.
Go
Before trying this sample, follow the Go setup instructions in the
BigQuery quickstart using
client libraries.
For more information, see the
BigQuery Go API
reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the
BigQuery quickstart using
client libraries.
For more information, see the
BigQuery Python API
reference documentation.
dataset.access_entries
property with the access controls for a dataset. Then call the
client.update_dataset()
function to update the property.
Revoke access to a table or view
Select one of the following options:
Console
Go to the BigQuery page.
In the Explorer panel, expand your project and select a table or view.
In the details panel, click Share.
In the Share dialog, expand the principal whose access you want to revoke.
Click
Delete.In the Remove role from principal? dialog, click Remove.
To return to the table or view details, click Close.
SQL
To remove access to tables or views from principals, use the
REVOKE
DCL statement:
In the Google Cloud console, go to the BigQuery page.
In the query editor, enter the following statement:
REVOKE ROLE_LIST ON RESOURCE_TYPE RESOURCE_NAME TO "USER_LIST"
Replace the following:
ROLE_LIST
: a role or list of comma-separated roles that you want to revokeRESOURCE_TYPE
: the type of resource that the role is revoked fromSupported values include
SCHEMA
(equivalent to dataset),TABLE
,VIEW
, andEXTERNAL TABLE
.RESOURCE_NAME
: the name of the resource that you want to revoke permission onUSER_LIST
: a comma-separated list of users who will have their roles revokedFor a list of valid formats, see
user_list
.
Click
Run.
For more information about how to run queries, see Running interactive queries.
bq
To write the existing table or view information (including access controls) to a JSON file, use the
bq get-iam-policy
command:bq get-iam-policy \ PROJECT_ID:DATASET.TABLE_OR_VIEW \ > PATH_TO_FILE
Replace the following:
- PROJECT_ID: your project ID
- DATASET: the name of the dataset that contains the table or view that you want to update
- TABLE_OR_VIEW: the name of the resource to update
PATH_TO_FILE: the path to the JSON file on your local machine
Make changes to the
access
section of the JSON file. You can remove any of thespecialGroup
entries:projectOwners
,projectWriters
,projectReaders
, andallAuthenticatedUsers
. You can also remove any of the following:userByEmail
,groupByEmail
, anddomain
. For example, theaccess
section of a table or view's JSON file would look like the following:{ "access": [ { "role": "READER", "specialGroup": "projectReaders" }, { "role": "WRITER", "specialGroup": "projectWriters" }, { "role": "OWNER", "specialGroup": "projectOwners" }, { "role": "READER", "specialGroup": "allAuthenticatedUsers" }, { "role": "READER", "domain": "domain_name" }, { "role": "WRITER", "userByEmail": "user_email" }, { "role": "READER", "groupByEmail": "group_email" } ], ... }
Use
bq set-iam-policy
command to update the policy:bq set-iam-policy \ PROJECT_ID:DATASET.TABLE_OR_VIEW \ > PATH_TO_FILE
To verify your access control changes, use the
get-iam-policy
command again without writing the information to a file:bq get-iam-policy --format=prettyjson \ PROJECT_ID:DATASET.TABLE_OR_VIEW
API
- To retrieve the current policy, call the
tables.getIamPolicy
method. Edit the policy to remove members and/or bindings. For the format required for the policy, see the Policy reference topic.
Call
tables.setIamPolicy
to write the updated policy. Note: Empty bindings with no members are not allowed and result in an error.
Java
Before trying this sample, follow the Java setup instructions in the
BigQuery quickstart using
client libraries.
For more information, see the
BigQuery Java API
reference documentation.