Google OAuth is used in conjunction with Identity and Access Management (IAM) to authenticate Looker (Google Cloud core) users.
When using OAuth for authentication, Looker (Google Cloud core) authenticates users through the OAuth 2.0 protocol. You can use any OAuth 2.0 client. As an example, this page walks you through the steps to set up authentication for a Looker (Google Cloud core) instance by using the Google Cloud console to create OAuth credentials.
If another method is the primary form of authentication, Google OAuth is by default the backup authentication method.
When used with OAuth, Looker (Google Cloud core) IAM roles provide the following levels of authentication and authorization for all Looker (Google Cloud core) instances within a given Google Cloud project. Assign one of the following IAM roles to each of your principals, depending on the levels of access that you want them to have:
roles/looker.instanceUser)Can sign in to Looker (Google Cloud core) instances
Cannot access Looker (Google Cloud core) resources in the Google Cloud console.
roles/looker.viewer)roles/looker.admin)Verified on each login to Looker (Google Cloud core) that uses primary OAuth or backup OAuth and each time the user makes a call to the Looker API, this role (or a custom role that includes the looker.instances.update permission) also grants the Admin via IAM role within the instance.
The Admin via IAM role contains all the permissions and capabilities of the Admin Looker role. This role cannot be removed or reassigned within the Looker (Google Cloud core) instance. To remove the Admin via IAM role, reassign the principal to an IAM role other than Looker Admin (roles/looker.admin). Changes to IAM roles are automatically synced to the Looker (Google Cloud core) instance even if the user logs in with a third-party identity provider after the change. For more information, see the Admin Looker role versus Admin via IAM Looker role section.
Additionally, user accounts with the owner role for a project can log in to and administer any Looker (Google Cloud core) instances within that project. These users will be granted the Admin Looker role.
If the predefined roles don't provide the set of permissions that you want, you can also create your own custom roles.
Looker (Google Cloud core) accounts are created at the time of first login to a Looker (Google Cloud core) instance.
There are two roles within a Looker (Google Cloud core) instance that use the Admin permission set and confer the same admin privileges within the instance. The following table summarizes the two roles' similarities and differences.
| Property | Admin Looker role | Admin via IAM Looker role |
|---|---|---|
| Authoritative source | Granted by another admin in the Looker (Google Cloud core) instance | Directly linked to the Looker Admin IAM role |
| Can be added or removed within a Looker (Google Cloud core) instance? | Yes | No |
| Can be added or removed with IAM? | No | Yes |
| Permissions within Looker (Google Cloud core) | All permissions | All permissions |
| Permissions within the Google Cloud console | None | Full access to all Looker (Google Cloud core) resources |
| Role validation | Continually within the Looker (Google Cloud core) instance | Upon every login to the Looker (Google Cloud core) instance and every Looker API call.Changes to a role with IAM may take several minutes to propagate. |
| Scope | Individual Looker (Google Cloud core) instance | All Looker (Google Cloud core) instances within a Google Cloud project |
A user can have both the Admin and the Admin via IAM Looker roles. Therefore, if you want to revoke admin privileges, be sure to remove both the IAM role and the Admin role within the Looker (Google Cloud core) instance.
Within the Looker (Google Cloud core) instance, the Google Authentication page in the Authentication section of the Admin menu lets you configure some Google OAuth settings. You must have the Admin Looker role.
In the Merge Users Using field, specify the method to be used to merge a first-time OAuth sign-in to an existing user account. When a user signs in for the first time through OAuth, this option will connect the user to their existing account by finding the account with a matching email address. If no account exists for the user, a new user account will be created.
You can merge users from the following systems:
If you have more than one system in place, you can specify more than one system to merge by in this field. Looker (Google Cloud core) will look up users from the listed systems in the order in which the systems are specified. For example, if you first created some users using OIDC and then later used SAML, when a user attempts to login with OAuth for the first time, Looker (Google Cloud core) first looks for the user using OIDC and then, if it doesn't find a match for the user with OIDC, it would then look for the user using SAML.
If you don't want Looker (Google Cloud core) to merge users, leave this field blank.
If you have managed Google Groups, Looker (Google Cloud core) can create Looker groups that mirror the membership of your Google Groups. This means that you don't have to set up users in Looker (Google Cloud core) directly but can manage user access by managing the membership of the Google Groups. Additionally, Looker groups can be used to assign roles to group members, set content access controls, control feature and data access, and assign user attributes.
For group mirroring to function correctly, users must have the VIEW_MEMBERSHIP permission, which lets them view the membership of the Google Groups that they belong to. To grant this permission in the Google Groups UI settings, set the Who can view members field to Group members.
The mirrored Looker groups (and any associated roles and access) are applied to new users at their initial login to the Looker (Google Cloud core) instance. The groups aren't applied to pre-existing users, and the groups aren't reapplied if they are removed from a user's account within Looker (Google Cloud core) after the user's initial login.
The Admin via IAM Looker role, which is automatically granted to users who have the Looker Admin role in the IAM system, overrides group mirroring. Users with the Looker Admin role in the IAM system are automatically assigned the Admin via IAM role within Looker (Google Cloud core) regardless of what group memberships they have. In addition, these users will be assigned to mirrored groups and receive roles and access through the standard mirroring process.
We recommend that you enable group mirroring for only the primary authentication method for Looker (Google Cloud core). If you are using OAuth as the backup authentication method, don't enable group mirroring for OAuth. If you enable group mirroring for both the primary and secondary methods of authentication, the following behaviors will occur:
To enable group mirroring, complete the following steps:
roles/serviceusage.serviceUsageAdmin) IAM role to enable APIs.
In the Google Cloud console, update the OAuth client's consent screen to add the https://www.googleapis.com/auth/cloud-identity.groups.readonly scope. You must have the clientauthconfig.clients.update IAM permission to add scopes. Complete the following steps to update the consent screen:
https://www.googleapis.com/auth/cloud-identity.groups.readonly scope and select the checkbox next to it.Close the panel and click Save on the Data Access page to save the scope.
In the Looker (Google Cloud core) instance, enable the Mirror Google Groups toggle on the Google Authentication page. This toggle defaults to disabled. Complete the following fields:
Looker (Google Cloud core) will make one Looker group for every Google Group that is added to the Google Authentication page. You can view those Looker groups on the Groups page of Looker (Google Cloud core).
When you make changes to a Google Groups membership, those changes are automatically propagated to the mirrored Looker group's membership and validated at the time of each user's next login.
If you edit the Custom name or Role fields that are assigned to a group on the Google Authentication page, this changes how the mirrored Looker group's name appears in Looker (Google Cloud core)'s Groups page or the role(s) assigned to the group, but it doesn't change the group members.
If you change the name or email in Google Group ID field on the Google Authentication page to a new Google group's ID, that changes the members of the mirrored Looker group to the members of the new Google group, but it would maintain the group name and roles as defined on the Google Authentication page.
Any edits that are made to a mirrored group will be applied to users of that group when they next sign in to Looker (Google Cloud core).
If you want to stop mirroring your Google groups within Looker (Google Cloud core), disable the Mirror Google Groups toggle on the Google Authentication page of the Looker (Google Cloud core) instance. Disabling the toggle results in the following behavior:
If the Mirror Google Groups toggle is enabled, the Google Authentication page displays the Advanced Role Management settings. The options in this section determine how much flexibility Looker admins have when configuring Looker groups and users who have been mirrored from Google.
If you want your Looker group and user configuration to strictly match your Google Groups configuration, turn on all the Advanced Role Management options. When all of the options are enabled, Looker admins cannot modify mirrored group memberships and can only assign roles to users through Google Groups.
If you want to have more flexibility to customize your groups within Looker (Google Cloud core), turn off these options. Your Looker (Google Cloud core) groups will still mirror your Google Groups configuration, but you will be able to perform additional group and user management within Looker (Google Cloud core), such as adding Google users to Looker groups or assigning Looker roles directly to Google users.
For Looker (Google Cloud core) instance, these options are off by default.
The Advanced Role Management section contains the following options:
Prevent individual Google users from receiving direct roles: Turning this option on prevents Looker admins from assigning Looker roles directly to Google users. Google users will receive roles only through their group memberships. If Google users are allowed membership in built-in (not mirrored) Looker groups, they can still inherit their roles both from mirrored Google Groups and from built-in Looker groups. Any Google users who were previously assigned roles directly will have those roles removed when they next log in.
If this option is off, Looker admins can assign Looker roles directly to Google users within the Looker (Google Cloud core) instance.
Prevent direct membership in non-Google groups: This option prevents Looker admins from adding members of mirrored groups directly to built-in Looker groups that are not part of the mirrored group configuration on the Google Authentication page.
If this option is selected, any Google users who were previously assigned to built-in Looker groups will be removed from those groups when they next login.
If this option is cleared, Looker admins can add Google users directly to built-in Looker groups.
Prevent Role Inheritance from non-Google Groups: This option prevents members of mirrored groups from inheriting roles from built-in Looker groups. If mirrored Google Groups are allowed to be members of built-in Looker groups, Google users may retain membership in any built-in Looker groups. Any Google users who previously inherited roles from a built-in Looker group will lose those roles when they next sign in.
If this option is off, mirrored groups or Google users who are added as members of a built-in Looker group will inherit the roles that are assigned to the built-in Looker group.
Auth Requires Role: If this option is on, Google users are required to have a Looker role assigned. Any Google users who don't have a role assigned won't be able to sign in to Looker (Google Cloud core) at all.
If this option is off, Google users can authenticate to Looker (Google Cloud core) even if they have no role assigned. A user with no assigned role won't be able to see any data or take any action in Looker (Google Cloud core), but they will be able to sign in to Looker (Google Cloud core).
If the Mirror Google Groups toggle is disabled, the Roles for new users setting appears on the Google Authentication page. This setting lets you set the default Looker role that will be granted to user accounts with the Looker Instance User (roles/looker.instanceUser) IAM role or the Looker Viewer (roles/looker.viewer) IAM role upon their first login to a Looker (Google Cloud core) instance. To set a default role, follow these steps:
Admin roles can't be default roles. User accounts with a Looker Admin (roles/looker.admin) IAM role will be granted the Admin via IAM Looker role upon first login in addition to the role that's selected in the Roles for new users setting.
If you enable the Mirror Google Groups toggle after customizing the Roles for new users setting, the roles that are assigned to users through the Roles for new users setting will be removed for users upon their next login and replaced by the roles assigned through the Mirror Google Groups setting.
Click the Test Google Authentication button to test your settings. Tests will redirect out to Google's OAuth server and will open a browser tab. The tab displays the following information:
Once you are done entering your information and the tests are all passing, select the I have confirmed the configuration above and want to enable applying it globally checkbox, and click Submit to save.
Once a Looker (Google Cloud core) instance has been created, users can be added through IAM. To add users, follow these steps:
Navigate to the Google Cloud console project that the Looker (Google Cloud core) instance resides in.
Navigate to the IAM & Admin > IAM section of the Google Cloud console.
Select Grant Access.
In the Add principals section, add one or more of the following:
In the Assign roles section, select one of the predefined Looker (Google Cloud core) IAM roles or a custom role that you have added.
Click Save.
Communicate to new Looker (Google Cloud core) users that access has been granted and direct them to the URL for the instance. From there they can sign in to the instance, at which point their accounts will be created. No automated communication will be sent.
If you change a user's IAM role, the IAM role propagates to the Looker (Google Cloud core) instance within a few minutes. If there is an existing Looker user account, that user's Looker role remains unchanged.
All users must be provisioned by the IAM steps described previously, with one exception: You can create Looker API-only service accounts within the Looker (Google Cloud core) instance.
The first time that users sign in, they are asked to sign in using their Google Account. Each user should use the same account that the Looker admin listed in the Add principals field when granting them access. Users will view the OAuth consent screen that was configured during OAuth client creation. After users agree to the consent screen, their accounts within the Looker (Google Cloud core) instance are created and they are logged in.
After that, users will be automatically logged in to Looker (Google Cloud core) unless their authorization expires or is revoked by the user. In those scenarios, users will again view the OAuth consent screen and be asked to consent to authorization.
Some users may be assigned API credentials for use in retrieving an API access token. If the authorization for those users expires or is revoked, their API credentials stop working. Any current API access tokens will also stop working. To resolve the issue, the user must re-authorize their credentials by logging back in to the Looker (Google Cloud core) UI for each Looker (Google Cloud core) instance that is affected. Alternatively, using API-only service accounts helps avoid a credential authorization failure for API access tokens.
If you have a role that lets you manage IAM access, you can remove access to a Looker (Google Cloud core) instance by revoking the IAM role that granted access. If you remove a user account's IAM role, that change propagates to the Looker (Google Cloud core) instance within a few minutes. The user will no longer be able to authenticate to the instance. However, the user account will still appear active on the Users page. To remove the user account from the Users page, delete the user within the Looker (Google Cloud core) instance.
OAuth is the backup authentication method when SAML or OIDC is the primary authentication method.
To set up an OAuth as the backup method, grant each Looker (Google Cloud core) user the appropriate IAM role to log in to the instance.
Once the backup method is set up, users access it through the following steps:
Users can then log in using their Google Accounts. When first logging in with OAuth, they will be prompted to accept the OAuth consent screen that was set up during instance creation.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-06-09 UTC.