ICF 1.5.20.35

Google Vertex AI connector

Google Vertex AI is Google Cloud’s platform for building and deploying AI agents. The Google Vertex AI connector is a read-only connector that discovers Google Cloud AI agents, including Dialogflow CX agents and Vertex AI Agent Engine reasoning engines, and governance-relevant objects including tools, knowledge bases, guardrails, identity bindings, service accounts, and tool credentials.

Contact your Ping Identity Customer Success Outcome Manager (CSOM) or Account Executive to obtain this connector.

Retrieval of agentIdentityBinding, serviceAccount, and agentToolCredential is enabled through an offline inventory mechanism that requires an Agent Governance license. Contact your CSOM for details.

Google Vertex AI requirements

The Google Vertex AI connector is read-only. It needs Google Cloud read permissions for the configured project, location, and API flavor.

Use the narrowest permissions your environment allows. The following is a starting point:

roles/dialogflow.reader
roles/aiplatform.viewer

If org-wide discovery is enabled with useCloudAssetApi=true, the connector principal also needs:

cloudasset.assets.searchAllResources

The connector doesn’t need project-wide IAM policy collection permissions when the companion inventory job is deployed. IAM policy scanning belongs to the offline inventory job, not to the connector.

Offline inventory job permissions

The offline inventory job writes identity binding, service account, and tool credential artifacts to GCS. The job service account typically needs:

roles/dialogflow.viewer
roles/aiplatform.viewer
roles/iam.securityReviewer
roles/storage.objectAdmin

The connector reads the generated artifacts through per-artifact pre-signed GCS URLs.

Before you configure the connector, confirm you have the following:

Requirement Value

Dialogflow CX agents or Vertex AI Agent Engine reasoning engines

Configured in the target GCP project and location

GCP project ID

Required

GCP location

Required

Service account key JSON

Required by the current implementation

GCS inventory artifacts

Required for identity bindings, service accounts, and tool credentials

Companion inventory job

Required if you want agentIdentityBinding, serviceAccount, or agentToolCredential populated

Install the Google Vertex AI connector

To check for an Advanced Identity Cloud application for this connector, refer to:

To obtain the connector .jar file, contact your Ping Identity Customer Success Outcome Manager (CSOM) or Account Executive.

  • If you’re running the connector locally, place the .jar file in the /path/to/openidm/connectors directory.

  • If you’re using a remote connector server (RCS), place the .jar file in the /path/to/openicf/connectors directory on the RCS.

Configure the Google Vertex AI connector

Create a connector configuration using the IDM admin UI:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type list, select Google Vertex AI Connector - 1.5.20.33.

  5. Complete the Base Connector Details and any applicable Additional Options.

    For a list of all configuration properties, refer to Google Vertex AI Connector Configuration.

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Connection details

The Google Vertex AI connector uses the following configuration properties:

Property Type Required Default Description

projectId

String

Yes

None

GCP project ID.

location

String

Yes

None

GCP location, for example us-central1.

agentApiFlavor

String

No

dialogflowcx

Agent API flavor. Allowed values are dialogflowcx, vertexai, and both.

useWorkloadIdentity

Boolean

Yes

false

When true, authenticates using Application Default Credentials (ADC) or Workload Identity Federation. When false, provide serviceAccountKeyJson.

serviceAccountKeyJson

GuardedString

Conditional

None

Full service account key JSON. Required when useWorkloadIdentity=false.

identityBindingScanEnabled

Boolean

No

false

Enables GCS-backed agentIdentityBinding, serviceAccount, and agentToolCredential reconciliation.

agentNameFilterRegex

String

No

None

Optional regex filter applied to agent display names.

organizationId

String

Conditional

None

GCP organization ID. Required when useCloudAssetApi=true.

gcsIdentityBindingsUrl

String

Conditional

None

Pre-signed GCS URL for identity-bindings.json. Required when identityBindingScanEnabled=true.

gcsServiceAccountsUrl

String

Conditional

None

Pre-signed GCS URL for service-accounts.json. Required when identityBindingScanEnabled=true.

gcsToolCredentialsUrl

String

Conditional

None

Pre-signed GCS URL for tool-credentials.json. Required when identityBindingScanEnabled=true.

useCloudAssetApi

Boolean

No

false

Enables org-wide agent discovery through Cloud Asset API. Requires organizationId.
The configuration exposes useWorkloadIdentity, but the current client implementation throws an exception when workload identity is selected. Configure useWorkloadIdentity=false and provide serviceAccountKeyJson until workload identity / ADC support is implemented.

Example Google Vertex AI configuration

{
  "connectorRef": {
    "bundleName": "org.forgerock.openicf.connectors.googlevertexai-connector",
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "connectorName": "org.forgerock.openicf.connectors.googlevertexai.GoogleVertexAIConnector"
  },
  "configurationProperties": {
    "projectId": "my-gcp-project",
    "location": "us-central1",
    "agentApiFlavor": "both",
    "useWorkloadIdentity": false,
    "serviceAccountKeyJson": {
      "$crypto": {
        "type": "x-simple-encryption",
        "value": {
          "cipher": "...",
          "data": "...",
          "iv": "...",
          "key": "openidm-sym-default"
        }
      }
    },
    "identityBindingScanEnabled": true,
    "gcsIdentityBindingsUrl": "https://storage.googleapis.com/.../identity-bindings.json?...",
    "gcsServiceAccountsUrl": "https://storage.googleapis.com/.../service-accounts.json?...",
    "gcsToolCredentialsUrl": "https://storage.googleapis.com/.../tool-credentials.json?...",
    "useCloudAssetApi": false,
    "agentNameFilterRegex": ".*"
  }
}

Test the Google Vertex AI connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/googlevertexai?_action=test"
{
  "name": "googlevertexai",
  "enabled": true,
  "config": "config/provisioner.openicf/googlevertexai",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.googlevertexai-connector",
    "connectorName": "org.forgerock.openicf.connectors.googlevertexai.GoogleVertexAIConnector"
  },
  "displayName": "Google Vertex AI Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector has been configured correctly and can authenticate to the Google Cloud APIs.

TestOp validates connectivity by listing one page of agents. It doesn’t prove that the GCS inventory artifacts exist. Verify GCS inventory separately when validating identity bindings, service accounts, or tool credentials.

Google Vertex AI remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Google Vertex AI connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

Refer to Remote connectors for configuring the Google Vertex AI remote connector.

Implementation specifics

Collection architecture

The Google Vertex AI connector uses a split collection model.

Live collection runs inside the Java connector during reconciliation, calling Google Cloud APIs to list agents, tools, data stores, and guardrail-like safety settings.

Offline collection is handled by the companion vertex-tools-inventory process. That process scans IAM policies and service account metadata, writes normalized JSON artifacts to GCS, and the connector reads those artifacts during reconciliation. This split keeps reconciliation fast and avoids giving the connector broad IAM enumeration permissions.

Live data

Data GCP API family

Dialogflow CX agents

Dialogflow CX API

Vertex AI Agent Engine reasoning engines

Vertex AI API

Tools

Dialogflow CX tools API

Webhooks

Dialogflow CX webhooks API

Knowledge bases / data stores

Dialogflow CX data stores API

Guardrail-like safety settings

Derived from agent safety settings

Org-wide resource discovery

Cloud Asset API, only when useCloudAssetApi=true

GCS inventory data

The connector reads these GCS artifact URLs when identityBindingScanEnabled=true:

Artifact Configuration property Used for

Identity bindings

gcsIdentityBindingsUrl

agentIdentityBinding, identityBindingIds

Service accounts

gcsServiceAccountsUrl

serviceAccount, serviceAccountIds

Tool credentials

gcsToolCredentialsUrl

agentToolCredential, toolCredentialIds

The connector expects each URL to point to a JSON array artifact produced by the offline inventory job.

GCS inventory behavior

Behavior Description

Identity binding source

gcsIdentityBindingsUrl.

Service account source

gcsServiceAccountsUrl.

Tool credential source

gcsToolCredentialsUrl.

Inventory format

Each artifact is expected to be a bare JSON array.

URL type

Pre-signed GCS URL.

Missing URL

Configuration validation fails when identityBindingScanEnabled=true.

Failed GCS read

Reconciliation fails with an exception. The connector doesn’t silently return empty offline-backed records.

Forward pointers

Agent objects are enriched with identityBindingIds, serviceAccountIds, and toolCredentialIds from the same GCS artifacts.

Use the Google Vertex AI connector

The Google Vertex AI connector discovers the following resource types:

ICF Native Type Google Cloud Resource Type Naming Attribute Notes

__ACCOUNT__

Dialogflow CX Agent or Vertex AI Agent Engine reasoning engine

__NAME__

Represents one AI agent. UID is the short ID extracted from the full resource name.

agentTool

Dialogflow CX Tool or Webhook

__NAME__

Represents tools and webhooks attached to Dialogflow CX agents. Vertex AI Agent Engine agents currently return no live tool records from this path.

agentKnowledgeBase

Dialogflow CX Data Store connection

__NAME__

Represents a data store connection attached to an agent.

agentGuardrail

Synthetic guardrail derived from agent safety settings

__NAME__

Not a standalone Google Cloud resource. The connector creates this object when agent safety settings are available.

agentIdentityBinding

Derived IAM principal-to-agent binding

__NAME__

Not a native agent resource. Read from the offline identity-bindings.json artifact.

serviceAccount

Google Cloud IAM service account

__NAME__

Read from the offline service-accounts.json artifact.

agentToolCredential

Derived tool credential metadata

__NAME__

Not a native agent resource. Read from the offline tool-credentials.json artifact.

__ACCOUNT__ attributes

Attribute Type Multivalued Description

platform

String

No

Connector platform identifier. Current value is GOOGLE_VERTEX_AI.

agentId

String

No

Full Google Cloud agent resource name.

description

String

No

Agent description.

foundationModel

String

No

Generative model / foundation model, when exposed by the API.

defaultLanguageCode

String

No

Default language code.

timeZone

String

No

Agent time zone.

startFlow

String

No

Dialogflow CX start flow, when present.

startPlaybook

String

No

Playbook-based start target, when present.

createdAt

String

No

Agent creation timestamp.

updatedAt

String

No

Agent update timestamp.

safetySettings

String

No

Raw or serialized safety settings.

toolIds

String

Yes

Forward pointers to agentTool objects.

knowledgeBaseIds

String

Yes

Forward pointers to agentKnowledgeBase objects.

guardrailId

String

No

Forward pointer to the synthetic agentGuardrail object.

agentFramework

String

No

Vertex AI Agent Engine framework, when present.

serviceAccount

String

No

Runtime service account, when exposed by the agent API.

projectId

String

No

Project ID extracted from the resource name.

region

String

No

Region/location extracted from the resource name.

identityBindingIds

String

Yes

Forward pointers to agentIdentityBinding records from GCS inventory.

serviceAccountIds

String

Yes

Forward pointers to serviceAccount records from GCS inventory.

toolCredentialIds

String

Yes

Forward pointers to agentToolCredential records from GCS inventory.

agentTool attributes

Attribute Type Multivalued Description

agentId

String

No

Parent agent resource name.

description

String

No

Tool or webhook description.

toolType

String

No

Tool classification, such as tool, webhook, or data-store-related tool.

endpoint

String

No

Tool or webhook endpoint, when present.

projectId

String

No

Project ID extracted from the tool resource name.

region

String

No

Region/location extracted from the tool resource name.

agentKnowledgeBase attributes

Attribute Type Multivalued Description

platform

String

No

Connector platform identifier.

knowledgeBaseId

String

No

Full data store resource name.

knowledgeBaseState

String

No

Data store status/state.

dataStoreType

String

No

Data store type.

agentId

String

No

Parent agent resource name.

projectId

String

No

Project ID extracted from the data store resource name.

region

String

No

Region/location extracted from the data store resource name.

agentGuardrail attributes

Attribute Type Multivalued Description

platform

String

No

Connector platform identifier.

agentId

String

No

Parent agent resource name.

safetyEnforcement

String

No

Safety enforcement mode, when present.

bannedPhrases

String

Yes

Configured banned phrases.

defaultBannedPhrases

String

Yes

Default banned phrases.

rawSettingsJson

String

No

Raw serialized safety settings.

agentIdentityBinding attributes

Attribute Type Multivalued Description

platform

String

No

Connector platform identifier.

agentId

String

No

Agent ID from the inventory artifact.

agentVersion

String

No

Agent version from the inventory artifact.

kind

String

No

Principal type from the inventory artifact.

principal

String

No

Principal value.

permissions

String

Yes

Permissions associated with the binding.

scope

String

No

Scope type from the inventory artifact.

iamRole

String

No

IAM role associated with the binding.

iamMember

String

No

IAM member string associated with the binding.

scopeResourceName

String

No

Scope resource name from the inventory artifact.

sourceTag

String

No

Source tag from the inventory artifact.

confidence

String

No

Confidence value from the inventory artifact.

flavor

String

No

Agent flavor from the inventory artifact.

expanded

Boolean

No

Whether the principal was expanded by the inventory process.

serviceAccount attributes

Attribute Type Multivalued Description

platform

String

No

Connector platform identifier.

email

String

No

Service account email.

description

String

No

Service account description.

displayName

String

No

Service account display name.

saProjectId

String

No

Project ID of the service account.

uniqueId

String

No

Service account unique ID.

createdAt

String

No

Service account creation timestamp.

oauth2ClientId

String

No

OAuth2 client ID.

disabled

Boolean

No

Whether the service account is disabled.

keys

String

No

Serialized key metadata from the inventory artifact.

keyCount

Integer

No

Number of keys reported by the inventory artifact.

linkedAgentIds

String

Yes

Agent IDs linked to this service account.

agentToolCredential attributes

Attribute Type Multivalued Description

toolId

String

No

Tool ID from the inventory artifact.

toolKey

String

No

Tool key from the inventory artifact.

toolType

String

No

Tool type from the inventory artifact.

agentId

String

No

Parent agent ID from the inventory artifact.

authType

String

No

Authentication type.

credentialRef

String

No

Credential reference. Doesn’t contain secret material.

tcProjectId

String

No

Project ID from the tool credential artifact.

tcLocation

String

No

Location from the tool credential artifact.

Troubleshooting

Connector initializes but test fails

Check:

  1. projectId is valid.

  2. location is valid for the selected API flavor.

  3. agentApiFlavor is one of dialogflowcx, vertexai, or both.

  4. useWorkloadIdentity=false is configured and serviceAccountKeyJson is present and valid.

  5. The service account has roles/dialogflow.reader and/or roles/aiplatform.viewer.

  6. The target project and location contain the expected agent resources.

Agents reconcile but expected agents are missing

Check:

  1. agentApiFlavor is correct. Use both if you need Dialogflow CX agents and Vertex AI Agent Engine reasoning engines.

  2. location matches where the agents are deployed.

  3. agentNameFilterRegex is not excluding the agents.

  4. If useCloudAssetApi=true, organizationId is configured and the connector principal can call Cloud Asset API.

  5. The service account has reader/viewer permission on all target projects.

agentTool returns no records

Check:

  1. The agent is a Dialogflow CX agent. Vertex AI Agent Engine agents currently return no live tool records from this connector path.

  2. The agent has tools or webhooks configured.

  3. The connector service account can read Dialogflow CX sub-resources.

  4. The selected agentApiFlavor includes Dialogflow CX.

agentKnowledgeBase returns no records

Check:

  1. The agent has Dialogflow CX data store connections.

  2. The selected agentApiFlavor includes Dialogflow CX.

  3. The connector service account can read the relevant data store resources.

  4. Some console-created agents may expose data store behavior as tools rather than agentKnowledgeBase records.

agentGuardrail returns no records

Check:

  1. The agent API response includes safety settings.

  2. The configured agent actually has guardrail-relevant safety settings exposed through the API.

  3. Current console-created agents may not expose generativeSettings in the agent GET response even when safety is configured in the UI.

agentIdentityBinding, serviceAccount, or agentToolCredential returns no records

Check:

  1. identityBindingScanEnabled is set to true.

  2. All three GCS URL properties are configured.

  3. The pre-signed GCS URLs haven’t expired.

  4. The offline inventory job has run successfully.

  5. The GCS artifacts are bare JSON arrays.

  6. The connector can access the URLs from its runtime network.

  7. The inventory job found IAM bindings, service accounts, or tool credentials for the selected project/location.

GCS-backed reconciliation fails

Check:

  1. The GCS signed URL is still valid.

  2. The URL points to the latest artifact, not a stale or deleted run path.

  3. The artifact is valid JSON.

  4. The artifact schema matches the connector mapping.

  5. If URLs are rotated, the connector configuration has been updated with the new values.

OpenICF interfaces implemented by the Google Vertex AI connector

The Google Vertex AI connector implements the following OpenICF interfaces. You can find additional details in ICF interfaces:

Schema

Describes the object types, operations, and options that the connector supports.

Search

Searches the target resource for all objects that match the specified object class and filter.

Test

Tests the connector configuration.

Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Google Vertex AI connector configuration

The Google Vertex AI connector has the following configurable properties:

Basic configuration properties

Property Type Default Encrypted(1) Required(2)

projectId

String

null

Yes

Google Cloud project ID where agents are deployed.

location

String

null

Yes

GCP region for the API, e.g. us-central1 or global.

agentApiFlavor

String

dialogflowcx

No

Which Google Cloud agent API to use. dialogflowcx for Dialogflow CX agents (default). vertexai for Vertex AI Agent Engine (reasoningEngines). both to discover agents from both APIs. When using vertexai or both, the agentTool and agentKnowledgeBase object classes return empty results for Vertex AI Agent Engine agents as these are not exposed as sub-resources.

useWorkloadIdentity

Boolean

false

Yes

If true, authenticate using Application Default Credentials (ADC) or Workload Identity Federation. If false, a service account key JSON is required.

serviceAccountKeyJson

GuardedString

null

Yes

No

Full JSON key file content for a GCP service account. Required when useWorkloadIdentity is false.

identityBindingScanEnabled

Boolean

false

No

When true, the connector reads identity binding, service account, and tool credential artifacts from GCS using the three per-artifact pre-signed URLs. When false (default), agentIdentityBinding, serviceAccount, and agentToolCredential searches return no data. All three GCS URL properties are required when this is true.

agentNameFilterRegex

String

null

No

Optional regular expression to filter which agents are returned during discovery based on displayName.

organizationId

String

null

No

GCP organization ID (10-digit numeric) for org-wide agent discovery via Cloud Asset API. Required when useCloudAssetApi is enabled. Requires roles/cloudasset.viewer at the organization level.

gcsIdentityBindingsUrl

String

null

No

Full pre-signed GCS URL for identity-bindings.json produced by the offline Python inventory job. Required when identityBindingScanEnabled is true. The URL must be self-authenticating (pre-signed); no Authorization header is sent. Recommended TTL: 7 days.

gcsServiceAccountsUrl

String

null

No

Full pre-signed GCS URL for service-accounts.json produced by the offline Python inventory job. Required when identityBindingScanEnabled is true. The URL must be self-authenticating (pre-signed); no Authorization header is sent. Recommended TTL: 7 days.

gcsToolCredentialsUrl

String

null

No

Full pre-signed GCS URL for tool-credentials.json produced by the offline Python inventory job. Required when identityBindingScanEnabled is true. The URL must be self-authenticating (pre-signed); no Authorization header is sent. Recommended TTL: 7 days.

useCloudAssetApi

Boolean

false

No

When enabled, the connector uses Cloud Asset API to discover AI agents (Dialogflow CX and Vertex AI Agent Engine) across all projects in the organization. Requires organizationId to be set and roles/cloudasset.viewer at the organization level. Provides multi-region support automatically.

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.