Overview
Google Workspace is an ownership and cloud resources platform.
Integrating Cortex with Google allows you to:
- Automatically discover and track ownership of Google entities
- Create Scorecards that track progress and drive alignment on projects involving your Google resources and teams
For information on configuring Google SSO for logging in to Cortex, see the Google SSO documentation.
How to configure Google with Cortex
Prerequisites
Before getting started:
- Create a Google service account and add it in Cortex under Settings → Google.
- See Configure service account permissions below for the list of required service account permissions.
- Enable the Google Admin SDK API.
- For Google Cloud resources, in each project, enable the following:
- App Engine Admin API
- ArtifactRegistry API
- Apigee APIs
- BigQuery API
- BigQuery Connection API
- Cloud Asset API
- Cloud Composer API
- Cloud Functions
- Cloud SQL Admin
- Cloud Storage
- Compute Engine API
- Kubernetes Engine API
- Memorystore for Memcached API
- Memorystore for Redis API
- OS Config API
- Kubernetes Engine API
- Resource Manager API
- Spanner API
- Serverless VPC Access API
- For each project in Vertex AI, enable the following:
Configure service account permissions
The service account should also have the following permissions for each project to enable Google Cloud resources:
Google service account permissions
- AI Platform → AI Platform Viewer, Dataform Viewer, Cloud Storage for Firebase Viewer, Data Catalog Viewer, Vision AI Viewer, Notebooks Viewer, Dataflow Viewer
- Apigee → Cloud Api Hub Viewer
- App Engine → App Engine Viewer
- Artifact Registry → Artifact Registry Reader
- BigQuery → BigQuery Metadata Viewer
- BigQuery Connection → BigQuery Connection User
- Cloud Asset → Cloud Asset Viewer
- Cloud Asset → ListResource
- Note: This permission is necessary to run services and jobs.
- Cloud Functions → Cloud Functions Viewer
- Cloud Pub/Sub → Pub/Sub Viewer
- Cloud Resource Manager → Browser
- Cloud Run → Cloud Run Viewer
- Cloud SQL → Cloud SQL Viewer
- Cloud Storage → Storage Admin
- Composer → Composer User
- Compute Engine, VM Instances → Compute Viewer
- Kubernetes Engine → Kubernetes Engine Viewer
- Memorystore Memcached → Cloud Memorystore Memcached Viewer
- Memorystore Redis → Cloud Memorystore Redis Viewer
- Service Accounts → View Service Accounts
- Spanner → Cloud Spanner Viewer
- VM Instances Vulnerabilities → OS VulnerabilityReport Viewer
- VPC Serverless Connector → Serverless VPC Access Viewer
If you'd like to create a custom role with the minimum permissions required to enable this feature, add the following:
Custom role minimum permissions
resourcemanager.projects.get
resourcemanager.projects.list
storage.buckets.get
storage.buckets.list
cloudfunctions.functions.get
cloudfunctions.functions.list
cloudsql.instances.get
cloudsql.instances.list
pubsub.topics.get
pubsub.topics.list
compute.urlMaps.list
compute.urlMaps.get
compute.instances.list
compute.instances.get
compute.instanceGroups.list
compute.instanceGroups.get
cloudasset.assets.listResource
osconfig.vulnerabilityReports.get
redis.instances.list
redis.instances.get
memcache.instances.list
memcache.instances.get
run.services.list
run.services.get
run.jobs.list
run.jobs.get
bigquery.connections.get
bigquery.connections.list
bigquery.datasets.get
bigquery.routines.get
bigquery.routines.list
aiplatform.datasets.get
aiplatform.datasets.list
aiplatform.endpoints.get
aiplatform.endpoints.list
aiplatform.featurestores.get
aiplatform.featurestores.list
aiplatform.indexEndpoints.get
aiplatform.indexEndpoints.list
aiplatform.batchPredictionJobs.get
aiplatform.batchPredictionJobs.list
aiplatform.modelDeploymentMonitoringJobs.get
aiplatform.modelDeploymentMonitoringJobs.list
aiplatform.trainingPipelines.get
aiplatform.trainingPipelines.list
aiplatform.pipelineJobs.get
aiplatform.pipelineJobs.list
aiplatform.specialistPools.get
aiplatform.specialistPools.list
aiplatform.tensorboardExperiments.get
aiplatform.tensorboardExperiments.list
aiplatform.studies.get
aiplatform.studies.list
aiplatform.apps.get
aiplatform.apps.list
aiplatform.indexes.get
aiplatform.indexes.list
aiplatform.models.get
aiplatform.models.list
aiplatform.tensorboards.get
aiplatform.tensorboards.list
notebooks.instances.get
notebooks.instances.list
visionai.applications.get
visionai.applications.list
visionai.processors.get
visionai.processors.list
visionai.operators.get
visionai.operators.list
visionai.clusters.get
visionai.clusters.list
appengine.services.get
appengine.services.list
container.clusters.get
container.clusters.list
container.operations.get
container.operations.list
composer.environments.get
composer.environments.list
spanner.instances.get
spanner.instances.list
spanner.instanceConfigs.get
spanner.instanceConfigs.list
iam.serviceAccounts.get
iam.serviceAccounts.list
vpcaccess.connectors.get
vpcaccess.connectors.list
artifactregistry.repositories.get
artifactregistry.repositories.list
iam.serviceAccounts.get
apihub.apiHubInstances.get
apihub.apis.get
apihub.apis.list
If you do not see the settings page you're looking for, you may not have permission to access that page. Please contact your admin for assistance.
Step 1: Configure the integration in Google
- In the G Suite admin console, navigate to Security > API Controls > Manage Domain Wide Delegation. Click Add new.
- Add the client ID you copied during the previous steps, and include the following scopes:
- Navigate to the service account you created for this integration. Click Keys, then generate a key in JSON format.
- Navigate to Admin Roles > Groups Reader and expand the "Admins" panel.
- Click Assign service accounts then enter the email of the service account you created for this integration.
Step 2: Configure the integration in Cortex
- In Cortex, navigate to the Google Cloud & Groups settings page:
- In Cortex, click your avatar in the lower left corner, then click Settings.
- Under "Integrations," click Google Cloud & Groups.
- Configure the Google integration form:
- Domain: Enter your Google domain.
- Service account email: Enter the email address for the service account.
- Credentials JSON: Enter the service account JSON key you created in the previous steps.
- Click Save.
By default, a service will have dependencies on any resource with Google Cloud tag label = "service" and tag value = the service's Cortex tag. After saving your integration, you may customize the tag key name here by entering a new name into the Custom label key field. Leave it blank to use "service" as the key name.
How to connect Cortex entities to Google
Enable automatic import of Google entities
You can configure automatic import from Google Cloud. Note that this setting does not include team entities.
- In Cortex, navigate to the Entities Settings page.
- Next to Auto import from AWS, Azure, and/or Google Cloud, click the toggle to enable the import.
Import teams from Google
To import teams from Google:
- In the main nav of Cortex, click Catalogs > Teams.
- On the right side of the Teams page, click Create team.
- On the "Import entities" page, select Google Cloud & Groups.
- A list of discovered teams will appear. Click a team to add it.
- When you are finished adding teams, click Add.
Automatic ownership of Google entities
Cortex can use Google Groups as an ownership provider, automatically syncing memberships from any Google Group mailing list.
Automatic Google dependency discovery
By default, Cortex will try to automatically discover dependencies between your entities and Google Cloud resources with a matching label. By default the label key that will be matched is service, however you can customize this key value in the Google Cloud Settings page.
If you'd like to explicitly define these Google Cloud dependencies, the x-cortex-dependency field should be a map, defined as follows:
x-cortex-dependency:
gcp:
labels:
- key: my-key-1
value: my-value-1
- key: my-key-2
value: my-value-2
Editing the entity descriptor
You can define the following block in your Cortex entity descriptor to add your Google group as an owner.x-cortex-owners:
- type: group
name: my-group-email@getcortexapp.com
provider: GOOGLE
description: This is a description for this owner # optional
The value for name should be the full group email as defined in Google Groups.
Cortex uses the resource name and project ID to look up catalog entities in your Google Cloud account. Function resource names should be of the format location/function
x-cortex-infra:
Google Cloud:
resources:
- resourceName: location/function
projectId: project1
resourceType: function
- resourceName: example-bucket
projectId: project1
resourceType: storage
Scorecards and CQL
With the Google integration, you can create Scorecard rules and write CQL queries based on Google teams and GCP details.
See more examples in the CQL Explorer in Cortex.
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition: ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
ownership.teams().length > 0
All owner details
List of owners, including team members and individual users, for each entity.
Definition: ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
ownership.allOwners().all((member) => member.email != null)
Team details
List of teams for each entity.
Definition: ownership.teams()
Example
A Scorecard might include a rule to verify that an entity has at least one team owner:
ownership.teams().length > 0
GCP details
Get the GCP details for the entity.
Definition: gcp.details()
Examples
A Scorecard might include a rule to verify that an entity has GCP details:
gcp.details() != null
You might include a rule to check whether any labels on the GCP recourse are titled origin:
jq(gcp.details(), ".resources[0].labels | any(\"origin\")")
Background sync
Cortex conducts an ownership sync for Google teams every day at 9 a.m. UTC.