Set up a Google Cloud service account for Looker Studio

A service account is a special type of Google Account that is intended to represent a non-human user that can authenticate and be authorized to access data in Google APIs and products. Instead of delegating access using Owner's credentials, or requiring individual report viewers to have access to the data using viewer's credentials, Looker Studio can use a service account to access data.

Note: Service account credentials are available only for BigQuery data sources.

Learn more about service accounts.

Benefits of using a service account with Looker Studio

Using a service account instead of an individual user's credentials provides these benefits:

  • Data sources using service account credentials won't break if the creator leaves your company.
  • Service account credentials support access to data located behind VPC Service Controls perimeters that use device policies.
  • Automated features like scheduled email and scheduled data extracts work with data sources that are behind a VPC Service Controls perimeter. (See the Limits section for an important caveat.)
  • You can create ingress and egress rules to allow the service account access to and from the resources and clients protected by service perimeters.

Required roles

  • To get the Looker Studio service agent, you must be a Google Workspace or Cloud Identity user.
  • To set up a service account, you need to have the Service Account Admin (roles/iam.serviceAccountAdmin) or Create Service Accounts (roles/iam.serviceAccountCreator) role on your Google Cloud project. Learn more about service account roles.
  • To configure the service account to access a BigQuery table or dataset, you must have the BigQuery Data Owner (roles/bigquery.dataOwner) role on the table or dataset, or another role that gives you the bigquery.datasets.setIamPolicy permission.

Setup instructions

To set up a service account that provides access to BigQuery data, follow these steps:

  1. Get the Looker Studio service agent. In this step, you'll copy the service agent email address so that you can use it in the next step. This address is created for you automatically by Looker Studio.
  2. Create a service account for Looker Studio. In this step, you'll create the non-human user that will access the data.
  3. Allow the Looker Studio service agent to access your service account. In this step, you'll grant the service agent the required role on the service account.
  4. Grant user roles. In this step, you'll grant your users the required role so that they can create data sources that use service account credentials.
  5. Enable the service account to access your BigQuery data. In this step, you'll grant the service account the required role so that it can access a BigQuery table or dataset.

Step 1: Get the Looker Studio service agent

To allow the service account to access your data, you'll need to provide the Looker Studio service agent for your organization. You can get the service agent from a help page in Looker Studio:

  1. Navigate to the Looker Studio service agent help page.
  2. Copy the service agent email address that's shown on that page.

Step 2: Create a service account for Looker Studio

See the Google Cloud IAM documentation for instructions on creating a service account. You can use either the Google Cloud console or the Cloud Shell command line to create the service account.

Console

  1. From the Google Cloud console, go to the Create service account page.

    Go to Create service account

  2. Select a project.
  3. Enter a service account name to display in the Google Cloud console.

    The Google Cloud console generates a service account ID that's based on this name. Edit the ID now if necessary. You can't change the ID later.

  4. Optional: Enter a description for the service account.
  5. Click CREATE AND CONTINUE.
  6. In Permissions, grant the service account the BigQuery Job User IAM role in the project that contains the data to which you want to connect in Looker Studio. Note that this might be different from the project in which you created the service account.
  7. Click Continue.
  8. In the Service account users role field, add the users who can use this service account to provide credentials for their data sources. If you're not ready to add users now, you can do so later by following the directions in Grant user roles.
  9. Click DONE to save the service account and return to the service accounts list page for your project.

gcloud

Follow the general steps that are listed under Cloud Shell in Creating and managing service accounts.

  1. Open the Cloud Shell.
  2. Select a project, if necessary.
  3. To create the service account, run the gcloud iam service-accounts create command. You can use whatever account name, description, and display name that you choose.

Example:

gcloud iam service-accounts create looker-studio-service-account \
--description="Use for Looker Studio access to BigQuery"  \
--display-name="LS_BQ"

  1. To access BigQuery data on the Google Cloud project that you want to use with Looker Studio, give the service account the bigquery.jobs.create permission in that project. You can grant the BigQuery Job User IAM role to give this permission.

    In addition, give the service account bigquery.tables.getData and bigquery.tables.get permissions on the project or dataset that you want to use with Looker Studio. You can grant the BigQuery Data Viewer role (roles/bigquery.dataViewer) to give these permissions.

    To grant these roles, run the gcloud projects add-iam-policy-binding command. In the following examples, replace PROJECT_ID with your project ID.

    Example: Grant the BigQuery Job User role

    gcloud projects add-iam-policy-binding PROJECT_ID\
--member ="serviceAccount:looker-studio-service-account@PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/bigquery.jobUser"

    Example: Grant the BigQuery Data Viewer role

    gcloud projects add-iam-policy-bindingPROJECT_ID\
--member ="serviceAccount:looker-studio-service-account@PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/bigquery.dataViewer"

Step 3: Allow the Looker Studio service agent to access your service account

To allow the Looker Studio service agent to access data by using the service account, grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to the service agent.

Console

  1. Return to the Google Cloud console service accounts list.
  2. Select the Looker Studio service account that you just created by clicking it in the list.
  3. Click Principals with access.
  4. Click person_add GRANT ACCESS.
  5. In Add principals to PROJECT_ID, paste the Looker Studio service agent email (which you copied in step 1 previously) into the New principals box. (Your service agent's address looks like this: SERVICE_AGENT_NAME@PROJECT_ID.iam.gserviceaccount.com.)
  6. Select a role that gives the service agent the iam.serviceAccounts.getAccessTokenpermission. For example, you can use the Service Account Token Creator role, but you can also use any custom role that grants this permission.
  7. Click SAVE.

gcloud

Run the gcloud iam service-accounts add-iam-policy-binding command. In the following example, replace ORG_ID with your organization's ID.

Example:

gcloud iam service-accounts add-iam-policy-binding looker-studio-service-account@PROJECT_ID.iam.gserviceaccount.com \
--member="service-ORG_ID@gcp-sa-datastudio.iam.gserviceaccount.com" \
--role="roles/iam.serviceAccountTokenCreator"

Step 4: Grant user roles

Looker Studio users who will create or edit data sources need to be granted a role that includes the iam.serviceAccounts.actAs permission, such as the Service Account User role (roles/iam.serviceAccountUser). You can grant this role on the project or on an individual service account, but we recommend that you grant the role on the service account only. For instructions, see Managing service account impersonation.

We recommend that you not grant non-service agent users the Service Account Token Creator role — it is not needed for Looker Studio.

Console

  1. Navigate to the Console service accounts list.
  2. Select your Looker Studio service account by clicking it in the list.
  3. Click the Principals with access.
  4. Click person_add GRANT ACCESS.
  5. In Add principals and roles for Service Account, enter the email addresses of your users in the New principals box.
  6. Select the Service Account User role.
  7. Click SAVE.

gcloud

To grant the Service Account User role, run the gcloud projects add-iam-policy-binding command. In the following examples, replace PROJECT_ID with your project ID, and replace USER_EMAIL with one or more valid email addresses (separate multiple entries with commas).

Example:

gcloud iam service-accounts add-iam-policy-binding  looker-studio-service-account@PROJECT_ID.iam.gserviceaccount.com  \
--member="user:USER_EMAIL" \
--role="roles/iam.serviceAccountUser"

Step 5: Enable the service account to access your BigQuery data

To allow Looker Studio to access your data, grant the BigQuery Data Viewer role to the service account at the table or dataset level. We don't recommend granting service account access at the project level.

Console

To grant access to a table:

  1. Copy the Looker Studio service agent email address, as described previously in Step 1. Get the Looker Studio service agent.
  2. Navigate to the Google Cloud console service accounts list.
  3. Navigate to BigQuery and open a project.
  4. Expand a dataset by clicking the expand arrow .
  5. Select a table.
  6. In the toolbar, click person_add SHARE.
  7. In the panel that opens on the right, click person_add ADD PRINCIPAL.
  8. In the New principals box, paste the Looker Studio service agent email address.
  9. Select the BigQuery Data Viewer role.
  10. Click SAVE.

To grant access to a dataset:

  1. Copy the Looker Studio service agent email address, as described previously in Step 1. Get the Looker Studio service agent.
  2. Navigate to the Google Cloud console service accounts list.
  3. Navigate to BigQuery, open a project, and then locate the dataset.
  4. Click the options menu .
  5. Click Open.
  6. In the toolbar, click person_add Sharing permissions.
  7. In the panel that opens on the right, click person_add ADD PRINCIPAL.
  8. In the New principals box, paste the Looker Studio service agent email address.
  9. Select the BigQuery Data Viewer role.
  10. Click SAVE.

gcloud

We recommend using the Google Cloud console instructions to grant access to data. To grant access to data using the bq command line tool, see Controlling access to datasets in the BigQuery documentation.

Provide the Looker Studio service account(s) to your Looker Studio users

Looker Studio users will need to know which service account to use when they create data sources. As there is no way to see the list of available service accounts from within Looker Studio, you should make this information available using your organization's documentation, internal website, or email.

Create a data source that uses service account credentials

To create data sources that use service account credentials, Looker Studio users can follow the same basic steps as for other data credential types:

  1. Create or edit a BigQuery data source.
  2. In the toolbar, click Data Credentials.
  3. Select Service Account Credentials.
  4. Enter your Service account email address in the box.
  5. Click Update.

Edit a data source that uses service account credentials

When someone edits a data source that uses service account credentials, Looker Studio checks to see if they have permission to use the service account. If they don't, the data source switches to use that person's credentials instead.

See who is using the service account to access data

You can check the audit logs for service accounts in the Google Cloud console. You must enable IAM audit logs for Data Access activity if you want to receive audit logs for service accounts.

Service account example scenario

Suppose you want to make sure that Looker Studio users in your company have access only to the data for their country's subsidiary. A solution is to create a service account for each country, and only give Looker Studio users in that country permission to act as the service account.

Example setup

In this example, you'll create three service accounts: one for the UK, one for France, and one for Germany. You'll then assign as principals your service agent and any users whom you want to be able to create data sources that use the service account. You'll also assign the proper roles to each.

UK service account

service-account-1@example-org-uk-example-project.iam.gserviceaccount.com

UK principals

Principals Roles

service-org-12345@gcp-sa-datastudio.iam.gserviceaccount.com

This is the service agent.

 Service Account Token Creator
User 1 Service Account User
User 2 Service Account User

France service account

service-account-1@example-org-fr-example-project.iam.gserviceaccount.com

France principals

Principals Roles

service-org-12345@gcp-sa-datastudio.iam.gserviceaccount.com

This is the service agent.

 Service Account Token Creator
User 3 Service Account User
User 4 Service Account User

Germany service account

service-account-1@example-org-de-example-project.iam.gserviceaccount.com

Germany principals

Principals Roles

service-org-12345@gcp-sa-datastudio.iam.gserviceaccount.com

This is the service agent.

 Service Account Token Creator
User 5 Service Account User
User 6 Service Account User

Errors

This section explains the errors that Looker Studio data source creators and report viewers might see when they try to use a service account. In most cases, these errors have the same root cause: incorrect or incomplete setup of the service account.

Missing service agent role

Messages

  • Looker Studio's service agent is missing iam.serviceAccounts.getAccessToken permission for this service.
  • The service agent used by this data source's service account is missing the "Service Account Token Creator" role.

Cause

The service agent hasn't been granted the Service Account Token Creator role (or another role that includes the iam.serviceAccounts.getAccessToken permission).

Solution

Grant the Service Account Token Creator role to the service agent.

No access to the data

Message

This service account can't access the underlying dataset.

Causes

  • The service account hasn't been granted access to the project's data.
  • The billing project is connected to a project that the service account doesn't have access to.

Solution

At a minimum, grant the BigQuery Data Viewer role to your service account on the underlying table, dataset, or project.

Missing user role

Message

You don't have permission to use this service account.

Cause

The user hasn't been added as a principal to the service account with the Service Account User role.

Solution

Grant the Service Account User role to the user on the service account.

Service agent not available for the account

Messages

  • Service agents cannot be generated for this account — try again with a Google Workspace or Cloud Identity managed account.
  • Service agent credentials are available only for Google Workspace or Cloud Identity managed organizations. Please use a different account to use this feature.

Cause

The user is trying to use a standard (consumer user) Google Account to access data that's controlled by a service account.

Solution

Use a Google Workspace or Cloud Identity account to access the data.

Can't use service agent in credentials dialog

Message

Looker Studio service agents can't be used to directly connect to data. Use a service account instead.

Solution

Service agents and service accounts are different. Enter a service account in the credentials dialog. You can find the list of available service accounts using either the Google Cloud console or the Cloud Shell:

Console

  1. Navigate to the Google Cloud Platform > IAM & Admin > Service accounts page.
  2. Select a project, if necessary.
  3. In the Service accounts for project page, locate the service account that Looker Studio will use to access your BigQuery data.
  4. Copy the email address for that account.

gcloud

  1. Open the Cloud Shell.
  2. Select a project, if necessary.
  3. To list the service accounts to which you have access, run the gcloud iam service-accounts list command.

Example:

gcloud iam service-accounts list

Limits

  • Service account credentials are available only for BigQuery data sources. IAM limits apply to service accounts.
  • It might take a few minutes for changes to service account permissions to be reflected in Looker Studio.
  • Scheduled email delivery doesn't work with data that is protected using IP-based access levels with VPC Service Controls. (This is because Looker Studio doesn't pass the email recipient's IP address when the recipient views the report.)