diff --git a/.github/workflows/keyfactor-extension-update-catalog.yml b/.github/workflows/keyfactor-extension-update-catalog.yml deleted file mode 100644 index ab7942e..0000000 --- a/.github/workflows/keyfactor-extension-update-catalog.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: Generate Catalog Entry -on: [push, workflow_dispatch] - -jobs: - generate_entry: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@main - - - uses: actions/checkout@v2 - with: - token: ${{ secrets.SDK_SYNC_PAT }} - path: './catalog-temp/' - repository: 'Keyfactor/integrations-catalog' - - - uses: cuchi/jinja2-action@v1.2.0 - with: - template: ./catalog-temp/_integration.md.tpl - output_file: ${{ format('./catalog-temp/_integrations/{0}.md', github.event.repository.name) }} - data_file: integration-manifest.json - variables: | - repository= ${{ format('https://github.com/{0}', github.repository) }} - env: - GITHUB_TOKEN: ${{ secrets.SDK_SYNC_PAT }} - - - uses: EndBug/add-and-commit@v7 - with: - author_name: 'Keyfactor' - author_email: 'keyfactor@keyfactor.github.io' - branch: 'main' - message: ${{ format('Added the manifest for {0}', github.event.repository.name) }} - add: ${{ format('_integrations/{0}.md --force', github.event.repository.name) }} - cwd: './catalog-temp/' diff --git a/.github/workflows/keyfactor-bootstrap-workflow.yml b/.github/workflows/keyfactor-starter-workflow.yml similarity index 80% rename from .github/workflows/keyfactor-bootstrap-workflow.yml rename to .github/workflows/keyfactor-starter-workflow.yml index 6d8de53..a4649f2 100644 --- a/.github/workflows/keyfactor-bootstrap-workflow.yml +++ b/.github/workflows/keyfactor-starter-workflow.yml @@ -11,9 +11,10 @@ on: jobs: call-starter-workflow: - uses: keyfactor/actions/.github/workflows/starter.yml@v2 + uses: keyfactor/actions/.github/workflows/starter.yml@3.1.2 secrets: token: ${{ secrets.V2BUILDTOKEN}} APPROVE_README_PUSH: ${{ secrets.APPROVE_README_PUSH}} gpg_key: ${{ secrets.KF_GPG_PRIVATE_KEY }} gpg_pass: ${{ secrets.KF_GPG_PASSPHRASE }} + scan_token: ${{ secrets.SAST_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 09d4bf6..f760407 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,2 +1,6 @@ +v1.1.0 +- Implemented dual build for .net6/8 +- Converted README to use doctool + v1.0.2 - Initial Public Version \ No newline at end of file diff --git a/GcpCertManager/Client/GcpCertificateManagerClient.cs b/GcpCertManager/Client/GcpCertificateManagerClient.cs index 5155204..b41febf 100644 --- a/GcpCertManager/Client/GcpCertificateManagerClient.cs +++ b/GcpCertManager/Client/GcpCertificateManagerClient.cs @@ -1,4 +1,10 @@ -using System.IO; +// Copyright 2025 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. +using System.IO; using System.Reflection; using Google.Apis.Auth.OAuth2; using Google.Apis.CertificateManager.v1; diff --git a/GcpCertManager/GcpCertManager.csproj b/GcpCertManager/GcpCertManager.csproj index e9e15de..6f4a636 100644 --- a/GcpCertManager/GcpCertManager.csproj +++ b/GcpCertManager/GcpCertManager.csproj @@ -1,10 +1,10 @@ - false - netcoreapp3.1 - Keyfactor.Extensions.Orchestrator.GcpCertManager + true + net6.0;net8.0 true + disable @@ -27,11 +27,9 @@ - - - PreserveNewest + Always diff --git a/GcpCertManager/Jobs/Inventory.cs b/GcpCertManager/Jobs/Inventory.cs index 64ca851..b3d6165 100644 --- a/GcpCertManager/Jobs/Inventory.cs +++ b/GcpCertManager/Jobs/Inventory.cs @@ -1,3 +1,9 @@ +// Copyright 2025 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. using System; using System.Collections.Generic; using System.Linq; diff --git a/GcpCertManager/Jobs/Management.cs b/GcpCertManager/Jobs/Management.cs index c08cb83..29da573 100644 --- a/GcpCertManager/Jobs/Management.cs +++ b/GcpCertManager/Jobs/Management.cs @@ -1,4 +1,10 @@ -using System; +// Copyright 2025 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. +using System; using System.Collections.Generic; using System.Drawing; using System.IO; diff --git a/GcpCertManager/StoreProperties.cs b/GcpCertManager/StoreProperties.cs index d905a53..95384f8 100644 --- a/GcpCertManager/StoreProperties.cs +++ b/GcpCertManager/StoreProperties.cs @@ -1,4 +1,10 @@ -using System.ComponentModel; +// Copyright 2025 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. +using System.ComponentModel; using Newtonsoft.Json; namespace Keyfactor.Extensions.Orchestrator.GcpCertManager diff --git a/README.md b/README.md index 436f000..0ca4400 100644 --- a/README.md +++ b/README.md @@ -1,145 +1,247 @@ +

+ Google Cloud Provider Certificate Manager Universal Orchestrator Extension +

-# Google Cloud Provider Certificate Manager +

+ +Integration Status: production +Release +Issues +GitHub Downloads (all assets, all releases) +

-Google Certificate Manager Orchestrator for Add, Remove and Inventory. +

+ + + Support + + · + + Installation + + · + + License + + · + + Related Integrations + +

-#### Integration status: Production - Ready for use in production environments. +## Overview -## About the Keyfactor Universal Orchestrator Extension +The GCP Certificate Manager Orchestrator Extension remotely manages certificates on the Google Cloud Platform Certificate Manager Product. -This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications. +This orchestrator extension implements three job types - Inventory, Management Add, and Management Remove. Below are the steps necessary to configure this Orchestrator Extension. It supports adding certificates with private keys only. The GCP Certificate Manager Orchestrator Extension 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. -The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Extensions, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Extension see below in this readme. -The Universal Orchestrator is the successor to the Windows Orchestrator. This Orchestrator Extension plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator. -## Support for Google Cloud Provider Certificate Manager +## Compatibility -Google Cloud Provider Certificate Manager is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com +This integration is compatible with Keyfactor Universal Orchestrator version 10.4.1 and later. -###### To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab. +## Support +The Google Cloud Provider Certificate Manager Universal Orchestrator extension is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com. + +> To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab. ---- +## Requirements & Prerequisites +Before installing the Google Cloud Provider Certificate Manager Universal Orchestrator extension, we recommend that you install [kfutil](https://github.com/Keyfactor/kfutil). Kfutil is a command-line tool that simplifies the process of creating store types, installing extensions, and instantiating certificate stores in Keyfactor Command. ---- +**Google Cloud Configuration** +1. Read up on [Google Certificate Manager](https://cloud.google.com/certificate-manager/docs) and how it works. -## Keyfactor Version Supported +2. Either a Google Service Account is needed with the following permissions (Note: Workload Identity Management Should be used but at the time of the writing it was not available in the .net library yet), or the virtual machine running the Keyfactor Orchestrator Service must reside within Google Cloud. +![](docsource/images/ServiceAccountSettings.gif) -The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.4.1 -## Platform Specific Notes +3. The following Api Access is needed: +![](docsource/images/ApiAccessNeeded.gif) -The Keyfactor Universal Orchestrator may be installed on either Windows or Linux based platforms. The certificate operations supported by a capability may vary based what platform the capability is installed on. The table below indicates what capabilities are supported based on which platform the encompassing Universal Orchestrator is running. -| Operation | Win | Linux | -|-----|-----|------| -|Supports Management Add|✓ |✓ | -|Supports Management Remove|✓ |✓ | -|Supports Create Store| | | -|Supports Discovery| | | -|Supports Reenrollment| | | -|Supports Inventory|✓ |✓ | +4. If authenticating via service account, download the Json Credential file as shown below: +![](docsource/images/GoogleKeyJsonDownload.gif) +## Create the GcpCertMgr Certificate Store Type +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. ---- +* **Create GcpCertMgr using kfutil**: -## Google Cloud Platform Certificate Manager + ```shell + # GCP Certificate Manager + kfutil store-types create GcpCertMgr + ``` -**Overview** +* **Create GcpCertMgr manually in the Command UI**: +
Create GcpCertMgr manually in the Command UI -The GCP Certificate Manager Orchestrator Extension remotely manages certificates on the Google Cloud Platform Certificate Manager Product + Create a store type called `GcpCertMgr` with the attributes in the tables below: -This orchestrator extension implements three job types – Inventory, Management Add, and Management Remove. Below are the steps necessary to configure this Orchestrator Extension. It supports adding certificates with private keys only. The GCP Certificate Manager Orchestrator Extension 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. + #### Basic Tab + | 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: -**Google Cloud Configuration** + ![GcpCertMgr Basic Tab](docsource/images/GcpCertMgr-basic-store-type-dialog.png) -1. Read up on [Google Certificate Manager](https://cloud.google.com/certificate-manager/docs) and how it works. + #### Advanced Tab + | 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.) | -2. Either a Google Service Account is needed with the following permissions (Note: Workload Identity Management Should be used but at the time of the writing it was not available in the .net library yet), or the virtual machine running the Keyfactor Orchestrator Service must reside within Google Cloud. -![](images/ServiceAccountSettings.gif) + The Advanced tab should look like this: -3. The following Api Access is needed: -![](images/ApiAccessNeeded.gif) + ![GcpCertMgr Advanced Tab](docsource/images/GcpCertMgr-advanced-store-type-dialog.png) -4. If authenticating via service account, download the Json Credential file as shown below: -![](images/GoogleKeyJsonDownload.gif) + #### Custom Fields Tab + 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 | The GCP region used for this Certificate Manager instance. **global** is the default but could be another region based on the project. | String | global | ✅ Checked | + | ServiceAccountKey | Service Account Key File Path | The file name of the Google Cloud Service Account Key File installed in the same folder as the orchestrator extension. Empty if the orchestrator server resides in GCP and you are not using a service account key. | String | | 🔲 Unchecked | + + The Custom Fields tab should look like this: + + ![GcpCertMgr Custom Fields Tab](docsource/images/GcpCertMgr-custom-fields-store-type-dialog.png) + + + +
+ +## Installation + +1. **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](https://github.com/Keyfactor/gcp-certmanager-orchestrator/releases/latest). Refer to the compatibility matrix below to determine whether the `net6.0` or `net8.0` 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 | `rollForward` condition in `Orchestrator.runtimeconfig.json` | `gcp-certmanager-orchestrator` .NET version to download | + | --------- | ----------- | ----------- | ----------- | + | Older than `11.0.0` | | | `net6.0` | + | Between `11.0.0` and `11.5.1` (inclusive) | `net6.0` | | `net6.0` | + | Between `11.0.0` and `11.5.1` (inclusive) | `net8.0` | `Disable` | `net6.0` | + | Between `11.0.0` and `11.5.1` (inclusive) | `net8.0` | `LatestMajor` | `net8.0` | + | `11.6` _and_ newer | `net8.0` | | `net8.0` | + + Unzip 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`. + +2. **Locate the Universal Orchestrator extensions directory.** + + * **Default on Windows** - `C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions` + * **Default on Linux** - `/opt/keyfactor/orchestrator/extensions` + +3. **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. + +4. **Copy the contents of the downloaded and unzipped assemblies from __step 2__ to the `gcp-certmanager-orchestrator` directory.** + +5. **Restart the Universal Orchestrator service.** + + Refer to [Starting/Restarting the Universal Orchestrator service](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/StarttheService.htm). + + + +> The above installation steps can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions). + + + +## Defining Certificate Stores + + + +* **Manually with the Command UI** + +
Create Certificate Stores manually in the UI + + 1. **Navigate to the _Certificate Stores_ page in Keyfactor Command.** + Log into Keyfactor Command, toggle the _Locations_ dropdown, and click _Certificate Stores_. -## Keyfactor Command Configuration + 2. **Add a Certificate Store.** -**1. Create the New Certificate Store Type for the GCP Certificate Manager Orchestrator** + 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 | GCP Project ID for your account. | + | Store Path | This is not used and should be defaulted to n/a per the certificate store type set up. | + | Orchestrator | Select an approved orchestrator capable of managing `GcpCertMgr` certificates. Specifically, one with the `GcpCertMgr` capability. | + | Location | The GCP region used for this Certificate Manager instance. **global** is the default but could be another region based on the project. | + | ServiceAccountKey | The file name of the Google Cloud Service Account Key File installed in the same folder as the orchestrator extension. Empty if the orchestrator server resides in GCP and you are not using a service account key. | -In Keyfactor Command create a new Certificate Store Type similar to the one below: -#### STORE TYPE CONFIGURATION -SETTING TAB | CONFIG ELEMENT | DESCRIPTION -------|-----------|------------------ -Basic |Name |Descriptive name for the Store Type. Example: Google Cloud Certificate Manager -Basic |Short Name |The name that identifies the registered functionality of the orchestrator. Must be GcpCertMgr -Basic |Custom Capability|Unchecked -Basic |Job Types |Inventory, Add, and Remove are the supported job types -Basic |Needs Server |Unchecked -Basic |Blueprint Allowed |Unchecked -Basic |Requires Store Password |Unchecked -Basic |Supports Entry Password |Unchecked -Advanced |Store Path Type| Fixed -Advanced |Store Path Type Value (the textbox that appears below Store Path Type when Store Path Type is set to "Fixed") |n/a -Advanced |Supports Custom Alias |Required -Advanced |Private Key Handling |Required -Advanced |PFX Password Style |Default -Custom Fields|Google Cloud Platform Project Location/Region|Name:Location, Display Name:Location, Type:String, Default Value:global, Required:False -Custom Fields|The file name of the Google Cloud Service Account Key File installed in the same folder as the orchestrator extension. Empty if the orchestrator server resides in GCP and you are not using a service account key |Name:Service Account Key File Name, Type:String, Default Value: (leave blank), Required:True -Entry Parameters|N/A| There are no Entry Parameters + -**Basic Settings:** +
-![](images/CertStoreType-Basic.gif) +* **Using kfutil** + +
Create Certificate Stores with kfutil + + 1. **Generate a CSV template for the GcpCertMgr certificate store** -**Advanced Settings:** + ```shell + kfutil stores import generate-template --store-type-name GcpCertMgr --outpath GcpCertMgr.csv + ``` + 2. **Populate the generated CSV file** -![](images/CertStoreType-Advanced.gif) + 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 | GCP Project ID for your account. | + | Store Path | This is not used and should be defaulted to n/a per the certificate store type set up. | + | Orchestrator | Select an approved orchestrator capable of managing `GcpCertMgr` certificates. Specifically, one with the `GcpCertMgr` capability. | + | Location | The GCP region used for this Certificate Manager instance. **global** is the default but could be another region based on the project. | + | ServiceAccountKey | The file name of the Google Cloud Service Account Key File installed in the same folder as the orchestrator extension. Empty if the orchestrator server resides in GCP and you are not using a service account key. | -**Custom Fields:** -![](images/CertStoreType-CustomFields.gif) -![](images/CertStoreType-CustomField-Location.gif) -![](images/CertStoreType-CustomField-ServiceAccountKey.gif) + -**Entry Params:** + 3. **Import the CSV file to create the certificate stores** -![](images/CertStoreType-EntryParameters.gif) + ```shell + kfutil stores import csv --store-type-name GcpCertMgr --file GcpCertMgr.csv + ``` +
-**2. Register the GCP Certificate Manager Orchestrator with Keyfactor** -See Keyfactor InstallingKeyfactorOrchestrators.pdf Documentation. Get from your Keyfactor contact/representative. +> The content in this section can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store). -**3. Create a GCP Certificate Manager Certificate Store within Keyfactor Command** -In Keyfactor Command create a new Certificate Store similar to the one below -![](images/CertStoreSettings.gif) -#### STORE CONFIGURATION -CONFIG ELEMENT |DESCRIPTION -----------------|--------------- -Category |The type of certificate store to be configured. Select category based on the display name configured above "GCP Certificate Manager". -Container |This is a logical grouping of like stores. This configuration is optional and does not impact the functionality of the store. -Client Machine |Your GCP Project ID for your account. -Store Path |This is not used and should be defaulted to n/a per the certificate store type set up. -Orchestrator |This is the orchestrator server registered with the appropriate capabilities to manage this certificate store type. -Location|**global** is the default but could be another region based on the project. -Service Account Key File Name | The name of the file containing the GCP Service Account JSON formatted key previously downloaded. Keep this optional field blank if the Keyfactor Orchestrator Service is running from an authenticated VM within Google Cloud. -Update Server User Name |Click and select No Value. -Update Server Password |Click and select No Value. -Use SSL |This should be checked. -Inventory Schedule |The interval that the system will use to report on what certificates are currently in the store. +## License -When creating cert store type manually, that store property names and entry parameter names are case sensitive +Apache License 2.0, see [LICENSE](LICENSE). +## Related Integrations +See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator). \ No newline at end of file diff --git a/docsource/content.md b/docsource/content.md new file mode 100644 index 0000000..b1e78e5 --- /dev/null +++ b/docsource/content.md @@ -0,0 +1,21 @@ +## Overview + +The GCP Certificate Manager Orchestrator Extension remotely manages certificates on the Google Cloud Platform Certificate Manager Product. + +This orchestrator extension implements three job types - Inventory, Management Add, and Management Remove. Below are the steps necessary to configure this Orchestrator Extension. It supports adding certificates with private keys only. The GCP Certificate Manager Orchestrator Extension 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. + + +## Requirements + +**Google Cloud Configuration** + +1. Read up on [Google Certificate Manager](https://cloud.google.com/certificate-manager/docs) and how it works. + +2. Either a Google Service Account is needed with the following permissions (Note: Workload Identity Management Should be used but at the time of the writing it was not available in the .net library yet), or the virtual machine running the Keyfactor Orchestrator Service must reside within Google Cloud. +![](docsource/images/ServiceAccountSettings.gif) + +3. The following Api Access is needed: +![](docsource/images/ApiAccessNeeded.gif) + +4. If authenticating via service account, download the Json Credential file as shown below: +![](docsource/images/GoogleKeyJsonDownload.gif) \ No newline at end of file diff --git a/docsource/gcpcertmgr.md b/docsource/gcpcertmgr.md new file mode 100644 index 0000000..ed37e8e --- /dev/null +++ b/docsource/gcpcertmgr.md @@ -0,0 +1 @@ +## Overview diff --git a/images/ApiAccessNeeded.gif b/docsource/images/ApiAccessNeeded.gif similarity index 100% rename from images/ApiAccessNeeded.gif rename to docsource/images/ApiAccessNeeded.gif diff --git a/docsource/images/GcpCertMgr-advanced-store-type-dialog.png b/docsource/images/GcpCertMgr-advanced-store-type-dialog.png new file mode 100644 index 0000000..534ecb2 Binary files /dev/null and b/docsource/images/GcpCertMgr-advanced-store-type-dialog.png differ diff --git a/docsource/images/GcpCertMgr-basic-store-type-dialog.png b/docsource/images/GcpCertMgr-basic-store-type-dialog.png new file mode 100644 index 0000000..1c94820 Binary files /dev/null and b/docsource/images/GcpCertMgr-basic-store-type-dialog.png differ diff --git a/docsource/images/GcpCertMgr-custom-fields-store-type-dialog.png b/docsource/images/GcpCertMgr-custom-fields-store-type-dialog.png new file mode 100644 index 0000000..9cde5e9 Binary files /dev/null and b/docsource/images/GcpCertMgr-custom-fields-store-type-dialog.png differ diff --git a/images/GoogleKeyJsonDownload.gif b/docsource/images/GoogleKeyJsonDownload.gif similarity index 100% rename from images/GoogleKeyJsonDownload.gif rename to docsource/images/GoogleKeyJsonDownload.gif diff --git a/images/ServiceAccountSettings.gif b/docsource/images/ServiceAccountSettings.gif similarity index 100% rename from images/ServiceAccountSettings.gif rename to docsource/images/ServiceAccountSettings.gif diff --git a/images/CertStoreSettings.gif b/images/CertStoreSettings.gif deleted file mode 100644 index 7347fb8..0000000 Binary files a/images/CertStoreSettings.gif and /dev/null differ diff --git a/images/CertStoreType-Advanced.gif b/images/CertStoreType-Advanced.gif deleted file mode 100644 index 9e1f062..0000000 Binary files a/images/CertStoreType-Advanced.gif and /dev/null differ diff --git a/images/CertStoreType-Basic.gif b/images/CertStoreType-Basic.gif deleted file mode 100644 index 227fd38..0000000 Binary files a/images/CertStoreType-Basic.gif and /dev/null differ diff --git a/images/CertStoreType-CustomField-Location.gif b/images/CertStoreType-CustomField-Location.gif deleted file mode 100644 index 136eb2f..0000000 Binary files a/images/CertStoreType-CustomField-Location.gif and /dev/null differ diff --git a/images/CertStoreType-CustomField-ServiceAccountKey.gif b/images/CertStoreType-CustomField-ServiceAccountKey.gif deleted file mode 100644 index 617d934..0000000 Binary files a/images/CertStoreType-CustomField-ServiceAccountKey.gif and /dev/null differ diff --git a/images/CertStoreType-CustomFields.gif b/images/CertStoreType-CustomFields.gif deleted file mode 100644 index 9aa24fa..0000000 Binary files a/images/CertStoreType-CustomFields.gif and /dev/null differ diff --git a/images/CertStoreType-EntryParameters.gif b/images/CertStoreType-EntryParameters.gif deleted file mode 100644 index 919c83c..0000000 Binary files a/images/CertStoreType-EntryParameters.gif and /dev/null differ diff --git a/integration-manifest.json b/integration-manifest.json index a3ea0b9..7200373 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -1,81 +1,70 @@ { - "$schema": "https://keyfactor.github.io/integration-manifest-schema.json", - "integration_type": "orchestrator", - "name": "Google Cloud Provider Certificate Manager", - "status": "production", - "update_catalog": false, - "support_level": "kf-supported", - "link_github": true, - "release_dir": "GcpCertManager/bin/release", - "description": "Google Certificate Manager Orchestrator for Add, Remove and Inventory.", - "about": { - "orchestrator": { - "UOFramework": "10.4.1", - "keyfactor_platform_version": "9.1.0", - "pam_support": false, - "win": { - "supportsCreateStore": false, - "supportsDiscovery": false, - "supportsManagementAdd": true, - "supportsManagementRemove": true, - "supportsReenrollment": false, - "supportsInventory": true, - "platformSupport": "Unused" - }, - "linux": { - "supportsCreateStore": false, - "supportsDiscovery": false, - "supportsManagementAdd": true, - "supportsManagementRemove": true, - "supportsReenrollment": false, - "supportsInventory": true, - "platformSupport": "Unused" - }, - "store_types": { - "GcpCertMgr": { - "Name": "GCP Certificate Manager", - "ShortName": "GcpCertMgr", - "Capability": "GcpCertMgr", - "ServerRequired": false, - "BlueprintAllowed": false, - "CustomAliasAllowed": "Required", - "PowerShell": false, - "PrivateKeyAllowed": "Required", - "StorePathType": "", - "StorePathValue": "n/a", - "SupportedOperations": { - "Add": true, - "Create": true, - "Discovery": true, - "Enrollment": false, - "Remove": true - }, - "PasswordOptions": { - "Style": "Default", - "EntrySupported": false, - "StoreRequired": false - }, - "Properties": [ - { - "Name": "Location", - "DisplayName": "Location", - "Type": "String", - "DependsOn": "", - "DefaultValue": "global", - "Required": true - }, - { - "Name": "ServiceAccountKey", - "DisplayName": "Service Account Key File Path", - "Type": "String", - "DependsOn": "", - "DefaultValue": null, - "Required": false - } - ], - "EntryParameters": [] + "$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json", + "integration_type": "orchestrator", + "name": "Google Cloud Provider Certificate Manager", + "status": "production", + "update_catalog": false, + "support_level": "kf-supported", + "link_github": true, + "release_dir": "GcpCertManager/bin/release", + "release_project": "GcpCertManager/GcpCertManager.csproj", + "description": "Google Certificate Manager Orchestrator for Add, Remove and Inventory.", + "about": { + "orchestrator": { + "UOFramework": "10.4.1", + "keyfactor_platform_version": "9.1.0", + "pam_support": false, + "store_types": [ + { + "Name": "GCP Certificate Manager", + "ShortName": "GcpCertMgr", + "Capability": "GcpCertMgr", + "ServerRequired": false, + "BlueprintAllowed": false, + "CustomAliasAllowed": "Required", + "PowerShell": false, + "PrivateKeyAllowed": "Required", + "StorePathType": "", + "StorePathValue": "n/a", + "SupportedOperations": { + "Add": true, + "Create": true, + "Discovery": true, + "Enrollment": false, + "Remove": true + }, + "PasswordOptions": { + "Style": "Default", + "EntrySupported": false, + "StoreRequired": false + }, + "Properties": [ + { + "Name": "Location", + "DisplayName": "Location", + "Type": "String", + "DependsOn": "", + "DefaultValue": "global", + "Required": true, + "IsPAMEligible": false, + "Description": "The GCP region used for this Certificate Manager instance. **global** is the default but could be another region based on the project." + }, + { + "Name": "ServiceAccountKey", + "DisplayName": "Service Account Key File Path", + "Type": "String", + "DependsOn": "", + "DefaultValue": "", + "Required": false, + "IsPAMEligible": false, + "Description": "The file name of the Google Cloud Service Account Key File installed in the same folder as the orchestrator extension. Empty if the orchestrator server resides in GCP and you are not using a service account key." + } + ], + "ClientMachineDescription": "GCP Project ID for your account.", + "StorePathDescription": "This is not used and should be defaulted to n/a per the certificate store type set up.", + "EntryParameters": [] + } + ] } - } } - } } diff --git a/readme_source.md b/readme_source.md deleted file mode 100644 index b0d5003..0000000 --- a/readme_source.md +++ /dev/null @@ -1,91 +0,0 @@ -## Google Cloud Platform Certificate Manager - -**Overview** - -The GCP Certificate Manager Orchestrator Extension remotely manages certificates on the Google Cloud Platform Certificate Manager Product - -This orchestrator extension implements three job types – Inventory, Management Add, and Management Remove. Below are the steps necessary to configure this Orchestrator Extension. It supports adding certificates with private keys only. The GCP Certificate Manager Orchestrator Extension 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. - - -**Google Cloud Configuration** - -1. Read up on [Google Certificate Manager](https://cloud.google.com/certificate-manager/docs) and how it works. - -2. Either a Google Service Account is needed with the following permissions (Note: Workload Identity Management Should be used but at the time of the writing it was not available in the .net library yet), or the virtual machine running the Keyfactor Orchestrator Service must reside within Google Cloud. -![](images/ServiceAccountSettings.gif) - -3. The following Api Access is needed: -![](images/ApiAccessNeeded.gif) - -4. If authenticating via service account, download the Json Credential file as shown below: -![](images/GoogleKeyJsonDownload.gif) - - -## Keyfactor Command Configuration - -**1. Create the New Certificate Store Type for the GCP Certificate Manager Orchestrator** - -In Keyfactor Command create a new Certificate Store Type similar to the one below: - -#### STORE TYPE CONFIGURATION -SETTING TAB | CONFIG ELEMENT | DESCRIPTION -------|-----------|------------------ -Basic |Name |Descriptive name for the Store Type. Example: Google Cloud Certificate Manager -Basic |Short Name |The name that identifies the registered functionality of the orchestrator. Must be GcpCertMgr -Basic |Custom Capability|Unchecked -Basic |Job Types |Inventory, Add, and Remove are the supported job types -Basic |Needs Server |Unchecked -Basic |Blueprint Allowed |Unchecked -Basic |Requires Store Password |Unchecked -Basic |Supports Entry Password |Unchecked -Advanced |Store Path Type| Fixed -Advanced |Store Path Type Value (the textbox that appears below Store Path Type when Store Path Type is set to "Fixed") |n/a -Advanced |Supports Custom Alias |Required -Advanced |Private Key Handling |Required -Advanced |PFX Password Style |Default -Custom Fields|Google Cloud Platform Project Location/Region|Name:Location, Display Name:Location, Type:String, Default Value:global, Required:False -Custom Fields|The file name of the Google Cloud Service Account Key File installed in the same folder as the orchestrator extension. Empty if the orchestrator server resides in GCP and you are not using a service account key |Name:Service Account Key File Name, Type:String, Default Value: (leave blank), Required:True -Entry Parameters|N/A| There are no Entry Parameters - -**Basic Settings:** - -![](images/CertStoreType-Basic.gif) - -**Advanced Settings:** - -![](images/CertStoreType-Advanced.gif) - -**Custom Fields:** - -![](images/CertStoreType-CustomFields.gif) -![](images/CertStoreType-CustomField-Location.gif) -![](images/CertStoreType-CustomField-ServiceAccountKey.gif) - -**Entry Params:** - -![](images/CertStoreType-EntryParameters.gif) - -**2. Register the GCP Certificate Manager Orchestrator with Keyfactor** -See Keyfactor InstallingKeyfactorOrchestrators.pdf Documentation. Get from your Keyfactor contact/representative. - -**3. Create a GCP Certificate Manager Certificate Store within Keyfactor Command** -In Keyfactor Command create a new Certificate Store similar to the one below - -![](images/CertStoreSettings.gif) - -#### STORE CONFIGURATION -CONFIG ELEMENT |DESCRIPTION -----------------|--------------- -Category |The type of certificate store to be configured. Select category based on the display name configured above "GCP Certificate Manager". -Container |This is a logical grouping of like stores. This configuration is optional and does not impact the functionality of the store. -Client Machine |Your GCP Project ID for your account. -Store Path |This is not used and should be defaulted to n/a per the certificate store type set up. -Orchestrator |This is the orchestrator server registered with the appropriate capabilities to manage this certificate store type. -Location|**global** is the default but could be another region based on the project. -Service Account Key File Name | The name of the file containing the GCP Service Account JSON formatted key previously downloaded. Keep this optional field blank if the Keyfactor Orchestrator Service is running from an authenticated VM within Google Cloud. -Update Server User Name |Click and select No Value. -Update Server Password |Click and select No Value. -Use SSL |This should be checked. -Inventory Schedule |The interval that the system will use to report on what certificates are currently in the store. - -