Merge to main

.github/workflows/keyfactor-bootstrap-workflow-v3.yml

@@ -0,0 +1,20 @@
+name: Keyfactor Bootstrap Workflow
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, closed, synchronize, edited, reopened]
+  push:
+  create:
+    branches:
+      - 'release-*.*'
+
+jobs:
+  call-starter-workflow:
+    uses: keyfactor/actions/.github/workflows/starter.yml@v3
+    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 }}

CHANGELOG.md

@@ -0,0 +1,6 @@
+1.0.0  
+Inital Release.  Support for Enroll, Sync, and Revocation. 
+
+1.0.1  
+Bugfix - sync records with null serial    
+Bugfix - Fix for custom fields in enrollment  

README.md

@@ -1,93 +1,122 @@
-# cpr-cagateway-template
+<h1 align="center" style="border-bottom: none">
+    Sectigo Certificate Manager   Gateway AnyCA Gateway REST Plugin
+</h1>
 
-## Template for new CA Gateway integrations
+<p align="center">
+  <!-- Badges -->
+<img src="https://img.shields.io/badge/integration_status-production-3D1973?style=flat-square" alt="Integration Status: production" />
+<a href="https://github.com/Keyfactor/sectigo-scm-caplugin/releases"><img src="https://img.shields.io/github/v/release/Keyfactor/sectigo-scm-caplugin?style=flat-square" alt="Release" /></a>
+<img src="https://img.shields.io/github/issues/Keyfactor/sectigo-scm-caplugin?style=flat-square" alt="Issues" />
+<img src="https://img.shields.io/github/downloads/Keyfactor/sectigo-scm-caplugin/total?style=flat-square&label=downloads&color=28B905" alt="GitHub Downloads (all assets, all releases)" />
+</p>
 
-### Use this repository to create new integrations for new CA Gateway integration types. 
+<p align="center">
+  <!-- TOC -->
+  <a href="#support">
+    <b>Support</b>
+  </a> 
+  ·
+  <a href="#requirements">
+    <b>Requirements</b>
+  </a>
+  ·
+  <a href="#installation">
+    <b>Installation</b>
+  </a>
+  ·
+  <a href="#license">
+    <b>License</b>
+  </a>
+  ·
+  <a href="https://github.com/orgs/Keyfactor/repositories?q=anycagateway">
+    <b>Related Integrations</b>
+  </a>
+</p>
 
 
-1. [Use this repository](#using-the-repository)
-1. [Update the integration-manifest.json](#updating-the-integration-manifest.json)
-1. [Add Keyfactor Bootstrap Workflow (keyfactor-bootstrap-workflow.yml)](#add-bootstrap)
-1. [Create required branches](#create-required-branches)
-1. [Replace template files/folders](#replace-template-files-and-folders)
-1. [Create initial prerelease](#create-initial-prerelease)
----
+The Sectigo AnyCA Gateway REST plugin extends the capabilities of the Sectigo Certificate Manager to Keyfactor Command via the Keyfactor AnyCA Gateway REST. The plugin represents a fully featured AnyCA REST Plugin with the following capabilies:
+* SSL Certificate Synchronization
+    * Sync can be filtered by any available SSL Certificate List filter defined by the Cert Manager API
+    * All Sync jobs are treated as a full sync because the Cert Manager API does not allow for filtering based on a date/time stamp
+    * Certificates will only syncronize once.  If a certificate is found based on Serial Number for the managed CA, and its status is unchanged, it will be skipped for subsequent syncs to minimize impact on Cert Manager API load
+* SSL Certificate Enrollment
+   * Note about organizations.  The organization for enrollment is selected based on the Organization subject field, as well as any Department specified in the template configuration. If a department is specified, and that department exists within the organization and is valid for issuing certs, the department ID will be used. If no department is specified, the organization ID will be used if the organization is valid for issuing certs. If the organization/department are not valid for issuing certs, the enrollment will fail, as that is a required field for Sectigo.
+* SSL Certificate Revocation
 
-#### Using the repository
-1. Select the ```Use this template``` button at the top of this page
-1. Update the repository name following [these guidelines](https://keyfactorinc.sharepoint.com/sites/IntegrationWiki/SitePages/GitHub-Processes.aspx#repository-naming-conventions) 
-    1. All repositories must be in lower-case
-	1. General pattern: company-product-type
-	1. e.g. hashicorp-vault-orchestator
-1. Click the ```Create repository``` button
+## Compatibility
 
----
+The Sectigo Certificate Manager   Gateway AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 24.2.0 and later.
 
-#### Updating the integration-manifest.json
+## Support
+The Sectigo Certificate Manager   Gateway AnyCA Gateway REST plugin 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. 
 
-*The following properties must be updated in the integration-manifest.json*
+> 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.
 
-Clone the repository locally, use vsdev.io, or the GitHub online editor to update the file.
+## Requirements
 
-* "name": "Friendly name for the integration"
-	* This will be used in the readme file generation and catalog entries
-* "description": "Brief description of the integration."
-	* This will be used in the readme file generation
-	* If the repository description is empty this value will be used for the repository description upon creating a release branch
-* "release_dir": "PATH\\\TO\\\BINARY\\\RELEASE\\\OUTPUT\\\FOLDER"
-	* Path separators can be "\\\\" or "/"
-	* Be sure to specify the release folder name. This can be found by running a Release build and noting the output folder
-	* Example: "AzureAppGatewayOrchestrator\\bin\\Release"
-* "gateway_framework": "" string denoting the required command gateway framework version
----
+For each Organization/Department you plan on using through the gateway, in your Sectigo portal, go to that Organization, select Certificate Settings -> SSL Certificates, and check the "Enable Web/REST API" checkbox.  
+In addition, for the admin account you plan to use, make sure it has the API admin type selected in the portal.
 
-#### Add Bootstrap 
-Add Keyfactor Bootstrap Workflow (keyfactor-bootstrap-workflow.yml). This can be copied directly from the workflow templates or through the Actions tab
-* Directly:
-    1. Create a file named ```.github\workflows\keyfactor-bootstrap-workflow.yml``` 
-	1. Copy the contents of [keyfactor/.github/workflow-templates/keyfactor-bootstrap-workflow.yml](https://raw.githubusercontent.com/Keyfactor/.github/main/workflow-templates/keyfactor-bootstrap-workflow.yml) into the file created in the previous step
-* Actions tab:
-    1. Navigate to the [Actions tab](./actions) in the new repository
-	1. Click the ```New workflow``` button
-	1. Find the ```Keyfactor Bootstrap Workflow``` and click the ```Configure``` button
-	1. Click the ```Commit changes...``` button on this screen and the next to add the bootstrap workflow to the main branch
-
-A new build will run the tasks of a *Push* trigger on the main branch
+## Installation
 
-*Ensure there are no errors during the workflow run in the Actions tab.*
+1. Install the AnyCA Gateway REST per the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/InstallIntroduction.htm).
 
----
+2. On the server hosting the AnyCA Gateway REST, download and unzip the latest [Sectigo Certificate Manager   Gateway AnyCA Gateway REST plugin](https://github.com/Keyfactor/sectigo-scm-caplugin/releases/latest) from GitHub.
 
-#### Create required branches 
-1. Create a release branch from main: release-1.0
-1. Create a dev branch from the starting with the devops id in the format ab#\<DevOps-ID>, e.g. ab#53535. 
-    1. For the cleanest pull request merge, create the dev branch from the release branch. 
-	1. Optionally, add a suffix to the branch name indicating initial release. e.g. ab#53535-initial-release
+3. Copy the unzipped directory (usually called `net6.0`) to the Extensions directory:
 
----
+    ```shell
+    Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions
+    ```
 
+    > The directory containing the Sectigo Certificate Manager   Gateway AnyCA Gateway REST plugin DLLs (`net6.0`) can be named anything, as long as it is unique within the `Extensions` directory.
 
-#### Replace template files and folders
-1. Replace the contents of readme_source.md
-1. Create a CHANGELOG.md file in the root of the repository indicating ```1.0: Initial release```
-1. Replace the SampleOrchestratorExtension.sln solution file and SampleOrchestratorExtension folder with your new orchestrator dotnet solution
-1. Push your updates to the dev branch (ab#xxxxx)
+4. Restart the AnyCA Gateway REST service.
 
----
+5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the Sectigo Certificate Manager   Gateway plugin by hovering over the ⓘ symbol to the right of the Gateway on the top left of the portal.
 
+## Configuration
 
-#### Create initial prerelease
-1. Create a pull request from the dev branch to the release-1.0 branch
+1. Follow the [official AnyCA Gateway REST documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Gateway.htm) to define a new Certificate Authority, and use the notes below to configure the **Gateway Registration** and **CA Connection** tabs:
 
+    * **Gateway Registration**
 
-----
+        In order to enroll for certificates the Keyfactor Command server must trust the trust chain. Once you set your Root and/or Subordinate CA in your Sectigo account, make sure to download and import the certificate chain into the Command Server certificate store
 
-When the repository is ready for SE Demo, change the following property:
-* "status": "pilot"
+    * **CA Connection**
 
-When the integration has been approved by Support and Delivery teams, change the following property:
-* "status": "production"
+        Populate using the configuration fields collected in the [requirements](#requirements) section.
 
-If the repository is ready to be published in the public catalog, the following properties must be updated:
-* "update_catalog": true
-* "link_github": true
+        * **ApiEndpoint** - The Sectigo API endpoint to connect to. There are a few possible values, depending on your Sectigo account configuration. NOTE: If doing Certificate Auth, the endpoint should end in /private/ 
+        * **CustomerUri** - This is a static value that represents the Sectigo account name. This can be found as part of the portal login URL. Ex: https://hard.cert-manager.com/customer/{CustomerUri} 
+        * **AuthType** - This value must be either Password or Certificate. It will determine which credentials are used to connect to the API. NOTE: Certificate Auth will not work properly if there is a proxy doing TLS inspection. 
+        * **Username** - This is the username associated with the API login and will determine the security role in the Certificate Manager platform. 
+        * **Password** - If AuthType is set to Password, this is the password associated with the API login. Ignored for Certificate AuthType. 
+        * **ClientCertificate** - If AuthType is set to Certificate, this is the certificate the Gateway will use to authenticate to the API. 
+        * **PickupRetries** - This setting determines the number of times the service will attempt to download a certificate after successful enrollment. If the certificate cannot be downloaded during this period it will be picked up during the next sync. 
+        * **PickupDelay** - This is the number of seconds between retries. Be aware that the total # of retries times the number of seconds will be the maximum amount of time the Command portal will be occupied during enrollment. If the duration is too long, the request may timeout and cause unexpected results. 
+        * **PageSize** - This is the number of records that will be processed per API call during a sync. 
+        * **ExternalRequestorFieldName** - If you wish to be able to specify at enroll-time a requestor email address for enrollment notifications, first define a requestor field name in this setting. Afterwards, you can create a custom Enrollment Field in Command with that same name, and supply the email address in that enrollment field. If no custom requestor field is provided, the API will use the email address of the API user itself. 
+        * **SyncFilterProfileId** - Comma-separated list of profile IDs to filter the sync on. If not provided, all certificates will be returned. 
+        * **ForceCompleteSync** - By default, the sync only updates database records if the status of the certificate has changed. Set this to true to force all records to sync/update. 
+        * **Enabled** - Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available. 
+
+2. When defining templates, the product IDs are unique to your Sectigo account. Log in to your Sectigo portal and go to your product types, and you should be able to retrieve the ID numbers there.
+
+3. Follow the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Keyfactor.htm) to add each defined Certificate Authority to Keyfactor Command and import the newly defined Certificate Templates.
+
+4. In Keyfactor Command (v12.3+), for each imported Certificate Template, follow the [official documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Configuring%20Template%20Options.htm) to define enrollment fields for each of the following parameters:
+
+    * **MultiDomain** - This flag lets Keyfactor know if the certificate can contain multiple domain names. Depending on the setting, the SAN entries of the request will change to support Sectigo requirements. 
+    * **Organization** - If the organization name is provided here, the Sectigo gateway will use that organization name in requests instead of whatever is in the O= field in the request subject. 
+    * **Department** - If your Sectigo account is using department-level products, put the appropriate department name here. Previously, this was alternatively supplied in the OU= subject field, which is now deprecated. 
+
+
+
+## License
+
+Apache License 2.0, see [LICENSE](LICENSE).
+
+## Related Integrations
+
+See all [Keyfactor Any CA Gateways (REST)](https://github.com/orgs/Keyfactor/repositories?q=anycagateway).