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.
Service account credentials are currently available only for BigQuery data sources.
- 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.
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:
- Navigate to the Looker Studio service agent help page.
- 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.
Step 1: Create a new service account
-
From the Cloud console, go to the Create service account page.
Go to Create service account - Select a project.
-
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.
- Optional: Enter a description for the service account.
-
Click CREATE AND CONTINUE.
- 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.
- Click Continue.
- 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.
- 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
- Return to the Cloud console service accounts list.
- Select the Looker Studio service account that you just created by clicking it in the list.
- At the top, click PERMISSIONS.
- Click GRANT ACCESS.
- 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.
- 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. - Click SAVE.
service-account@<project_id>.iam.gserviceaccount.com
. If you know your project ID, you can construct the address manually.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.
- Navigate to the Cloud console service accounts list.
- Select your Looker Studio service account by clicking it in the list.
- At the top of the page, click PERMISSIONS.
- Click GRANT ACCESS.
- On the right, in Add principals and roles for <service account>, enter the email addresses of your users in the New principals box.
- Select the Service Account User role.
- 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.
To grant access to a table:
- Navigate to the Cloud console service accounts list.
- Copy the Looker Studio service account email address.
- Navigate to BigQuery and open a project.
- Expand a dataset by clicking .
- Select a table.
- In the toolbar, click SHARE.
- In the panel that opens on the right, click ADD PRINCIPAL.
- In the New principals box, paste the Looker Studio service account email address.
- Select the BigQuery Data Viewer role.
- Click SAVE.
To grant access to a dataset:
- Navigate to the Cloud console service accounts list.
- Copy your Looker Studio service account email address.
- Navigate to BigQuery, open a project, then locate the dataset.
- To the right of the dataset name, click View actions .
- Click Open.
- In the toolbar, click SHARING > Permissions.
- In the panel that opens on the right, click ADD PRINCIPAL.
- In the New principals box, paste the Looker Studio service account email address.
- Select the BigQuery Data Viewer role.
- Click SAVE.
Step 1: Create a new service account
Follow the general steps listed under gcloud in Creating and managing service accounts.
- Open the Cloud Shell.
- Select a project if necessary.
- 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"
- 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 accountbigquery.tables.getData
andbigquery.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:
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.
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 "[email protected]" with one or more valid email addresses (separate multiple entries with commas).
Example:
--member="user:[email protected]" \
--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.
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.
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:
- Create or edit a BigQuery data source.
- In the toolbar, click Data Credentials.
- Select Service Account Credentials.
- Enter your Service account email address in the box.
- 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
service-account-1@example-org-uk-example-project.iam.gserviceaccount.com
UK principals
Principals | Roles |
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 |
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 |
This is the service agent. |
Service Account Token Creator |
User 5 | Service Account User |
User 6 | Service Account User |
service-account-1@example-org-fr-example-project.iam.gserviceaccount.com
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.
Messages
|
CauseThe service agent hasn't been granted the Service Account Token Creator role (or another role that includes the |
SolutionGrant the Service Account Token Creator role to the service agent. |
MessageThis service account can't access the underlying data set. |
CauseThe service account hasn't been granted access to the project's data. |
SolutionAt a minimum, grant the BigQuery Data Viewer role to your service account on the underlying table, dataset, or project. |
MessageYou don’t have permission to use this service account. |
CauseThe user hasn't been added as a principal to the service account with the Service Account User role. |
SolutionGrant the Service Account User role to the user on the service account. |
Messages
|
CauseThe user is trying to access data controlled by a service account from a standard (consumer user) Google account. |
SolutionUse a Google Workspace or Cloud Identity account to access the data. |
MessageLooker Studio service agents can't be used to directly connect to data. Use a service account instead. |
SolutionService 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
Use Cloud shell
Example:
|
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.