Skip to main content
GCP

GCP Onboarding Process

Connect Google Cloud to Wiv with the in-app keyless wizard. Wiv creates a read-only service account and impersonates it — no JSON keys to download.

Written By Dotan Cohen

Last updated 4 days ago

GCP Onboarding Process

Connect Google Cloud to Wiv from Integrations → GCP → New GCP Integration. The wizard grants Wiv read-only access with no service account keys.

Need to upload a JSON key instead? Use GCP Onboarding Process (Manual).

What Wiv sets up

After you grant access, Wiv:

  1. Creates or reuses a host project named wiv-host-<organization> (for example, org wiv.ai → wiv-host-wiv-ai) and links it to a Cloud Billing account you can see. If you cannot create projects, you pick an existing project in the organization.

  2. Enables the APIs the host project needs (Service Usage, IAM, IAM Credentials, Cloud Resource Manager, BigQuery).

  3. Creates or reuses a read-only service account with the wiv-readonly- prefix.

  4. Grants viewer-only organization roles to that service account.

  5. Grants impersonation so Wiv can use the service account without downloading a key.

  6. Finds your BigQuery Cloud Billing export (or asks you to enter it) and finishes the integration.

Wiv never stores Google OAuth tokens or JSON keys on the integration. Customer GCP resources (host project, service account, IAM bindings) stay in your org if onboarding fails, is retried, or is cancelled.

Trust and connectivity

After onboarding, Google trusts one Wiv identity: the platform service account wiv-gcp-platform@wiv-prod-1.iam.gserviceaccount.com. You allow that account to impersonate wiv-readonly-* in your project. Wiv holds no JSON key.

How Wiv gets a Google access token after onboarding. Your Google Cloud organization is on the left, the Wiv platform on the right.

When you click New GCP integration, an admin in your organization signs in with Google and approves a consent screen. Wiv creates the host project, the read-only service account, and the roles with that admin's permissions, then drops the admin's tokens.

What happens when your admin connects GCP, from Google sign-in through provisioning.

Roles, the network path, and how to revoke access are in Wiv GCP connectivity architecture.

Prerequisites

1. BigQuery Cloud Billing export

Wiv reads cost from a BigQuery billing export. If you do not have one yet, follow Google’s export guide and choose Detailed usage cost data.

Wiv prefers detailed tables (gcp_billing_export_resource_v1_*) over standard tables (gcp_billing_export_v1_*).

2. Permissions in Wiv

You need permission to create integrations in Wiv.

3. Permissions in Google Cloud

Sign in to Google as a user who can complete the grant for the selected organization. Typical needs:

Scope

Why it is needed

Organization

List organizations and set organization-level IAM

Billing account

List your Cloud Billing accounts and link the host project to one

Project

Create or select the host project, enable APIs

Project

Create a service account and allow Wiv to impersonate it

Recommended predefined roles:

Scope

Role

Purpose

Organization

roles/resourcemanager.organizationAdmin

List orgs, set org-level IAM

Billing account

roles/billing.user

List billing accounts, link the host project

Project

roles/owner or roles/editor

Create the host project

Project

roles/iam.serviceAccountAdmin

Create the service account

Project

roles/serviceusage.serviceUsageAdmin

Enable APIs on the host project

Wiv only uses open Cloud Billing accounts that the signed-in Google user can see. If the user sees none, Wiv cannot link the host project and onboarding fails with No open Cloud Billing account is available for this Google account.

Organization-level IAM changes apply across the organization. Use least privilege, and only grant access for the organization you intend to connect.

4. Organization policy: Domain restricted sharing

The Impersonation grant phase adds Wiv's platform service account (wiv-gcp-platform@wiv-prod-1.iam.gserviceaccount.com) as a Token Creator on the wiv-readonly-… service account in your organization. That service account belongs to Wiv's Google Cloud organization, not yours.

If your organization enforces Domain restricted sharing (constraints/iam.allowedPolicyMemberDomains), Google rejects the grant with:

One or more users named in the policy do not belong to a permitted customer.
User wiv-gcp-platform@wiv-prod-1.iam.gserviceaccount.com is not in permitted organization.

Organizations created on or after May 3, 2024 enforce this policy by default.

Before you start the wizard, ask an Organization Policy Administrator (roles/orgpolicy.policyAdmin) to add Wiv's organization principal set to the allowed values. Scope the override to the host project (or its folder) rather than the whole organization.

Allowed value to add

Covers

principalSet://cloudresourcemanager.googleapis.com/organizations/809599052593

All service accounts in Wiv's organization (wiv.ai)

Console

  1. In the Google Cloud console, open IAM & Admin → Organization Policies.

  2. In the project picker, select the host project (for example wiv-host-<organization>).

  3. Select Domain restricted sharing, then click Manage policy.

  4. Under Applies to, choose Override parent's policy.

  5. Click Add a rule. Under Policy values, select Custom. Under Policy type, select Allow.

  6. Under Custom values, keep your own customer ID and add principalSet://cloudresourcemanager.googleapis.com/organizations/809599052593.

  7. Click Done, then Set policy.

gcloud

Save the following as wiv-domain-policy.yaml, replacing HOST_PROJECT_ID and YOUR_CUSTOMER_ID (your own C0… Workspace or Cloud Identity customer ID from gcloud organizations list):

name: projects/HOST_PROJECT_ID/policies/iam.allowedPolicyMemberDomains
spec:
  inheritFromParent: false
  rules:
    - values:
        allowedValues:
          - is:YOUR_CUSTOMER_ID
          - is:principalSet://cloudresourcemanager.googleapis.com/organizations/809599052593

Apply it, then confirm the effective policy on the host project includes the Wiv entry:

gcloud org-policies set-policy wiv-domain-policy.yaml
gcloud org-policies describe iam.allowedPolicyMemberDomains \
  --project=HOST_PROJECT_ID --effective

Then run (or retry) the wizard. Google keeps honoring the Token Creator binding even if you later tighten the policy again, so you can remove the exception after onboarding succeeds if your security policy requires it.

If you cannot change organization policy, use GCP Onboarding Process (Manual). The manual path grants roles only to a service account inside your organization and is not affected by this constraint.

Connect in Wiv

  1. Sign in to Wiv and go to Integrations.

  2. Click GCP, then New GCP Integration.

  3. Follow the four wizard steps: Connect, Configure, Provision, Complete.

Connect

On Grant Wiv.ai access to GCP, read Before you start — it covers the host project Wiv creates, the Cloud Billing account you pick in the next step (sign in as a user who can see it), and the Domain restricted sharing exception — then click Connect to Google Cloud.

Google asks you to authorize Wiv. The grant is read-oriented:

  • Read cloud metadata (organizations, folders, and projects)

  • Least-privilege roles only

  • No service account keys — nothing sensitive is downloaded

You can choose Onboard Manually at any time to use the JSON key path instead.

Configure

On Choose your GCP scope:

  1. Select the Organization to connect.

  2. Select the Billing account. The dropdown lists every open Cloud Billing account your Google user can see, with the first one preselected; the host project is linked to the account you choose. If it shows No billing accounts available, go back and sign in as a user with Billing Account User on the billing account, or onboard manually.

  3. Confirm the Host project. Wiv suggests wiv-host-<organization> (for example wiv-host-wiv-ai). If you cannot create projects, pick an existing project from the list.

  4. Confirm the generated Integration name (Organization · host-project). It is created from the organization and host project.

  5. Click Apply. The panel shows Apply to continue until this succeeds.

  6. Click Next.

    Choose your GCP scope: organization, billing account, host project, and generated integration name

Provision

Setting up your integration lists each phase as it runs. Next stays disabled until setup finishes (or billing details are confirmed). You can still choose Onboard Manually or Back.

Phase

What happens

Verifying granted scope

Confirms the organization from your Google grant

Host project setup

Creates or reuses the host project (Created or Reused)

API enablement

Turns on required APIs on the host project

Service account creation

Creates or reuses wiv-readonly-…

Organization role grants

Assigns viewer roles at organization scope

Impersonation grant

Lets Wiv impersonate the service account (IAM can take a minute to propagate)

Billing

Scans for a BigQuery billing export

Billing export found

When a detailed usage cost export is detected, the panel shows Billing export found and fills:

  • Billing project ID

  • Dataset name

  • Billing table name

  • WIV will read — the project.dataset.table path Wiv queries

Edit a field if this is not the export you want, then click Next.

No billing export found

If the scan does not find an export (it looks across projects visible to your grant, preferring names that include billing):

  1. Confirm detailed usage cost export is enabled.

  2. Click Retry Scan, or enter Billing project ID, Dataset name, and Billing table name yourself, then continue.

The wizard waits about a minute for the automatic scan before asking you to fill the fields. Onboarding cannot finish until those three values are set.

If a phase fails, use Retry when the UI offers it, or Onboard Manually. Wiv reuses the host project and service account on retry instead of deleting them.

Complete

When setup succeeds you see Your GCP environment is connected. Wiv starts analyzing your GCP configuration. Click View Cloud Inventory to open the GCP integrations list.

Generate Integration Link

Use Generate Integration Link when the person who can authorize Google Cloud is not a Wiv user — for example an MSP onboarding a customer's organization. The recipient completes the same four steps in a standalone page, with no Wiv login and no JSON key. The link runs the same provisioning as the in-app wizard.

Create and share the link

  1. Go to Integrations → GCP and click Generate Integration Link. MSP users can also generate a link for a specific customer from Customers.

  2. Copy the URL and send it to the person who will connect the organization.

The link requires no authentication to open. It is single-use and expires after 7 days. Share it only with the intended recipient.

What the recipient does

  1. Connect — The screen is titled Grant … access to GCP with your organization's name. The recipient clicks Connect to Google Cloud and signs in with a Google user that has the Google Cloud permissions listed above.

  2. Configure — On Choose your GCP scope, the recipient reviews:

    • Organization — the recipient's organization. It is a dropdown when the Google user can see more than one.

    • Billing account — the Cloud Billing account the host project is linked to. The dropdown lists every open billing account the Google user can see, with the first one preselected. It is shown even when there is only one account. Costs for this integration are billed to the selected account.

    • Host project — set by Wiv. For an MSP customer it is wiv-host-<msp>-<customer> (for example wiv-host-commit-appcharge).

    • Integration name — generated from the organization and host project. It cannot be edited.

    The recipient clicks Apply, then Next once the panel shows Configuration confirmed. Next stays disabled until Apply succeeds.

  3. Provision — the same phases as the in-app wizard. When the billing scan finishes, the recipient reviews or enters the Billing project ID, Dataset name, and Billing table name, then clicks Next.

  4. Complete — Your GCP environment is connected. The recipient clicks Close tab.

Choose your GCP scope in the link flow: organization, billing account, host project, and integration name

The integration is created in the recipient's organization. For an MSP customer it is also shared with the MSP organization, so it appears under Integrations → GCP for both.

If something fails

The recipient sees which step failed (for example Configuring host project failed) and a Download report button. The report is a CSV with three columns: timestamp, step and phase, and the error message from Wiv. Close tab becomes available after the report is downloaded. Ask the recipient to send you the report, fix the cause, and generate a new link.

Report message

Likely cause

Action

No open Cloud Billing account is available for this Google account.

The Google user cannot see an open Cloud Billing account

Grant roles/billing.user on the billing account to that user, then send a new link

Failed to link billing account to host project

The user can see the billing account but cannot link projects to it

Grant roles/billing.user on the selected billing account, then send a new link

Any Provision phase failed

See Troubleshooting below

Fix the cause, then send a new link. Wiv reuses the host project and service account

After onboarding

  • Confirm the new GCP integration appears under Integrations → GCP.

  • In Google Cloud, confirm the host project and wiv-readonly-… service account, and that viewer roles are assigned at the organization.

  • For what each role is used for, see GCP Permissions List.

  • To add roles later, see Permissions Update GCP.

Application privacy policy

This Application Privacy Policy describes how Wiv Cloud Ltd. (“Wiv”, “we”, “us”) collects, uses, stores, and shares Google user data when you connect Google Cloud to Wiv through the GCP keyless onboarding flow (Google OAuth).

This policy applies specifically to the Wiv Google Cloud OAuth application used for GCP onboarding. It supplements Wiv’s general Privacy Policy.

Google user data we access

When you click Grant Read Access and authorize Wiv in Google, Wiv requests these OAuth scopes:

  • openid and https://www.googleapis.com/auth/userinfo.email — to identify the Google account that completed the grant (email address).

  • https://www.googleapis.com/auth/cloud-platform — temporary access to your Google Cloud resources so Wiv can complete onboarding (list organizations/projects, create or select the host project, enable APIs, create a read-only service account, grant organization viewer roles, and allow Wiv to impersonate that service account).

How we use Google user data

We use Google user data only to:

  • Authenticate the administrator who starts GCP onboarding.

  • Provision the Wiv GCP integration in your Google Cloud organization (host project, read-only service account, IAM bindings, and billing-export discovery).

  • After onboarding, analyze your Google Cloud configuration and billing export for FinOps / cloud operations features inside Wiv.

We do not use Google user data to advertise to users, sell personal data, or train unrelated AI models on your Google account content.

How we store Google user data

  • OAuth access and refresh tokens are held only for the active installation session (encrypted at rest) and are deleted when onboarding finishes, fails, is cancelled, or the session expires. They are not stored on the lasting GCP integration record.

  • Service account keys are not downloaded or stored for keyless onboarding. Ongoing access uses service-account impersonation of the customer-owned wiv-readonly-… account.

  • Integration metadata needed to operate the product (for example organization/project identifiers, service account email, and BigQuery billing export project/dataset/table) is stored in Wiv as part of your tenant’s GCP integration.

Data protection mechanisms for sensitive data

Security procedures are in place to protect the confidentiality, integrity, and availability of Google user data processed by the Wiv Google Cloud OAuth application. In particular:

  • Encryption in transit: We use encryption (TLS/HTTPS) to protect Google user data and API traffic while it is transmitted between your browser, Google, and Wiv services.

  • Encryption at rest: We use encryption to protect sensitive installation-session data. Google OAuth access and refresh tokens are encrypted before storage for the duration of the onboarding session and are deleted when the session ends.

  • Access controls: Access to Google user data and GCP integration configuration inside Wiv is limited to authenticated, authorized users within your tenant and to Wiv systems/personnel who need that access to operate or support the service. Administrative and infrastructure access is restricted and logged.

  • Least privilege: After keyless onboarding, ongoing Google Cloud access uses impersonation of a customer-owned read-only service account rather than retaining end-user OAuth credentials on the lasting integration. Service account JSON keys are not downloaded or stored for this flow.

  • Session controls: Installation sessions that hold OAuth grants are time-bounded; tokens are removed when onboarding completes, fails, is cancelled, or the session expires.

  • Infrastructure security: Wiv runs on hardened cloud infrastructure with network controls, monitoring, and operational security practices designed to prevent unauthorized access, disclosure, alteration, or destruction of Google user data.

Sharing

We do not sell Google user data. We share it only with subprocessors that help us operate Wiv (for example cloud infrastructure providers), under contractual confidentiality and security obligations, or when required by law.

Retention and deletion

Installation-session OAuth tokens are removed as described above. Integration configuration and related operational data are retained while the GCP integration exists in your Wiv tenant and are removed or anonymized according to your account deletion / data-retention practices and our general Privacy Policy.

Your choices

You may revoke Wiv’s Google OAuth grant at any time in your Google Account permissions. You may also disconnect or delete the GCP integration in Wiv, and remove the host project, service account, or IAM bindings in Google Cloud.

Contact

Privacy questions: privacy@wiv.ai. Support: support@wiv.ai.

Application terms of service

These Application Terms of Service govern use of the Wiv Google Cloud OAuth application and the GCP keyless onboarding flow. They supplement Wiv’s general Website Terms of Use and any master subscription agreement between you and Wiv.

What the application does

The application lets an authorized Google Cloud administrator grant Wiv temporary OAuth access so Wiv can set up a read-only GCP integration: create or reuse a host project and wiv-readonly-… service account, assign viewer-oriented organization roles, grant impersonation to Wiv, and locate or confirm a BigQuery Cloud Billing export.

Your responsibilities

  • You represent that you have authority to grant organization- or project-level access for the Google Cloud organization you select.

  • You are responsible for reviewing the roles and resources Wiv creates or modifies in your Google Cloud environment.

  • You must keep BigQuery billing export configured if you want cost insights that depend on that export.

Access model

  • Keyless onboarding does not download JSON service-account keys to your workstation for storage in Wiv.

  • After setup, Wiv accesses Google Cloud by impersonating the customer-owned read-only service account, not by retaining end-user OAuth tokens on the integration.

  • Customer GCP resources created during onboarding (host project, service account, IAM bindings) remain in your Google Cloud organization if onboarding fails, is retried, or is cancelled.

Acceptable use

You may use the application only to connect Google Cloud environments you are authorized to manage, and only in accordance with Google’s terms, applicable law, and your agreement with Wiv. You may not misuse the OAuth grant to access data beyond the scopes you approved or outside the onboarding / integration purpose.

Disclaimer

The application is provided as part of the Wiv service. Except as stated in your commercial agreement with Wiv, the OAuth onboarding flow is provided on an “as available” basis, and Wiv is not responsible for Google Cloud outages, IAM propagation delays, or misconfiguration in your Google Cloud organization.

Contact

Questions about these terms: support@wiv.ai.

Troubleshooting

Symptom

Likely cause

Action

Grant / read access failed

Google user cannot authorize the org, or you cancelled the consent

Retry Grant Read Access, or onboard manually

Billing account shows "No billing accounts available"

The Google user cannot see an open Cloud Billing account

Grant roles/billing.user on the billing account, go back to Connect and sign in again, or onboard manually

Host project setup failed: "Failed to link billing account"

The user can see the billing account but cannot link projects to it

Grant roles/billing.user on the selected billing account, then retry

Host project setup failed

Missing project-create rights, or the suggested ID is taken

Create projects in the org, pick an existing host project, or onboard manually

API enablement stuck or failed

Missing serviceusage permission, or Google is still enabling APIs

Confirm Service Usage Admin on the host project, then retry

Impersonation grant running a long time

IAM Token Creator binding is still propagating

Wait for the wizard to retry. Do not delete the service account

Impersonation grant failed: "do not belong to a permitted customer"

Domain restricted sharing blocks Wiv's platform service account

Add Wiv's organization principal set to the policy (see 4. Organization policy: Domain restricted sharing), then retry

No billing export found

Export not enabled, or the table is in a project the scan did not see

Set up detailed usage cost export, retry the scan, or enter project / dataset / table manually

Integration missing from the list after success

Browser still showing a cached list

Open Integrations → GCP again, or refresh the page