Support · Installation · License · Related Integrations
The GCP Certificate Manager Orchestrator Extension remotely manages certificates on the Google Cloud Platform Certificate Manager Product.
This orchestrator extension implements four job types - Inventory, Management Add, Management Remove, and Discovery. It supports adding certificates with private keys only. The orchestrator supports the replacement of unbound certificates as well as certificates bound to existing map entries, but it does not support specifying map entry bindings when adding new certificates.
Every GcpCertMgr store identifies its target Certificate Manager instance through the canonical GCP resource path in Store Path:
projects/{projectId}/locations/{location}
This applies equally to manually-created stores and Discovery-approved stores. The Location custom property is deprecated as of v1.2 and used only as a v1.1 backwards-compatibility fallback. Client Machine is a display label for grouping in Command's UI - the recommended value is the GCP Organization ID.
The Discovery job enumerates every GCP project that the orchestrator's service account can see and proposes one candidate store per (project, location) pair, with Store Path pre-populated in canonical form. The actual scope of discovery is bounded by IAM - grant the service account the appropriate role at the organization root and Discovery will return everything underneath. See the GCP Certificate Manager store-type page for full operator-facing details.
This integration is compatible with Keyfactor Universal Orchestrator version 10.4.1 and later.
The Google Cloud Provider Certificate Manager Universal Orchestrator extension is supported by Keyfactor. If you require support for any issues or have feature request, please open a support ticket by either contacting your Keyfactor representative or via the Keyfactor Support Portal at https://support.keyfactor.com.
If you want to contribute bug fixes or additional enhancements, use the Pull requests tab.
Before installing the Google Cloud Provider Certificate Manager Universal Orchestrator extension, we recommend that you install kfutil. Kfutil is a command-line tool that simplifies the process of creating store types, installing extensions, and instantiating certificate stores in Keyfactor Command.
To use the Google Cloud Provider Certificate Manager Universal Orchestrator extension, you must create the GcpCertMgr Certificate Store Type. This only needs to happen once per Keyfactor Command instance.
The GcpCertMgr store type represents a single (Project, Location) pair within Google Cloud Certificate Manager. The orchestrator manages self-managed certificates inside that container - listing them for inventory, uploading new PFX certificates, and deleting existing certificates by alias.
Every GcpCertMgr store - whether Discovery-approved or manually created - identifies its target Certificate Manager instance through the Store Path field:
projects/{projectId}/locations/{location}
That single value carries both the GCP project and the location (region or global). Inventory and Management read it directly; Client Machine is a display label for grouping in Command's UI and is not parsed by the orchestrator.
| Field | What it carries | Read by |
|---|---|---|
| Store Path | Canonical GCP resource path: projects/{projectId}/locations/{location} |
Inventory, Management, Discovery (emit) |
| Client Machine | Display label only. Recommended: GCP Organization ID (e.g. 1005564431893). Not parsed. |
UI grouping in Command |
| Service Account Key File Path (custom, deprecated) | v1.1 shape only. Leave blank for new stores - authentication uses Application Default Credentials. | Credential loader fallback; emits a deprecation warning when read |
| Location (custom, deprecated) | v1.1 shape only. New stores leave it blank. Used as a fallback when Store Path is empty or n/a. |
v1.1 fallback path; emits a deprecation warning when read |
Set:
- Client Machine: GCP Organization ID
- Store Path:
projects/{projectId}/locations/{location}- e.g.projects/edgecerts/locations/global - Service Account Key File Path: leave blank (deprecated; ADC is used)
- Location: leave blank
Authentication uses Application Default Credentials - see "Service account credentials" below.
Discovery emits one candidate per (project, location) pair in canonical form, so no edits are required on approval - just click SAVE. If Create Certificate Store If Missing is checked on the discovery job, every candidate auto-approves with no operator review. Discovery sets Store Path correctly on each, so all auto-created stores are immediately usable.
Discovery is configured against the GCP Certificate Manager store type and enumerates candidate stores across an entire GCP organization. It uses the Cloud Resource Manager v3 API (projects.search) to list every active project the orchestrator's service account can see, then emits one candidate store path per (project, location) combination.
| Field on the discovery-job form | What to put |
|---|---|
| Client Machine | The GCP Organization ID (e.g. 1005564431893). Logged for traceability; not used as a query filter. |
| Server Username / Server Password | Not used. Leave blank - GCP authentication uses a service account, not username/password. |
| Directories to search | Comma-separated list of GCP locations (regions) to enumerate, e.g. global,us-central1,europe-west1. Leave blank to default to global. |
The candidate count is projects × locations, so be deliberate about how many regions you list - listing 8 regions for an org with 100 projects yields 800 candidate stores, most of which will be empty.
The orchestrator authenticates exclusively via Application Default Credentials. Two supported deployment modes:
- Inside GCP - on a GCE VM or GKE pod with the service account attached via workload identity. ADC discovers the service account from the metadata server automatically. No host configuration needed.
- Outside GCP - on a Windows host or on-prem Linux. Set the
GOOGLE_APPLICATION_CREDENTIALSmachine-level environment variable to the absolute path of the service account's JSON key, then restart the Keyfactor Orchestrator service so it picks up the variable. The account that runs the orchestrator service must have read access to the JSON key file.
The legacy Service Account Key File Path custom store property (a JSON filename relative to the orchestrator extension directory) is deprecated as of v1.2 because the Discovery job has no way to surface custom store properties in Keyfactor Command's discovery-job UI - so file-based auth can't be configured uniformly across all four job types. v1.1 stores with the property populated continue to work, but every job run logs a deprecation warning. The field is scheduled for removal in v2.0; new stores should leave it blank.
The service account needs at minimum:
roles/browserat the organization root - forprojects.searchto see projects nested in folders.roles/certificatemanager.viewerper project (or at the org root for inheritance) - for inventory to list certificates.roles/certificatemanager.editor- for management to add/remove certificates.
Required APIs to enable in the service account's home project:
- Cloud Resource Manager API
- Certificate Manager API (also needs to be enabled in every project you actually inventory)
GCP Certificate Manager constrains certificate resource IDs to a strict shape:
- 1 to 63 characters
- Lowercase letters, digits, hyphens only
- Must start with a lowercase letter
- Must not end with a hyphen
- Regex:
[a-z]([-a-z0-9]*[a-z0-9])?
The orchestrator validates the alias against this rule before any API calls or PFX parsing during Management/Add. A non-conforming alias fails fast with a [FAIL] ValidateAlias step in the flow trace and a suggestion of a normalized alias (e.g. Cert1 → cert1). Rename the certificate in Keyfactor Command to the suggested form and retry the Management/Add job.
Every job (Discovery, Inventory, Management) uses a shared FlowLogger to record step-by-step progress with timing. The flow summary is appended to JobResult.FailureMessage on both success and failure paths so operators reading job history can see what happened without having to pull orchestrator-side trace logs. Errors arising from the GCP SDK are unwrapped through AggregateException walls and reported with HTTP status + the GCP error response body, so quota errors / IAM denials / malformed certificates surface clearly in Command's UI.
A v1.1-shape store has Store Path empty or n/a, Client Machine set to the GCP Project ID, the Location custom property set to the region, and possibly the Service Account Key File Path custom property pointing at a JSON key in the orchestrator extension directory. These continue to work in v1.2 through fallback paths, but every inventory/management run logs deprecation warnings naming the store. To migrate, edit each affected store:
- Set Store Path to
projects/{the-current-Client-Machine-value}/locations/{the-current-Location-value}. - Optionally change Client Machine to the GCP Organization ID for cleaner UI grouping.
- Optionally clear the Location field (no longer required).
- Configure ADC on the orchestrator host (see "Service account credentials") and clear the Service Account Key File Path field.
- Save.
The deprecation warnings will stop on the next job run once the store is fully migrated. Both fallbacks will be removed in v2.0.
In v1.1 the orchestrator built the GCP resource path from Client Machine (= GCP Project ID) + the Location custom property, with Store Path unused (defaulted to n/a). Adding Discovery in v1.2 forced this model to change. Here's why.
The Keyfactor IDiscoveryJobExtension contract emits a plain List<string> of discovered locations - there is no hook to set per-candidate Client Machine values. When an operator approves a discovered candidate (or auto-approval is enabled via the Create Certificate Store If Missing checkbox), Keyfactor Command creates the new store with:
- Store Path = the discovered location string (e.g.
projects/edgecerts/locations/global) - Client Machine = whatever the discovery job's Client Machine was set to - one value shared across every candidate
- Custom properties = their store-type defaults
Under the v1.1 model that meant every Discovery-approved store ended up with the same Client Machine across every project in the organization, which is wrong: each store needs its project ID to make GCP API calls. The first time inventory ran against a Discovery-approved store, that's exactly what produced an HTTP 403 CONSUMER_INVALID error against projects/<orchestrator-hostname>/locations/global - GCP correctly saying "that's not a valid project ID."
| Option | Why we didn't pick it |
|---|---|
| Force the operator to manually edit Client Machine after every Discovery approval | Friction. Discovery should produce working stores without an extra editing step per candidate, especially if the operator wants to use auto-approval. |
| One discovery job per project (so each job's Client Machine = that project's ID) | Impractical: an organization with 100 projects would need 100 discovery jobs, each independently configured and scheduled. |
Have Discovery POST stores directly via Keyfactor Command's REST API instead of the standard SubmitDiscoveryUpdate callback |
Non-standard pattern, much larger code surface, and diverges from how every other Keyfactor orchestrator works - making this orchestrator harder to maintain alongside the rest of the Keyfactor extension catalog. |
| Make Store Path the canonical source for both manual and Discovery flows | Picked. The discovered storepath already encodes both project and location, so reading it directly (instead of reconstructing from Client Machine + Location) means Discovery-approved stores work with zero operator edits, and manually-created stores configure the same way. Smallest code change for the cleanest user-facing schema. |
- Client Machine is now a display label, not load-bearing. Some other Keyfactor orchestrators use Client Machine as a literal target host; for GCP that does not fit, because the orchestrator talks to a single GCP API endpoint regardless of which project a store targets - there is no per-store host to put there. The recommended value (GCP Organization ID) at least groups GCP stores together usefully in Command's UI.
- The Location custom property is deprecated, not removed. Keeping it in the manifest with
Required: falsepreserves v1.1 stores' UI rendering during the transition. The fallback path inJobBase.ResolveGcpResourcePathreads it for v1.1-shaped stores (Store Path blank orn/a) and emits aLogWarningeach time naming the migration step. Removal is scheduled for v2.0. - The Service Account Key File Path custom property is deprecated, not removed, for the same backwards-compatibility reason. Authentication consolidates around Application Default Credentials, the GCP-recommended pattern, which works uniformly across all four job types - the deprecated property only ever worked for Inventory/Management because Discovery's UI doesn't expose store-type custom properties. Removal is scheduled for v2.0.
- Google Cloud Certificate Manager
- Cloud Resource Manager v3 - projects.search
- Application Default Credentials
| Operation | Is Supported |
|---|---|
| Add | ✅ Checked |
| Remove | ✅ Checked |
| Discovery | ✅ Checked |
| Reenrollment | 🔲 Unchecked |
| Create | ✅ Checked |
kfutil is a custom CLI for the Keyfactor Command API and can be used to create certificate store types.
For more information on kfutil check out the docs
Click to expand GcpCertMgr kfutil details
This will reach out to GitHub and pull the latest store-type definition
# GCP Certificate Manager
kfutil store-types create GcpCertMgrIf required, it is possible to create store types from the integration-manifest.json included in this repo. You would first download the integration-manifest.json and then run the following command in your offline environment.
kfutil store-types create --from-file integration-manifest.jsonBelow are instructions on how to create the GcpCertMgr store type manually in the Keyfactor Command Portal
Click to expand manual GcpCertMgr details
Create a store type called GcpCertMgr with the attributes in the tables below:
| Attribute | Value | Description |
|---|---|---|
| Name | GCP Certificate Manager | Display name for the store type (may be customized) |
| Short Name | GcpCertMgr | Short display name for the store type |
| Capability | GcpCertMgr | Store type name orchestrator will register with. Check the box to allow entry of value |
| Supports Add | ✅ Checked | Check the box. Indicates that the Store Type supports Management Add |
| Supports Remove | ✅ Checked | Check the box. Indicates that the Store Type supports Management Remove |
| Supports Discovery | ✅ Checked | Check the box. Indicates that the Store Type supports Discovery |
| Supports Reenrollment | 🔲 Unchecked | Indicates that the Store Type supports Reenrollment |
| Supports Create | ✅ Checked | Check the box. Indicates that the Store Type supports store creation |
| Needs Server | 🔲 Unchecked | Determines if a target server name is required when creating store |
| Blueprint Allowed | 🔲 Unchecked | Determines if store type may be included in an Orchestrator blueprint |
| Uses PowerShell | 🔲 Unchecked | Determines if underlying implementation is PowerShell |
| Requires Store Password | 🔲 Unchecked | Enables users to optionally specify a store password when defining a Certificate Store. |
| Supports Entry Password | 🔲 Unchecked | Determines if an individual entry within a store can have a password. |
The Basic tab should look like this:
| Attribute | Value | Description |
|---|---|---|
| Supports Custom Alias | Required | Determines if an individual entry within a store can have a custom Alias. |
| Private Key Handling | Required | This determines if Keyfactor can send the private key associated with a certificate to the store. Required because IIS certificates without private keys would be invalid. |
| PFX Password Style | Default | 'Default' - PFX password is randomly generated, 'Custom' - PFX password may be specified when the enrollment job is created (Requires the Allow Custom Password application setting to be enabled.) |
The Advanced tab should look like this:
For Keyfactor Command versions 24.4 and later, a Certificate Format dropdown is available with PFX and PEM options. Ensure that PFX is selected, as this determines the format of new and renewed certificates sent to the Orchestrator during a Management job. Currently, all Keyfactor-supported Orchestrator extensions support only PFX.
Custom fields operate at the certificate store level and are used to control how the orchestrator connects to the remote target server containing the certificate store to be managed. The following custom fields should be added to the store type:
| Name | Display Name | Description | Type | Default Value/Options | Required |
|---|---|---|---|---|---|
| Location | Location (deprecated) | Deprecated in v1.2. The GCP location is parsed from Store Path. Leave blank for new stores. v1.1-shape stores (where Store Path is blank or n/a) still read this value as a fallback; expect a deprecation warning in the orchestrator log when that path is used. |
String | 🔲 Unchecked | |
| ServiceAccountKey | Service Account Key File Path (deprecated) | Deprecated in v1.2. Leave blank. Authenticate via Application Default Credentials instead (set GOOGLE_APPLICATION_CREDENTIALS as a machine-level environment variable on the orchestrator host pointing at the JSON key, or run on a GCE VM / GKE pod with workload identity). The Discovery job has no way to surface this custom property in Keyfactor Command's discovery-job UI, so ADC is the only mechanism that works uniformly across all four job types. v1.1 stores that have this populated continue to work via a deprecation-logged fallback; the field is scheduled for removal in v2.0. |
String | 🔲 Unchecked |
The Custom Fields tab should look like this:
Deprecated in v1.2. The GCP location is parsed from Store Path. Leave blank for new stores. v1.1-shape stores (where Store Path is blank or n/a) still read this value as a fallback; expect a deprecation warning in the orchestrator log when that path is used.
Deprecated in v1.2. Leave blank. Authenticate via Application Default Credentials instead (set GOOGLE_APPLICATION_CREDENTIALS as a machine-level environment variable on the orchestrator host pointing at the JSON key, or run on a GCE VM / GKE pod with workload identity). The Discovery job has no way to surface this custom property in Keyfactor Command's discovery-job UI, so ADC is the only mechanism that works uniformly across all four job types. v1.1 stores that have this populated continue to work via a deprecation-logged fallback; the field is scheduled for removal in v2.0.
-
Download the latest Google Cloud Provider Certificate Manager Universal Orchestrator extension from GitHub.
Navigate to the Google Cloud Provider Certificate Manager Universal Orchestrator extension GitHub version page. Refer to the compatibility matrix below to determine the asset should be downloaded. Then, click the corresponding asset to download the zip archive.
Universal Orchestrator Version Latest .NET version installed on the Universal Orchestrator server rollForwardcondition inOrchestrator.runtimeconfig.jsongcp-certmanager-orchestrator.NET version to downloadOlder than 11.0.0net6.0Between 11.0.0and11.5.1(inclusive)net6.0net6.0Between 11.0.0and11.5.1(inclusive)net8.0Disablenet6.011.6and newernet8.0net8.0Unzip the archive containing extension assemblies to a known location.
Note If you don't see an asset with a corresponding .NET version, you should always assume that it was compiled for
net6.0. -
Locate the Universal Orchestrator extensions directory.
- Default on Windows -
C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions - Default on Linux -
/opt/keyfactor/orchestrator/extensions
- Default on Windows -
-
Create a new directory for the Google Cloud Provider Certificate Manager Universal Orchestrator extension inside the extensions directory.
Create a new directory called
gcp-certmanager-orchestrator.The directory name does not need to match any names used elsewhere; it just has to be unique within the extensions directory.
-
Copy the contents of the downloaded and unzipped assemblies from step 2 to the
gcp-certmanager-orchestratordirectory. -
Restart the Universal Orchestrator service.
Refer to Starting/Restarting the Universal Orchestrator service.
The above installation steps can be supplemented by the official Command documentation.
Click to expand details
-
Navigate to the Certificate Stores page in Keyfactor Command.
Log into Keyfactor Command, toggle the Locations dropdown, and click Certificate Stores.
-
Add a Certificate Store.
Click the Add button to add a new Certificate Store. Use the table below to populate the Attributes in the Add form.
Attribute Description Category Select "GCP Certificate Manager" or the customized certificate store name from the previous step. Container Optional container to associate certificate store with. Client Machine Display label for grouping certificate stores in Keyfactor Command. Recommended value is the GCP Organization ID (e.g. 1005564431893); the orchestrator does not parse a project ID out of this field. The actual GCP project + location are read from Store Path.Store Path Canonical GCP resource path in the form projects/{projectId}/locations/{location}(e.g.projects/edgecerts/locations/global). This is the single source of truth for which Certificate Manager instance the store targets. For Discovery-approved stores Keyfactor Command auto-fills this from the discovered candidate; for manually-created stores the operator types it directly.Orchestrator Select an approved orchestrator capable of managing GcpCertMgrcertificates. Specifically, one with theGcpCertMgrcapability.Location Deprecated in v1.2. The GCP location is parsed from Store Path. Leave blank for new stores. v1.1-shape stores (where Store Path is blank or n/a) still read this value as a fallback; expect a deprecation warning in the orchestrator log when that path is used.ServiceAccountKey Deprecated in v1.2. Leave blank. Authenticate via Application Default Credentials instead (set GOOGLE_APPLICATION_CREDENTIALSas a machine-level environment variable on the orchestrator host pointing at the JSON key, or run on a GCE VM / GKE pod with workload identity). The Discovery job has no way to surface this custom property in Keyfactor Command's discovery-job UI, so ADC is the only mechanism that works uniformly across all four job types. v1.1 stores that have this populated continue to work via a deprecation-logged fallback; the field is scheduled for removal in v2.0.
Click to expand details
-
Generate a CSV template for the GcpCertMgr certificate store
kfutil stores import generate-template --store-type-name GcpCertMgr --outpath GcpCertMgr.csv
-
Populate the generated CSV file
Open the CSV file, and reference the table below to populate parameters for each Attribute.
Attribute Description Category Select "GCP Certificate Manager" or the customized certificate store name from the previous step. Container Optional container to associate certificate store with. Client Machine Display label for grouping certificate stores in Keyfactor Command. Recommended value is the GCP Organization ID (e.g. 1005564431893); the orchestrator does not parse a project ID out of this field. The actual GCP project + location are read from Store Path.Store Path Canonical GCP resource path in the form projects/{projectId}/locations/{location}(e.g.projects/edgecerts/locations/global). This is the single source of truth for which Certificate Manager instance the store targets. For Discovery-approved stores Keyfactor Command auto-fills this from the discovered candidate; for manually-created stores the operator types it directly.Orchestrator Select an approved orchestrator capable of managing GcpCertMgrcertificates. Specifically, one with theGcpCertMgrcapability.Properties.Location Deprecated in v1.2. The GCP location is parsed from Store Path. Leave blank for new stores. v1.1-shape stores (where Store Path is blank or n/a) still read this value as a fallback; expect a deprecation warning in the orchestrator log when that path is used.Properties.ServiceAccountKey Deprecated in v1.2. Leave blank. Authenticate via Application Default Credentials instead (set GOOGLE_APPLICATION_CREDENTIALSas a machine-level environment variable on the orchestrator host pointing at the JSON key, or run on a GCE VM / GKE pod with workload identity). The Discovery job has no way to surface this custom property in Keyfactor Command's discovery-job UI, so ADC is the only mechanism that works uniformly across all four job types. v1.1 stores that have this populated continue to work via a deprecation-logged fallback; the field is scheduled for removal in v2.0. -
Import the CSV file to create the certificate stores
kfutil stores import csv --store-type-name GcpCertMgr --file GcpCertMgr.csv
The content in this section can be supplemented by the official Command documentation.
Before configuring the orchestrator, make sure your Google Cloud project is ready. Read the official Google Certificate Manager documentation for product background. The steps below are intentionally text-only; Google's Cloud Console UI changes regularly and the underlying APIs and gcloud commands are the stable interface.
In the project that will host the orchestrator's service account ("the SA project"), enable both:
- Cloud Resource Manager API - lets the Discovery job enumerate projects via
projects.search. Required even if you only use Inventory/Management today, because the API enablement check runs against the SA project regardless of what target project the call reads. - Certificate Manager API - read/write access to certificate resources. This must additionally be enabled in every project you intend to inventory or manage certs in.
gcloud (one-shot for both APIs in the SA project):
gcloud services enable cloudresourcemanager.googleapis.com certificatemanager.googleapis.com --project=<sa-project-id>
Service account credentials are identity, not authorization - the IAM bindings determine what the SA can see and do. Bind these roles at the organization so the SA inherits visibility into every folder and project:
| Role | Why |
|---|---|
roles/browser |
So projects.search returns projects nested in folders, not just top-level projects |
roles/certificatemanager.viewer |
Inventory: list certificates in each store |
roles/certificatemanager.editor |
Management/Add and Management/Remove |
gcloud iam service-accounts create kf-orchestrator \
--project=<sa-project-id> \
--display-name="Keyfactor Universal Orchestrator"
ORG=<organization-id>
SA=kf-orchestrator@<sa-project-id>.iam.gserviceaccount.com
gcloud organizations add-iam-policy-binding $ORG --member="serviceAccount:$SA" --role="roles/browser"
gcloud organizations add-iam-policy-binding $ORG --member="serviceAccount:$SA" --role="roles/certificatemanager.viewer"
gcloud organizations add-iam-policy-binding $ORG --member="serviceAccount:$SA" --role="roles/certificatemanager.editor"
The orchestrator authenticates exclusively via Application Default Credentials (ADC). There are two supported deployment modes:
Orchestrator runs inside GCP (recommended) - on a GCE VM or GKE pod with the service account attached via workload identity. ADC discovers the service account from the metadata server automatically. No further configuration on the host.
Orchestrator runs outside GCP - on a Windows host, on-prem Linux, etc.:
- Create a JSON key for the service account:
gcloud iam service-accounts keys create kf-orchestrator.json --iam-account=$SA. Google never re-displays this key, so save it somewhere safe. - Copy the JSON key to a secured location on the orchestrator host. Lock down filesystem permissions so only the account that runs the Keyfactor Orchestrator service can read it.
- Set the
GOOGLE_APPLICATION_CREDENTIALSmachine-level environment variable to the absolute path of the JSON key. Restart the Keyfactor Orchestrator service so it picks up the variable.
Note on the deprecated
Service Account Key File Pathstore property. Earlier versions of the orchestrator accepted a JSON filename in a per-store custom property and read the file from the orchestrator extension directory. That mechanism is deprecated in v1.2 because the Discovery job has no way to surface custom store properties in Keyfactor Command's discovery-job UI - so file-based auth can't be configured uniformly across all four job types. Existing v1.1 stores with the property populated continue to work, but every job run logs a deprecation warning. The field is scheduled for removal in v2.0.
Apache License 2.0, see LICENSE.






