Ab#84816 (#8)

* ab#84816

* Update generated docs

* ab#84816

* ab#84816

* ab#84816

* ab#84816

* ab#84816

* ab#84816

* Update generated docs

* ab#84816

* ab#84816

* ab#84816

* Update generated docs

* chore(docs): Generate screenshots

* ab#84816

* chore(docs): Generate screenshots

* ab#84816

---------

Co-authored-by: Lee Fine <lfine@keyfactor.com>
Co-authored-by: Lee Fine <50836957+leefine02@users.noreply.github.com>
Co-authored-by: Keyfactor <keyfactor@keyfactor.github.io>

Author: 4 people

CHANGELOG.md

@@ -1,3 +1,10 @@
+v1.2.0
+- Added support for labels
+- Added support for setting ttl duration
+- Added support for setting version destroy ttl duration
+- Added support for setting replication regions
+- Bug Fix: Modified logic to obtain organization from project to allow for recursive folder ownership between these layers 
+
 v1.1.0
 - Added new Entry Parameter of Tags to support the assignment of one-to-many organization tags to a certificate/secret being added as a new certificate/secret
 

GCPSecretManager/GCPClient.cs

@@ -23,6 +23,7 @@ internal class GCPClient
         TagBindingsClient TagBindingsClient { get; set; }
         TagValuesClient TagValuesClient { get; set; }
         ProjectsClient ProjectsClient { get; set; }
+        FoldersClient FoldersClient { get; set; }
 
         private const string ResourcePrefix = "//secretmanager.googleapis.com/";
 
@@ -35,6 +36,7 @@ public GCPClient(string projectId)
             TagBindingsClient = TagBindingsClient.Create();
             TagValuesClient = TagValuesClient.Create();
             ProjectsClient = ProjectsClient.Create();
+            FoldersClient = FoldersClient.Create();
         }
 
         public List<string> GetSecretNames()
@@ -92,7 +94,25 @@ public SecretWithLabels GetCertificateEntry(string name)
                 rtnValue.Secret = version.Payload.Data.ToStringUtf8();
                 rtnValue.Labels = string.Empty;
 
-                Secret secret = GetSecret(name);
+                Secret secret = GetSecret(name.Substring(name.LastIndexOf("/")+1));
+                rtnValue.TTLDuration = secret.Ttl;
+                rtnValue.VersionDestroyTTLDuration = secret.VersionDestroyTtl;
+
+
+                if (secret.Replication != null && secret.Replication.UserManaged != null && secret.Replication.UserManaged.Replicas != null && secret.Replication.UserManaged.Replicas.Count > 0)
+                {
+                    foreach (Replication.Types.UserManaged.Types.Replica replica in secret.Replication.UserManaged.Replicas)
+                    {
+                        rtnValue.ReplicationRegions += $",{replica.Location}";
+                        if (replica.CustomerManagedEncryption != null && !string.IsNullOrEmpty(replica.CustomerManagedEncryption.KmsKeyName))
+                        {
+                            rtnValue.ReplicationRegions += $":{replica.CustomerManagedEncryption.KmsKeyName}";
+                        }
+                    }
+
+                    rtnValue.ReplicationRegions = rtnValue.ReplicationRegions.Substring(1);
+                }
+
                 List<string> labelsString = new List<string>();
                 foreach(var label in secret.Labels)
                 {
@@ -500,12 +520,23 @@ private string GetOrganizationFromProject()
         {
             _logger.MethodEntry(LogLevel.Debug);
 
-            string organization = string.Empty;
+            string parent = string.Empty;
 
             try
             {
                 Project project = ProjectsClient.GetProject(new GetProjectRequest() { ProjectName = ProjectName.FromProject(ProjectId) });
-                organization = project.Parent;
+                parent = project.Parent;
+
+                while(string.IsNullOrEmpty(null))
+                {
+                    if (parent.StartsWith("organizations/"))
+                        break;
+
+                    if (!parent.StartsWith("folders/"))
+                        throw new Exception($"Invalid or unknown project parent - {parent}");
+
+                    parent = FoldersClient.GetFolder(parent).Parent;
+                }
             }
             catch (Exception ex)
             {
@@ -517,20 +548,23 @@ private string GetOrganizationFromProject()
                 _logger.MethodExit(LogLevel.Debug);
             }
 
-            return organization.Substring(organization.IndexOf("/") + 1);
+            return parent.Substring(parent.IndexOf("/") + 1);
         }
 
         private void AssignLabels(string labels, MapField<string, string> labelMap)
         {
-            List<(string, string)> labelsList = labels != null ? null :
+            List<(string, string)> labelsList = labels == null ? null :
                 labels.Split(',', StringSplitOptions.RemoveEmptyEntries)
                 .Select(pair => pair.Split(':', 2))
                 .Where(parts => parts.Length == 2)
                 .Select(parts => (Key: parts[0].Trim(), Value: parts[1].Trim()))
                 .ToList();
 
-            foreach (var label in labelsList)
-                labelMap[label.Item1] = label.Item2;
+            if (labelsList != null)
+            {
+                foreach (var label in labelsList)
+                    labelMap[label.Item1] = label.Item2;
+            }
         }
     }
 }

GCPSecretManager/Inventory.cs

@@ -72,20 +72,12 @@ public JobResult ProcessJob(InventoryJobConfiguration config, SubmitInventoryUpd
                     Dictionary<string, object> entryParameters = new()
                     {
                         { "tags", secretTags },
-                        { "labels", certificateEntry.Labels }
+                        { "labels", certificateEntry.Labels },
+                        { "replicationRegions", certificateEntry.ReplicationRegions },
+                        { "ttlDuration", certificateEntry.TTLDuration?.ToTimeSpan().Days.ToString() },
+                        { "versionDestroyTtlDuration", certificateEntry.VersionDestroyTTLDuration?.ToTimeSpan().Days.ToString() }
                     };
 
-                    Dictionary<string, object> secretTags = new Dictionary<string, object>();
-                    try
-                    {
-                        secretTags = client.GetSecretTags(secretName);
-                    }
-                    catch (Exception)
-                    {
-                        hasWarnings = true;
-                        continue;
-                    }
-
                     inventoryItems.Add(new CurrentInventoryItem()
                     {
                         ItemStatus = OrchestratorInventoryItemStatus.Unknown,

GCPSecretManager/Management.cs

@@ -109,7 +109,7 @@ private bool PerformAdd(ManagementJobConfiguration config, GCPClient client, boo
             try
             {
                 string secret = CertificateFormatter.ConvertCertificateEntryToSecret(config.JobCertificate.Contents, config.JobCertificate.PrivateKeyPassword, IncludeChain, newPassword);
-                string labels = (config.JobProperties.ContainsKey("labels") && config.JobProperties["labels"] != null && !entryExists) ? config.JobProperties["labels"].ToString() : null;
+                string labels = (config.JobProperties.ContainsKey("labels") && config.JobProperties["labels"] != null) ? config.JobProperties["labels"].ToString() : null;
 
                 int ttlDuration = 0;
                 TimeSpan? ttlDurationTS = null;
@@ -174,50 +174,6 @@ private bool SetTags(ManagementJobConfiguration config, GCPClient client, out st
                 .ToList();
 
 
-            foreach ((string,string) tagValue in newTagKeyValues)
-            {
-                if (availableTagKeyValues.Exists(t => t.TagKey.ShortName == tagValue.Item1 && t.TagValues.Exists(t2 => t2.ShortName == tagValue.Item2)))
-                {
-                    TagKeyValue keyValue = availableTagKeyValues.First(t => t.TagKey.ShortName == tagValue.Item1 && t.TagValues.Exists(t2 => t2.ShortName == tagValue.Item2));
-
-                    try
-                    {
-                        client.SetSecretTag(config.JobCertificate.Alias, keyValue.TagValues.Find(t => t.ShortName == tagValue.Item2).Name);
-                    }
-                    catch (Exception ex)
-                    {
-                        hasWarnings = true;
-                        message += $"Error attempting to add tag key/value pair {tagValue.Item1}/{tagValue.Item2}: {ex.Message}";
-                    }
-                }
-                else
-                {
-                    hasWarnings = true;
-                    message += $"Tag key/value pair {tagValue.Item1}/{tagValue.Item2} not set up as a valid organization level tag in GCP. Tag will not be assigned. ";
-                }
-            }
-
-            Logger.MethodExit(LogLevel.Debug);
-
-            return hasWarnings;
-        }
-        private bool SetTags(ManagementJobConfiguration config, GCPClient client, out string message)
-        {
-            Logger.MethodEntry(LogLevel.Debug);
-
-            bool hasWarnings = false;
-            message = string.Empty;
-
-            List<TagKeyValue> availableTagKeyValues = client.GetTagKeysValues();
-
-            List<(string,string)> newTagKeyValues = config.JobProperties["tags"].ToString()
-                .Split(',', StringSplitOptions.RemoveEmptyEntries)
-                .Select(pair => pair.Split(':', 2))
-                .Where(parts => parts.Length == 2)
-                .Select(parts => (Key: parts[0].Trim(), Value: parts[1].Trim()))
-                .ToList();
-
-
             foreach ((string,string) tagValue in newTagKeyValues)
             {
                 if (availableTagKeyValues.Exists(t => t.TagKey.ShortName == tagValue.Item1 && t.TagValues.Exists(t2 => t2.ShortName == tagValue.Item2)))

GCPSecretManager/Models.cs

@@ -1,4 +1,5 @@
 using Google.Cloud.ResourceManager.V3;
+using Google.Protobuf.WellKnownTypes;
 using System.Collections.Generic;
 
 namespace Keyfactor.Extensions.Orchestrator.GCPSecretManager
@@ -19,5 +20,8 @@ internal class SecretWithLabels
     {
         internal string Secret { get; set; }
         internal string Labels { get; set; }
+        internal Duration TTLDuration { get; set; }
+        internal Duration VersionDestroyTTLDuration { get; set; }
+        internal string ReplicationRegions { get; set; }
     }
 }

README.md

@@ -37,17 +37,12 @@ The Google Cloud Platform (GCP) Secret Manager Orchestrator Extension remotely m
 * PEM encoded certificate and unencrypted or encrypted private key with full certificate chain
 * PEM encoded certificate only
 
-For use cases including an encrypted private key, please refer to [Certificate Encryption Details](#certificate-encryption-details) for more information on handling/storing the encryption password for the private key.
-
-This extension also optionally supports the management of secret tags.  **If** the optional Entry Parameter of "Tags" exists in the store type definition:
-* Inventory will return all tags assigned to a secert in the comma delimited format of "TagKey1:TagValue1,TagKey2:TagValue2,...,TagKeyN:TagValueN".  
-* The same format of one-to-many tag key/value pairs ("TagKey1:TagValue1,TagKey2:TagValue2,...,TagKeyN:TagValueN") can be added to the "Tags" field during the setup of Management-Add jobs to assign tags to the secret **as long as each tag key/value pair is already set up as a valid Organization level tag key/value combination in GCP**.
-
-Additional notes regarding tags:
-* This integration does **not** support Project level tags when adding new certificates (secrets).  Only Organization level tags will be recognized.
-* The Tags field will be ignored when renewing/replacing a certificate since in this scenario the extension is only adding a new secret version and not replacing the entire secret.  Assigning tags is only attempted when adding a completely new certificate (secret).
-* When adding a new secret, any errors attempting to add tags **will not** impact the adding of the secret.  If a Management-Add job successfully adds a new certificate (secret) but fails to assign the tag, the job will be reported back with a status of Warning along with detailed messages why each tag could not be assigned.  The certificate (secret) itself, however, **will** be added.
-* If multiple tags are provided, and errors occur on some but not others, the successful ones will be assigned to the certificate (secret) and warning messages will be written to the log and job status for the others.
+Additional features:
+* For use cases including an encrypted private key, please refer to [Certificate Encryption Details](#certificate-encryption-details) for more information on handling/storing the encryption password for the private key.
+* For information on Tag Support, please refer to [Tag Support](#tag-support)
+* For information on Label Support, please refer to [Label Support](#label-support)
+* For information on Automatic vs User Managed Replication, please refer to [Region Replication](#region-replication)
+* For information on Secret and Secret Version Retention, please refer to [TTL and TTL Version Retention](#ttl-and-ttl-version-retention)
 
 
 
@@ -67,7 +62,11 @@ Before installing the GCP Secret Manager Universal Orchestrator extension, we re
 
 The GCP Secret Manager Orchestrator Extension uses Google Application Default Credentials (ADC) for authentication.  Testing of this orchestrator extension was performed using a service account, but please review [Google Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials) for more information on the various ways authentication can be set up.
 
-The GCP project and account being used to access Secret Manager must have access to and enabled the Secret Manger API and also must have assigned to it the Secret Manager Admin and Tag Administrator roles.
+The GCP project and account being used to access Secret Manager must have access to and enabled the Secret Manger API and also must have assigned to it the following roles:
+* Secret Manager Admin
+* Tag User (if assigning tags to secrets)
+* Folder Viewer (if assigning tags to secrets AND the project assigned for this certificate store has a folder as a direct parent)
+* Cloud KMS CryptoKey Encrypter/Decrypter (If assigning KMS Paths to regions when adding secrets using user managed replication)
 
 
 ## GCPScrtMgr Certificate Store Type
@@ -379,6 +378,50 @@ For GCP Secret Manager secrets containing private keys, the GCP Secret Manager O
 
 If the Store Password has a value, this will be used to encrypt the private key during a Management Add job.  If no value is set for the Store Password, the one time password that Keyfactor Command generates when triggering a Management-Add job will be used to encrypt the private key and this password will be stored as a secret in GCP Secret Manager with a name of Alias + Password Secret Location Suffix.  For example, if the certificate alias is set as "Alias1" and the Password Secret Location Suffix is set as "_Key", the certificate and encrypted private key will be stored in a secret named "Alias1" and the password for the key encryption will be stored in a secret named "Alias1_Key".  Please note that if using the generated password Keyfactor Command provides and storing the password in Secret Manager, each renewal/replacement of a certificate will encrypt the private key with a new generated password, which will then be stored as a new version of the password secret.
 
+## Tag Support
+
+This extension supports the management of secret tags.  **If** the optional Entry Parameter "Tags" exists in the store type definition:
+* Inventory will return all tags assigned to a secret in the comma delimited format of "TagKey1:TagValue1,TagKey2:TagValue2,...,TagKeyN:TagValueN".  
+* The same format of one-to-many tag key/value pairs ("TagKey1:TagValue1,TagKey2:TagValue2,...,TagKeyN:TagValueN") can be added to the "Tags" field during the setup of Management-Add jobs to assign tags to the secret **as long as each tag key/value pair is already set up as a valid Organization level tag key/value combination in GCP**.
+
+Additional notes regarding tags:
+* This integration does **not** support Project level tags when adding new certificates (secrets).  Only Organization level tags will be recognized.
+* The Tags field will be ignored when renewing/replacing a certificate since in this scenario the extension is only adding a new secret version and not replacing the entire secret.  Assigning tags is only attempted when adding a completely new certificate (secret).
+* When adding a new secret, any errors attempting to add tags **will not** impact the adding of the secret.  If a Management-Add job successfully adds a new certificate (secret) but fails to assign the tag, the job will be reported back with a status of Warning along with detailed messages why each tag could not be assigned.  The certificate (secret) itself, however, **will** be added.
+* If multiple tags are provided, and errors occur on some but not others, the successful ones will be assigned to the certificate (secret) and warning messages will be written to the log and job status for the others.
+
+## Label Support
+
+This extension supports the management of secret labels.  **If** the optional Entry Parameter "Labels" exists in the store type definition:
+* Inventory will return all labels attached to each secret in the comma delimited format of "LabelName1:LabelValue1,LabelName2:LabelValue2,...,LabelNameN:LabelValueN"
+* The same format of one-to-many label name/value pairs can be added to new secrets during Management-Add jobs in the Labels Entry Parameter.  These values can also be modified when renewing/replacing an existing secret.
+
+Additional notes regarding labels:
+* A blank Labels Entry Parameter will not remove any existing labels from an existing secret being replaced (certificate renewal use case).
+* A non blank Labels Entry Parameter will cause all pre-existing labels to be removed and replaced for the secret being replaced.
+* Improperly formatted Labels may cause pre-existing labels to be removed but none or only valid ones added, but this will not prevent the secret from being added/replaced.
+
+## Region Replication
+
+This extension supports replicating secrets to one-to-many valid GCP regions, along with optionally specifying a valid GCP Key Management Service (KMS) patha for each region.  **If** the optional Entry Parameter "Replication Regions" exists in the store type definition:
+* Inventory will return all replication regions and KMS paths attached to each secret in the comma delimited format of "Region1:KMSPath1,Region2:KMSPath2,...,RegionN:KMSPathN"
+* The same format of one-to-many region/KMS path pairs can be added to new secrets during Managment-Add jobs in the Replication Regions Entry Parameter.  Modification of these values is **NOT** supported when renewing/replacing an existing secret.  Region/KMS values entered when renewing/replacing a certificate in Management-Add job will be ignored.
+* Replication regions without KMS paths can also be provided - i.e. "Region1,Region2,...,RegionN", but GCP enforces the convention that **all** supplied regions must have an associated valid KMS path or all of them must **not** have a KMS path.  Cannot mix some with and some without.
+
+Additionsl notes regarding replication regions:
+* Each region must be a [GCP allowed region for secrets](https://docs.cloud.google.com/secret-manager/docs/locations).
+* In order to apply KMS paths to replication regions:
+	- A valid KMS Key Ring and Crypto Key must be created for the applicable region.
+	- The Cloud KMS CryptoKey Encrypter/Decrypter role must be applied to the service-{PROJECT ID}@gcp-sa-secretmanager.iam.gserviceaccount.com service principle where {PROJECT ID} is the numeric project id for the project the secret is being added to.
+	- The Cloud Key Management Service API must be enabled.
+
+## TTL and TTL Version Retention
+
+This extension supports supplying TTL (Time To Live) and Destroy Version TTL values.  **If** the optional Entry Parameters of "TTL Duration" and "Version Destroy TTL Duration" exist in the store type definition:
+* A numeric value (in days) can be entered for either or both values specifying when a secret will be deleted (TTL Duration) and how many days after secret deletion each version will be destroyed (Version Destroy TTL Duration).
+* These values will be returned in Inventory jobs as well as modified when renewing/replacing a secret.
+* Blank values supplied during Management job when replacing a secret will not affect current values for the secret.
+
 
 ## License