feat: add Scope custom store property for GCP Certificate Manager

GCP Certificate Manager's `scope` field is create-only and immutable.
Previous releases hard-coded `Scope = "DEFAULT"` on every certificate
created, which made the orchestrator unusable for environments running
cross-region internal Application Load Balancers (`ALL_REGIONS`), Media
CDN (`EDGE_CACHE`), or mTLS trust configs (`CLIENT_AUTH`). Affected
customers had to pre-create empty placeholder certificate resources in
GCP via Terraform with the right scope, then point Keyfactor at the
shell - breaking the single-pane-of-glass workflow.

Adds a `Scope` custom store property honored by Management/Add. Values
are case-normalized and validated against the four-value enum GCP
accepts; an unsupported value fails the `ResolveScope` flow step before
any API call. Blank resolves to `DEFAULT` so existing stores keep
working with no operator action.

Replace (overwrite) intentionally does not propagate scope: the patch
UpdateMask is "SelfManaged", and GCP would reject a scope change
anyway. The recommended pattern is one store per (project, location,
scope) tuple.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bhillkeyfactor

CHANGELOG.md

@@ -110,6 +110,29 @@ v1.2.0 - unreleased
   replacing the previous behavior of failing 700ms later with a wall-of-JSON
   HTTP 400 from GCP. See `JobBase.ValidateGcpCertificateId`.
 
+### Added (Scope custom property)
+- Added a new `Scope` custom store property that is honored by Management/Add.
+  Previous releases hard-coded `Scope = "DEFAULT"` on every certificate created
+  in GCP, which made the orchestrator unusable for environments that depend on
+  cross-region internal Application Load Balancers (`ALL_REGIONS`), Media CDN
+  (`EDGE_CACHE`), or mTLS trust-config / authorized-client server certs
+  (`CLIENT_AUTH`). Those customers had to pre-create empty placeholder
+  certificates in GCP via Terraform and then attach Keyfactor to the existing
+  shell. The new property lets a single store create certificates at any of
+  the four allowed scopes natively.
+  - Allowed values: `DEFAULT`, `ALL_REGIONS`, `EDGE_CACHE`, `CLIENT_AUTH`.
+    Values are case-normalized (uppercased and trimmed) before validation.
+    Anything else fails the `ResolveScope` flow step before any API call.
+  - Default is `DEFAULT`. Blank also resolves to `DEFAULT`, so existing v1.1
+    and v1.2-pre-Scope stores keep working with no operator action.
+  - GCP's Scope field is **create-only and immutable**. Replace (overwrite)
+    paths do not change scope: the `Patch` call's `UpdateMask` is `SelfManaged`,
+    so GCP only updates the cert/key bytes. To change a certificate's scope,
+    delete the certificate and re-add it.
+  - Recommended deployment pattern is one store per (project, location, scope)
+    tuple. Mixing scopes inside a single store is awkward because the property
+    is store-wide, not per-cert.
+
 ### Backwards compatibility
 - v1.1-shape stores (Store Path blank or `n/a`, Client Machine = Project ID,
   Location custom property = region) continue to work via a deprecation-logged

GcpCertManager/Jobs/JobBase.cs

@@ -212,6 +212,41 @@ protected static void ValidateGcpCertificateId(string alias)
             }
         }
 
+        // GCP Certificate Manager's create-only Scope values. Anything else produces an
+        // HTTP 400 INVALID_ARGUMENT from the create call, so validate up front and reject
+        // typos with a clear message instead of letting them reach the API.
+        // Source: https://cloud.google.com/certificate-manager/docs/reference/rest/v1/projects.locations.certificates#Certificate.Scope
+        private static readonly System.Collections.Generic.HashSet<string> AllowedScopes =
+            new System.Collections.Generic.HashSet<string>(StringComparer.Ordinal)
+            {
+                "DEFAULT",
+                "EDGE_CACHE",
+                "ALL_REGIONS",
+                "CLIENT_AUTH"
+            };
+
+        /// <summary>
+        /// Normalize the per-store <c>Scope</c> custom property to a value GCP will
+        /// accept. Blank → <c>DEFAULT</c> (matches pre-v1.2 behavior, so unmigrated
+        /// stores keep working). Other values are uppercased and validated against the
+        /// set GCP allows; an unknown value throws <see cref="ArgumentException"/> so
+        /// the operator sees a clear failure before any API call.
+        /// </summary>
+        protected static string ResolveScope(string configuredScope)
+        {
+            if (string.IsNullOrWhiteSpace(configuredScope)) return "DEFAULT";
+
+            var normalized = configuredScope.Trim().ToUpperInvariant();
+            if (!AllowedScopes.Contains(normalized))
+            {
+                throw new ArgumentException(
+                    $"Unsupported Scope '{configuredScope}'. GCP Certificate Manager accepts only " +
+                    "DEFAULT, EDGE_CACHE, ALL_REGIONS, or CLIENT_AUTH. Edit the store's Scope custom property and retry.",
+                    nameof(configuredScope));
+            }
+            return normalized;
+        }
+
         private static string SuggestValidAlias(string alias)
         {
             if (string.IsNullOrEmpty(alias)) return "cert";

GcpCertManager/Jobs/Management.cs

@@ -90,6 +90,7 @@ private JobResult PerformManagement(ManagementJobConfiguration config, FlowLogge
             Logger.LogTrace("  Location: {Location}", storeProperties.Location);
             Logger.LogTrace("  Project Id: {ProjectId}", storeProperties.ProjectId);
             Logger.LogTrace("  Service Account Key Path: {ServiceAccountKey}", storeProperties.ServiceAccountKey);
+            Logger.LogTrace("  Scope: {Scope}", storeProperties.Scope);
 
             CertificateManagerService svc = null;
             flow.Step("GetGoogleCredentials", () =>
@@ -108,7 +109,7 @@ private JobResult PerformManagement(ManagementJobConfiguration config, FlowLogge
             {
                 case CertStoreOperationType.Add:
                     flow.Branch("Add");
-                    try { return PerformAddition(svc, config, storePath, flow); }
+                    try { return PerformAddition(svc, config, storeProperties, storePath, flow); }
                     finally { flow.EndBranch(); }
                 case CertStoreOperationType.Remove:
                     flow.Branch("Remove");
@@ -129,14 +130,20 @@ private JobResult PerformRemoval(CertificateManagerService svc, ManagementJobCon
         }
 
         private JobResult PerformAddition(CertificateManagerService svc, ManagementJobConfiguration config,
-            string storePath, FlowLogger flow)
+            StoreProperties storeProperties, string storePath, FlowLogger flow)
         {
             // Validate the alias before any API calls or PFX parsing - GCP rejects
             // non-conforming IDs with HTTP 400 after we've already done the expensive
             // work, so failing fast saves both time and a confusing error message.
             flow.Step("ValidateAlias", () => ValidateGcpCertificateId(CertificateName),
                 $"alias={CertificateName}");
 
+            // Resolve the per-store Scope custom property up front. GCP's Scope field is
+            // create-only, so the value has to be correct before we touch the API.
+            string resolvedScope = null;
+            flow.Step("ResolveScope", () => resolvedScope = ResolveScope(storeProperties.Scope),
+                $"configured={storeProperties.Scope ?? "<blank>"}");
+
             var duplicate = false;
             flow.Step("CheckForDuplicate", () => duplicate = CheckForDuplicate(storePath, CertificateName, svc),
                 $"alias={CertificateName}");
@@ -219,15 +226,17 @@ private JobResult PerformAddition(CertificateManagerService svc, ManagementJobCo
 
             // Build the GCP certificate object. Don't serialize+log; that would leak the
             // private key into trace logs.
+            //
+            // Scope is sourced from the per-store custom property and is honored only on
+            // Add. On Replace the patch's UpdateMask is "SelfManaged", so GCP ignores
+            // every other field on the body (including Scope) - which is correct, since
+            // GCP rejects scope changes anyway.
             var gCertificate = new Certificate
             {
                 SelfManaged = new SelfManagedCertificate { PemCertificate = pubCertPem, PemPrivateKey = privateKeyString },
                 Name = CertificateName,
                 Description = CertificateName,
-                // Scope does not come back in inventory, so hard-code it. Customers
-                // running edge-cache stores will need to override this in a future
-                // store-property if/when that scope becomes used.
-                Scope = "DEFAULT"
+                Scope = resolvedScope
             };
 
             if (duplicate && config.Overwrite)

GcpCertManager/StoreProperties.cs

@@ -17,5 +17,13 @@ internal class StoreProperties
         public string ProjectId { get; set; }
 
         public string ServiceAccountKey { get; set; }
+
+        // GCP Certificate Manager's Scope field is create-only and immutable. Blank
+        // means "let JobBase.ResolveScope pick DEFAULT" so existing stores upgrade
+        // without operator intervention. Non-default scopes (ALL_REGIONS for
+        // cross-region internal ALBs, EDGE_CACHE for Media CDN, CLIENT_AUTH for
+        // mTLS trust configs) must be set per-store before the first Add.
+        [DefaultValue("")]
+        public string Scope { get; set; }
     }
 }

docsource/gcpcertmgr.md

@@ -20,6 +20,7 @@ That single value carries both the GCP project and the location (region or `glob
 | **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 |
+| **Certificate Scope** (custom) | GCP `scope` to apply to every new certificate created in this store. One of `DEFAULT`, `ALL_REGIONS`, `EDGE_CACHE`, `CLIENT_AUTH`. Blank → `DEFAULT`. Immutable on each cert once set in GCP - use one store per scope. See "Certificate scope" below. | Management/Add |
 
 #### Location semantics: where the GCP region lives
 
@@ -65,6 +66,7 @@ Set:
 - **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
+- **Certificate Scope**: `DEFAULT` for global external Application Load Balancers (the common case). Set to `ALL_REGIONS` if this store provisions certs for cross-region internal Application Load Balancers; `EDGE_CACHE` for Media CDN; `CLIENT_AUTH` for mTLS trust configs. See "Certificate scope" below.
 
 Authentication uses Application Default Credentials - see "Service account credentials" below.
 
@@ -79,6 +81,7 @@ After the discovery job runs, candidates appear in **Locations → Certificate S
 | **Application** | Optional, free-form. |
 | **Location** (custom) | Leave blank. Deprecated v1.1 field; the location is parsed from Store Path. |
 | **Service Account Key File Path** (custom) | Leave blank. Deprecated v1.1 field; authentication uses Application Default Credentials. |
+| **Certificate Scope** (custom) | Defaults to `DEFAULT`. Change only if this discovered store is going to back a non-default scope (`ALL_REGIONS`, `EDGE_CACHE`, `CLIENT_AUTH`) - Discovery does not know which scope your downstream load balancers need, so the operator sets it at approval time. Discovery emits one candidate per (project, location); if you need both `DEFAULT` and `ALL_REGIONS` certs in the same (project, location), reject this candidate and create two stores manually instead. See "Certificate scope" below. |
 | **Create Certificate Store If Missing** | **Check this.** Tells Command to create a new certificate store record from this candidate. Without it, the candidate sits in the discover tab with no store backing it. |
 | **Inventory Schedule** | Pick a cadence (e.g. Daily) for the inventory job to run after the store is created. |
 
@@ -148,6 +151,37 @@ GCP Certificate Manager constrains certificate resource IDs to a strict shape:
 
 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.
 
+### Certificate scope
+
+GCP Certificate Manager attaches a `scope` to every certificate that determines which load balancer / service families can consume it. The `Scope` custom store property tells the orchestrator which value to pass to GCP on create.
+
+| Value | What it is for |
+|---|---|
+| `DEFAULT` | Global external Application Load Balancers - the standard GCP load balancer for internet-facing traffic. This is the GCP default and the right answer for most stores. |
+| `ALL_REGIONS` | Cross-region **internal** Application Load Balancers. Use this when the consuming load balancer is regional/internal and replicated across regions. |
+| `EDGE_CACHE` | Google Cloud Media CDN edge-cache certs. |
+| `CLIENT_AUTH` | Certificates used by mTLS trust configs, or server certificates that are authorized for client authentication. |
+
+#### Immutability
+
+The `scope` field is **create-only** in the GCP API. Once GCP creates a certificate with a given scope, that scope cannot be changed by any patch operation. The orchestrator's Management/Replace path uses `UpdateMask = "SelfManaged"`, so re-adding a certificate over an existing one preserves its original scope - even if the store's Scope property has changed. To migrate a certificate to a different scope, delete it (Management/Remove) and re-add it with the new scope.
+
+This is why the recommended deployment pattern is **one store per (project, location, scope) tuple**. The Scope property is store-wide, not per-cert.
+
+#### What happened before v1.2.1
+
+Prior to v1.2.1 the orchestrator hard-coded `Scope = "DEFAULT"` on every certificate it created. Customers who needed non-default scopes (typically `ALL_REGIONS` for cross-region internal ALBs) had to pre-create empty placeholder certificate resources in GCP via Terraform with `scope = "ALL_REGIONS"`, then point Keyfactor at the existing resource as a Replace target. The new property removes that workaround: a store with Scope = `ALL_REGIONS` will create new certificate resources directly at the right scope.
+
+#### How the orchestrator validates the value
+
+`JobBase.ResolveScope` runs as the `ResolveScope` flow step on every Management/Add. It trims and uppercases the configured value, then validates it against the set GCP accepts. An unsupported value (typo, lowercase letters that don't normalize to a valid token, anything outside the four allowed values) fails with `[FAIL] ResolveScope` and a clear message naming the four legal values. Blank or null resolves to `DEFAULT`.
+
+#### Quick reference
+
+- "Where do I see what scope a certificate ended up with?" → GCP's Certificate Manager Console, or `gcloud certificate-manager certificates describe <name> --location=<loc> --project=<proj>`. The orchestrator's Inventory job does not surface scope today.
+- "Can I change a certificate's scope?" → No. Delete and re-add.
+- "I have one store with DEFAULT certs and I want to add an ALL_REGIONS cert" → Create a second store with the same (project, location) but Scope = `ALL_REGIONS`.
+
 ### Architecture and logging
 
 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.

integration-manifest.json

@@ -58,6 +58,16 @@
                             "Required": false,
                             "IsPAMEligible": false,
                             "Description": "**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."
+                        },
+                        {
+                            "Name": "Scope",
+                            "DisplayName": "Certificate Scope",
+                            "Type": "String",
+                            "DependsOn": "",
+                            "DefaultValue": "DEFAULT",
+                            "Required": false,
+                            "IsPAMEligible": false,
+                            "Description": "GCP Certificate Manager `scope` value applied to every new certificate created in this store. Allowed: `DEFAULT` (global external Application Load Balancers - the GCP default), `ALL_REGIONS` (cross-region internal Application Load Balancers), `EDGE_CACHE` (Media CDN), `CLIENT_AUTH` (mTLS trust configs / authorized client server certs). **Immutable in GCP** - once a certificate is created with a given scope, GCP refuses to change it. To use a different scope, delete and re-add the certificate. Pick the scope that matches the load balancer / service this store provisions certs for, and use one store per scope. Leave blank or set to `DEFAULT` for the legacy behavior."
                         }
                     ],
                     "ClientMachineDescription": "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.",