Continuously Scan with a GCP Integration

With WIF, Mondoo acts as an OIDC identity provider. When it's time to scan, Mondoo issues a short-lived OIDC token and presents it to GCP. GCP validates the token against Mondoo's public signing keys (fetched from Mondoo's OIDC discovery endpoint), then issues temporary GCP credentials that Mondoo uses to read resources from your project or organization. No static keys are stored or transmitted.

Step 1: Create a GCP service account

Create a GCP service account that Mondoo will impersonate to read resources in your project or organization. Do not create a key for this service account. WIF replaces the need for static keys.

1. In the GCP Console, navigate to IAM & Admin > Service Accounts.

2. Select Create Service Account.

3. Give the service account a name (for example, mondoo-scan) and select Create and Continue.

4. Grant the service account both of these roles on the project or organization you want to scan:

   • Viewer (roles/viewer)
   • Browser (roles/browser)

   For instructions, read Manage access to projects, folders, and organizations in the Google documentation.

5. Select Done. Note the service account email address (for example, mondoo-scan@PROJECT_ID.iam.gserviceaccount.com).

Step 2: Create a Workload Identity Pool

A Workload Identity Pool is a GCP resource that manages external identities. You create one pool and add Mondoo as an OIDC provider within it.

:::tip

If you already created a Workload Identity Pool and Mondoo OIDC provider for another integration (such as a Cloud Storage or BigQuery export), you can reuse it. Skip to Step 4.

:::

1. In the GCP Console, navigate to IAM & Admin > Workload Identity Federation.

2. Select Create Pool.

3. Enter a name for the pool (for example, mondoo-scan-pool) and an optional description.

4. Make sure the pool is Enabled and select Continue.

Step 3: Add Mondoo as an OIDC provider to the pool

Within the Workload Identity Pool, add Mondoo as a trusted OpenID Connect (OIDC) identity provider.

1. In the pool you just created, select Add Provider.

2. For Select a provider, choose OpenID Connect (OIDC).

3. Enter a provider name (for example, mondoo-provider).

4. Set the Issuer (URL) to the Mondoo STS endpoint for your environment:

   Environment	Issuer URL
   Mondoo (US)	https://sts.us.mondoo.com
   Mondoo (EU)	https://sts.eu.mondoo.com
   Mondoo Edge	https://sts.edge.mondoo.com
   Dedicated deployment	https://sts.mondoo.CUSTOMER.com

   GCP automatically fetches the OIDC discovery document from <issuer>/.well-known/openid-configuration to obtain Mondoo's signing keys. To learn more about Mondoo's OIDC endpoints, see Mondoo as an OIDC identity provider.

5. Under Audiences, select Allowed audiences and leave the default value. The audience is the full provider resource name, which you note in the next step.

6. Under Attribute Mapping, add this mapping:

   Google attribute	OIDC attribute
   google.subject	assertion.sub

7. Select Save.

Step 4: Note the WIF audience URL

After creating the provider, note the full audience URL. It follows this format:

https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

You can find this on the provider details page in the GCP Console. You enter this value in Mondoo in the next step.

:::tip

PROJECT_NUMBER is a numeric value, not the project ID string. Find it on your GCP project's dashboard or by running:

gcloud projects describe PROJECT_ID --format='value(projectNumber)'

:::

Step 5: Create the GCP integration in Mondoo

1. Access the Integrations > Add > GCP page in one of two ways:

   • New space setup: After creating a new Mondoo account or creating a new space, the initial setup guide welcomes you. Select BROWSE INTEGRATIONS and then select GCP.

     

   • INTEGRATIONS page: In the side navigation bar, under INTEGRATIONS, select Add New Integration. Under Cloud Security, select GCP.

     

2. To integrate your entire GCP organization with Mondoo, select Organization. To limit the integration to a single project, select Project.

3. In the Choose an integration name box, enter a name for the integration.

4. Identify the organization or project to integrate with Mondoo:

   • For an organization: In the Enter the organization resource ID box, enter your organization's resource ID. To learn how to retrieve this value, read Getting your organization resource ID in the Google documentation.

   • For a project: In the Enter the project ID box, enter your project's ID. To learn how to retrieve this value, read Identifying projects in the Google documentation.

5. Under Configure authentication, select Workload Identity Federation.

6. In the WIF Audience URL box, enter the audience URL from Step 4.

7. In the Service Account Email box, enter the email of the service account you created in Step 1 (for example, mondoo-scan@PROJECT_ID.iam.gserviceaccount.com).

8. Select CREATE INTEGRATION.

Step 6: Copy the WIF subject value

After you create the integration, Mondoo computes a WIF subject value that uniquely identifies this integration. You need this value to authorize Mondoo in GCP.

1. On the integration details page in the Mondoo Console, find the WifSubject field.

2. Copy the subject value. It has the format INTEGRATION_ID@integrations.SPACE_ID.

:::note

The WIF subject is a computed, read-only value. Mondoo generates it automatically when you create the integration. You cannot set or change it.

:::

Step 7: Authorize the WIF subject to impersonate the service account

Back in GCP, grant the WIF subject the Workload Identity User role on the service account you created in Step 1. This allows Mondoo's OIDC-validated identity to impersonate the service account and scan your resources.

Run this gcloud command, substituting your own values:

gcloud iam service-accounts add-iam-policy-binding \
  mondoo-scan@PROJECT_ID.iam.gserviceaccount.com \
  --project=PROJECT_ID \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_VALUE"

Step 8: Enable policies and verify the integration

1. On the Recommended Policies page, enable the policies on which you want to base assessments of your Google Cloud environment. To learn more, read Manage Policies.

2. Return to the integration details page and wait for the first scan to complete. If the status changes to active, the setup is working correctly.

If the scan fails, double-check:

• The WIF audience URL matches the full provider resource name in GCP exactly (including project number, pool ID, and provider ID).
• The service account email is correct.
• The gcloud iam service-accounts add-iam-policy-binding command completed successfully with the correct subject value.
• The service account has the Viewer and Browser roles on the project or organization you're scanning.

Step 1: Create a service account and JSON key

To access the data it needs, your GCP integration needs a GCP service account. To learn about service accounts, read Understanding service accounts in the Google documentation.

1. Create a new GCP service account for the Mondoo integration to use.

   For instructions, read Creating and managing service accounts in the Google documentation.

   Note the email address created for the new service account.

2. Grant the service account both of these roles on the project or organization you want to scan:

   • Viewer (roles/viewer)
   • Browser (roles/browser)

   For instructions, read Grant a single role in the Google documentation.

3. Create a JSON key for the service account.

   For instructions, read Create and manage service account keys in the Google documentation.

   Save the JSON file that downloads to your workstation when you create the key. You need it to configure the integration in the next step.

Step 2: Add the integration in Mondoo

1. Access the Integrations > Add > GCP page in one of two ways:

   • New space setup: After creating a new Mondoo account or creating a new space, the initial setup guide welcomes you. Select BROWSE INTEGRATIONS and then select GCP.

     

   • INTEGRATIONS page: In the side navigation bar, under INTEGRATIONS, select Add New Integration. Under Cloud Security, select GCP.

     

2. To integrate your entire GCP organization with Mondoo, select Organization. To limit the integration to a single project, select Project.

3. In the Choose an integration name box, enter a name for the integration. Make it a name that lets you easily recognize the GCP project or organization.

4. Identify the organization or project to integrate with Mondoo:

   • For an organization: In the Enter the organization resource ID box, enter your organization's resource ID. To learn how to retrieve this value, read Getting your organization resource ID in the Google documentation.

   • For a project: In the Enter the project ID box, enter your project's ID. To learn how to retrieve this value, read Identifying projects in the Google documentation.

5. Under Configure authentication, select Service Account Key.

6. Under Provide your Google service account config, upload the GCP service account's JSON key that you downloaded in the previous section by dragging the file into the Drag and drop your .json file here box, or selecting the cloud icon and choosing the file.

   

7. To complete the integration, select the START SCANNING button.

8. On the Recommended Policies page, enable the policies on which you want to base assessments of your Google Cloud environment. To learn more, read Manage Policies.