Set up a Google Cloud service account for Looker Studio

Intended audience:

This article is intended for Google Cloud administrators. To learn how to use an existing service account in your Looker Studio data source, see Data credentials.

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. 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. Learn more about service accounts.

Note:

Service account credentials are currently available only for BigQuery data sources.

In this article:

• Benefits of using a service account with Looker Studio
• Before you begin
• Setup instructions
• Provide the Looker Studio service account(s) to your Looker Studio users
• Edit a data source that uses service account credentials
• See who is using the service account to access data
• Service account example scenario
• Errors
• Limits
• Related resources

Benefits of using a service account with Looker Studio

To use a service account with Looker Studio, you add your organization's Looker Studio service agent as a user (principal) on the account. This gives you control over which service accounts can be used with Looker Studio, while ensuring that the users in your organization can easily access the data they need.

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.

We recommend that you create new service accounts that are solely for use with Looker Studio. For example, you can create separate service accounts dedicated for marketing, sales, and engineering teams to use with Looker Studio.

Before you begin

• To set up a service account, you need to have 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 get the Looker Studio service agent, you must be a Workspace or Cloud Identity user.

Setup instructions

You only need to perform the instructions in this article once unless you want to create different service accounts for different teams or groups of users. To create multiple service accounts, repeat these instructions for each additional service account.

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 shown on that page.

Create a service account for Looker Studio

Instructions on creating a service account can be found in the Google Cloud IAM documentation. You can use either the Cloud console or the Cloud Shell command line to create the service account.

Use Cloud console

Step 1: Create a new service account

1. From the 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 Cloud console.

   The Cloud console generates a service account ID 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 step 2, Grant this service account access to project, 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 Step 3: Grant user roles below.
9. Click DONE to save the service account and return to the service accounts list page for your project.

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

1. Return to the Cloud console service accounts list.
2. Select the Looker Studio service account that you just created by clicking it in the list.
3. At the top, click PERMISSIONS.
4. Click GRANT ACCESS.
5. On the right, in Add principals to <project>, paste the Looker Studio service agent email (which you copied in step 1 above) into the New principals box.
6. Select a role that gives the service agent the iam.serviceAccount.getAccessToken permission. 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.

Tip: Your service agent's address uses the format service-account@<project_id>.iam.gserviceaccount.com. If you know your project ID, you can construct the address manually.

Step 3: Grant user roles

Note: This step is optional if you already added Looker Studio users while creating the service account, as described in step 1 above.

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.

Tip: If you're not ready to complete this step, you can come back to it later.

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

Note: Users who will only view Looker Studio reports don't need to have permissions on the service account.

1. Navigate to the Cloud console service accounts list.
2. Select your Looker Studio service account by clicking it in the list.
3. At the top of the page, click PERMISSIONS.
4. Click GRANT ACCESS.
5. On the right, 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.

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

Note: We don't recommend granting service account access at the project level.

To grant access to a table:

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

To grant access to a dataset:

1. Navigate to the Cloud console service accounts list.
2. Copy your Looker Studio service account email address.
3. Navigate to BigQuery, open a project, then locate the dataset.
4. To the right of the dataset name, click View actions .
5. Click Open.
6. In the toolbar, click SHARING > Permissions.
7. In the panel that opens on the right, click ADD PRINCIPAL.
8. In the New principals box, paste the Looker Studio service account email address.
9. Select the BigQuery Data Viewer role.
10. Click SAVE.

Use Cloud Shell

Step 1: Create a new service account

Follow the general steps listed under gcloud 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 you choose.

   
   Example:

   gcloud iam service-accounts create datastudio_service_account \
--description="Use for Looker Studio access to BigQuery" \
--display-name="DS_BQ"

4. To access BigQuery data on the Google Cloud project 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 data set 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:
   gcloud projects add-iam-policy-binding PROJECT_ID \
--member = "serviceAccount:datastudio_sa@PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/bigquery.jobUser"

    

   gcloud projects add-iam-policy-binding PROJECT_ID \

   --member = "serviceAccount:datastudio_sa@PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/bigquery.dataViewer"

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

To allow the Looker Studio service agent to access data via the service account, grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to the service agent. To do this, 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 \ datastudio_service_account@PROJECT_ID.iam.gserviceaccount.com \ --member="[e-mail]" \ --role="roles/iam.serviceAccountTokenCreator"

Step 3: 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.

If you're not ready to complete this step, you can come back to it later.

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

Note: Users who will only view Looker Studio reports don't need to have permissions on the service account.

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 "[e-mail]" with one or more valid email addresses (separate multiple entries with commas).

Example:

gcloud iam service-accounts add-iam-policy-binding \ datastudio_service_account@PROJECT_ID.iam.gserviceaccount.com \
--member="user:[e-mail]" \
--role="roles/iam.serviceAccountUser"

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

It's easiest to do this using the Cloud console instructions, Step 4 above. To grant access to data using the bq command line tool, see Controlling access to datasets.

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 creating 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 via your organization's documentation, internal website, or email.

Note: You don't need to manage service account keys manually, nor do users need to download service account keys from Cloud console and upload them to Looker Studio. The limit of 10 service account keys per service account does not apply to Looker Studio.

Important: Simply knowing the service agent name does not allow a user to access data. The service agent needs to be added to a service account, and end users need to have permission to act as that service account.

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 their credentials instead.

See who is using the service account to access data

You can check the audit logs for service accounts in the 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 only have access 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 your service agent and any users you want to be able to create data sources that use the service account as principals, given each the proper roles.

UK service account

[e-mail]

UK principals

Principals	Roles
[e-mail] This is the service agent.	Service Account Token Creator
User 1	Service Account User
User 2	Service Account User

France service account

[e-mail]

France principals

Principals	Roles
[e-mail] This is the service agent.	Service Account Token Creator
User 3	Service Account User
User 4	Service Account User

Germany service account

[e-mail]

Germany principals

Principals	Roles
[e-mail] This is the service agent.	Service Account Token Creator
User 5	Service Account User
User 6	Service Account User

Tip: The service account name is not sensitive information: Even if User 5 knows that [e-mail] exists, they can't use it because they don't have the right permissions. The service agent needs to be added to a service account for it to function. (The service agent is just how Looker Studio makes use of the service account.)

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.serviceAccount.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.serviceAccount.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 data set.

Cause The service account hasn't been granted access to the project's data.

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 only available for Google Workspace or Cloud Identity managed organizations. Please use a different account to use this feature.

Cause The user is trying to access data controlled by a service account from a standard (consumer user) Google 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 the Cloud console: Use Cloud console Navigate to the Google Cloud Platform > IAM & Admin > Service accounts page. Select a project, if necessary. In the Service accounts for project page, locate the service account that Looker Studio will use to access your BigQuery data. Copy the email address for that account. Use Cloud shell Open the Cloud shell. Select a project, if necessary. 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 currently only available 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.

Related resources

• Understanding service accounts
• Connect to BigQuery: Support for VPC Service Controls
• Launching Cloud Shell