Control access to resources with IAM

Console

1. Go to the BigQuerypage.

   Go to BigQuery

2. In the Explorerpane, expand your project and select a dataset to share.

3. Click person_add Sharing > Permissions.

4. Click person_add Add principal.

5. In the New principalsfield, enter a principal.

6. In the Select a rolelist, select a predefined role or a custom role.

7. Click Save.

8. To return to the dataset info, click Close.

SQL

To grant principals access to datasets, use the GRANT DCL statement :

1. In the Google Cloud console, go to the BigQuerypage.

   Go to BigQuery

2. In the query editor, enter the following statement:

    GRANT 
     
    ` ROLE_LIST 
   ` 
    ON 
     
    SCHEMA 
     
     RESOURCE_NAME 
    
    TO 
     
    " USER_LIST 
   " 
   

   Replace the following:

   • ROLE_LIST : a role or list of comma-separated roles that you want to grant
   • RESOURCE_NAME : the name of the dataset that you're granting access to

   • USER_LIST : a comma-separated list of users that the role is granted to

     For a list of valid formats, see user_list .

3. Click play_circle Run.

For more information about how to run queries, see Run an interactive query .

The following example grants the BigQuery Data Viewer role to myDataset :

  GRANT 
  
 `roles/bigquery.dataViewer` 
 ON 
  
 SCHEMA 
  
 `myProject` 
 . 
 myDataset 
 TO 
  
 "user:user@example.com" 
 , 
  
 "user:user2@example.com" 
 

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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

3. Make changes to the access section of the JSON file. You can add to any of the specialGroup entries: projectOwners , projectWriters , projectReaders , and allAuthenticatedUsers . You can also add any of the following: userByEmail , groupByEmail , and domain .

   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 
   " 
     
    } 
     
    ], 
     
    ... 
    } 
   

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

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

Terraform

Use the google_bigquery_dataset_iam resources to update access to a dataset.

Set the access policy for a dataset

The following example shows how to use the google_bigquery_dataset_iam_policy resource to set the IAM policy for the mydataset dataset. This replaces any existing policy already attached to the dataset:

 # This file sets the IAM policy for the dataset created by 
 # https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf. 
 # You must place it in the same local directory as that main.tf file, 
 # and you must have already applied that main.tf file to create 
 # the "default" dataset resource with a dataset_id of "mydataset". 
data  
 "google_iam_policy" 
  
 "iam_policy" 
  
 { 
  
binding  
 { 
  
 role 
  
 = 
  
 "roles/bigquery.admin" 
  
 members 
  
 = 
  
 [ 
  
 "user:user@example.com" 
,  
 ] 
  
 } 
  
binding  
 { 
  
 role 
  
 = 
  
 "roles/bigquery.dataOwner" 
  
 members 
  
 = 
  
 [ 
  
 "group:data.admin@example.com" 
,  
 ] 
  
 } 
  
binding  
 { 
  
 role 
  
 = 
  
 "roles/bigquery.dataEditor" 
  
 members 
  
 = 
  
 [ 
  
 "serviceAccount:bqcx-1234567891011-12a3@gcp-sa-bigquery-condel.iam.gserviceaccount.com" 
,  
 ] 
  
 } 
 } 
resource  
 "google_bigquery_dataset_iam_policy" 
  
 "dataset_iam_policy" 
  
 { 
  
 dataset_id 
  
 = 
  
google_bigquery_dataset.default.dataset_id  
 policy_data 
  
 = 
  
data.google_iam_policy.iam_policy.policy_data } 

Set role membership for a dataset

The following example shows how to use the google_bigquery_dataset_iam_binding resource to set membership in a given role for the mydataset dataset. This replaces any existing membership in that role. Other roles within the IAM policy for the dataset are preserved:

 # This file sets membership in an IAM role for the dataset created by 
 # https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf. 
 # You must place it in the same local directory as that main.tf file, 
 # and you must have already applied that main.tf file to create 
 # the "default" dataset resource with a dataset_id of "mydataset". 
resource  
 "google_bigquery_dataset_iam_binding" 
  
 "dataset_iam_binding" 
  
 { 
  
 dataset_id 
  
 = 
  
google_bigquery_dataset.default.dataset_id  
 role 
  
 = 
  
 "roles/bigquery.jobUser" 
  
 members 
  
 = 
  
 [ 
  
 "user:user@example.com" 
,  
 "group:group@example.com" 
  
 ] 
 } 

Set role membership for a single principal

The following example shows how to use the google_bigquery_dataset_iam_member resource to update the IAM policy for the mydataset dataset to grant a role to one principal. Updating this IAM policy does not affect access for any other principals that have been granted that role for the dataset.

 # This file adds a member to an IAM role for the dataset created by 
 # https://github.com/terraform-google-modules/terraform-docs-samples/blob/main/bigquery/bigquery_create_dataset/main.tf. 
 # You must place it in the same local directory as that main.tf file, 
 # and you must have already applied that main.tf file to create 
 # the "default" dataset resource with a dataset_id of "mydataset". 
resource  
 "google_bigquery_dataset_iam_member" 
  
 "dataset_iam_member" 
  
 { 
  
 dataset_id 
  
 = 
  
google_bigquery_dataset.default.dataset_id  
 role 
  
 = 
  
 "roles/bigquery.user" 
  
 member 
  
 = 
  
 "user:user@example.com" 
 } 

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

1. Launch Cloud Shell .

2. Set the default Google Cloud project where you want to apply your Terraform configurations.

   You only need to run this command once per project, and you can run it in any directory.

   export GOOGLE_CLOUD_PROJECT= PROJECT_ID 
   

   Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module ).

1. In Cloud Shell , create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf . In this tutorial, the file is referred to as main.tf .

   mkdir DIRECTORY 
   && cd DIRECTORY 
   && touch main.tf

2. If you are following a tutorial, you can copy the sample code in each section or step.

   Copy the sample code into the newly created main.tf .

   Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

3. Review and modify the sample parameters to apply to your environment.
4. Save your changes.
5. Initialize Terraform. You only need to do this once per directory.

   terraform init

   Optionally, to use the latest Google provider version, include the -upgrade option:

   terraform init -upgrade

Apply the changes

1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:

   terraform plan

   Make corrections to the configuration as necessary.

2. Apply the Terraform configuration by running the following command and entering yes at the prompt:

   terraform apply

   Wait until Terraform displays the "Apply complete!" message.

3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

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 .

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "cloud.google.com/go/bigquery" 
 ) 
 // grantAccessToDataset creates a new ACL conceding the READER role to the group "example-analyst-group@google.com" 
 // For more information on the types of ACLs available see: 
 // https://cloud.google.com/storage/docs/access-control/lists 
 func 
  
 grantAccessToDataset 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectID 
 , 
  
 datasetID 
  
 string 
 ) 
  
 error 
  
 { 
  
 // TODO(developer): uncomment and update the following lines: 
  
 // projectID := "my-project-id" 
  
 // datasetID := "mydataset" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 // Create BigQuery handler. 
  
 client 
 , 
  
 err 
  
 := 
  
 bigquery 
 . 
 NewClient 
 ( 
 ctx 
 , 
  
 projectID 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "bigquery.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 // Create dataset handler 
  
 dataset 
  
 := 
  
 client 
 . 
 Dataset 
 ( 
 datasetID 
 ) 
  
 // Get metadata 
  
 meta 
 , 
  
 err 
  
 := 
  
 dataset 
 . 
 Metadata 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "bigquery.Dataset.Metadata: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 // Find more details about BigQuery Entity Types here: 
  
 // https://pkg.go.dev/cloud.google.com/go/bigquery#EntityType 
  
 // 
  
 // Find more details about BigQuery Access Roles here: 
  
 // https://pkg.go.dev/cloud.google.com/go/bigquery#AccessRole 
  
 entityType 
  
 := 
  
 bigquery 
 . 
  GroupEmailEntity 
 
  
 entityID 
  
 := 
  
 "example-analyst-group@google.com" 
  
 roleType 
  
 := 
  
 bigquery 
 . 
  ReaderRole 
 
  
 // Append a new access control entry to the existing access list. 
  
 update 
  
 := 
  
 bigquery 
 . 
  DatasetMetadataToUpdate 
 
 { 
  
 Access 
 : 
  
 append 
 ( 
 meta 
 . 
 Access 
 , 
  
& bigquery 
 . 
  AccessEntry 
 
 { 
  
 Role 
 : 
  
 roleType 
 , 
  
 EntityType 
 : 
  
 entityType 
 , 
  
 Entity 
 : 
  
 entityID 
 , 
  
 }), 
  
 } 
  
 // Leverage the ETag for the update to assert there's been no modifications to the 
  
 // dataset since the metadata was originally read. 
  
 meta 
 , 
  
 err 
  
 = 
  
 dataset 
 . 
 Update 
 ( 
 ctx 
 , 
  
 update 
 , 
  
 meta 
 . 
 ETag 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 err 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Details for Access entries in dataset %v.\n" 
 , 
  
 datasetID 
 ) 
  
 for 
  
 _ 
 , 
  
 access 
  
 := 
  
 range 
  
 meta 
 . 
 Access 
  
 { 
  
 fmt 
 . 
 Fprintln 
 ( 
 w 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Role: %s\n" 
 , 
  
 access 
 . 
 Role 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Entities: %v\n" 
 , 
  
 access 
 . 
 Entity 
 ) 
  
 } 
  
 return 
  
 nil 
 }