Merged
Conversation
The HID Global HydrantId AnyCA Gateway REST plugin extends the capabilities of HydrantId Certificate Authority Service to Keyfactor Command via the Keyfactor AnyCA Gateway. This plugin leverages the HydrantId REST API with Hawk authentication to provide comprehensive certificate lifecycle management. The plugin represents a fully featured AnyCA Plugin with the following capabilities:
* **CA Sync**:
* Download all certificates issued by the HydrantId CA
* Support for incremental and full synchronization
* Automatic extraction of end-entity certificates from PEM chains
* **Certificate Enrollment**:
* Support certificate enrollment with new key pairs
* Dynamic policy (profile) discovery from the CA
* Intelligent renewal vs. re-issue logic based on certificate expiration
* Support for PKCS#10 CSR format
* Configurable certificate validity periods
* **Certificate Revocation**:
* Request revocation of previously issued certificates
* Support for standard CRL revocation reasons
---------
Co-authored-by: Keyfactor <keyfactor@keyfactor.github.io>
There was a problem hiding this comment.
Pull request overview
This PR merges version 1.0.1 from the release-1.0 branch to main, introducing SaaS containerization support and multi-framework targeting. The changes add an "Enabled" flag to allow CA connectors to be disabled without losing configuration, expand documentation significantly, and add support for both .NET 6.0 and .NET 8.0 frameworks.
Changes:
- Added an "Enabled" boolean flag to CA configuration for SaaS containerization scenarios
- Expanded documentation with detailed setup instructions, API credential requirements, and configuration examples
- Multi-targeted the plugin to support both .NET 6.0 and .NET 8.0 frameworks
- Updated integration manifest to support the new build configuration and Enabled flag
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| integration-manifest.json | Updated release directory structure and added Enabled field to CA plugin configuration |
| docsource/configuration.md | Significantly expanded with detailed prerequisites, API setup instructions, and configuration examples |
| README.md | Updated with comprehensive requirements section and configuration details, though contains duplicate content |
| HydrantCAProxy/HydrantIdCAPluginConfig.cs | Added Enabled flag property and configuration metadata |
| HydrantCAProxy/HydrantIdCAPlugin.csproj | Changed from single-target (net6.0) to multi-target (net6.0;net8.0) |
| HydrantCAProxy/HydrantIdCAPlugin.cs | Added Enabled flag initialization and checks in Ping/ValidateCAConnectionInfo methods |
| CHANGELOG.md | Updated with v1.0.1 release notes |
| .gitignore | Added local development file exclusions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
38
to
50
| { | ||
| certDataReader = certificateDataReader; | ||
| Config = configProvider; | ||
| var rawData = JsonConvert.SerializeObject(configProvider.CAConnectionData); | ||
| _config = JsonConvert.DeserializeObject<HydrantIdCAPluginConfig.Config>(rawData); | ||
| _logger.LogTrace($"Initialize - Enabled: {_config.Enabled}"); | ||
| } | ||
| catch (Exception ex) | ||
| { | ||
| _logger.LogError($"Failed to initialize GCP CAS CAPlugin: {ex}"); | ||
| _logger.LogError($"Failed to initialize HydrantId CAPlugin: {ex}"); | ||
| } | ||
| } | ||
|
|
There was a problem hiding this comment.
The Synchronize method does not check the Enabled flag before attempting to synchronize certificates from HydrantId. This is inconsistent with the Ping and ValidateCAConnectionInfo methods which skip operations when Enabled is false. When the CA is disabled, this method should return early to avoid unnecessary API calls and processing.
Comment on lines
291
to
311
| ## Installation | ||
|
|
||
| 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 [HID Global HydrantId AnyCA Gateway REST plugin](https://github.com/Keyfactor/hydrantid-caplugin/releases/latest) from GitHub. | ||
|
|
||
| 3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory: | ||
|
|
||
| ```shell | ||
| Depending on your AnyCA Gateway REST version, copy the unzipped directory to one of the following locations: | ||
| Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions | ||
| Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net8.0\Extensions | ||
| ``` | ||
|
|
||
| > The directory containing the HID Global HydrantId AnyCA Gateway REST plugin DLLs (`net6.0` or `net8.0`) can be named anything, as long as it is unique within the `Extensions` directory. | ||
|
|
||
| 4. Restart the AnyCA Gateway REST service. | ||
|
|
||
| 5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the HID Global HydrantId plugin by hovering over the ⓘ symbol to the right of the Gateway on the top left of the portal. | ||
|
|
||
|
|
There was a problem hiding this comment.
The README.md file contains duplicate Installation sections. The first Installation section appears at lines 172-191, and a second identical Installation section appears at lines 291-309. One of these sections should be removed to avoid redundancy and confusion.
Suggested change
| ## Installation | |
| 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 [HID Global HydrantId AnyCA Gateway REST plugin](https://github.com/Keyfactor/hydrantid-caplugin/releases/latest) from GitHub. | |
| 3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory: | |
| ```shell | |
| Depending on your AnyCA Gateway REST version, copy the unzipped directory to one of the following locations: | |
| Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions | |
| Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net8.0\Extensions | |
| ``` | |
| > The directory containing the HID Global HydrantId AnyCA Gateway REST plugin DLLs (`net6.0` or `net8.0`) can be named anything, as long as it is unique within the `Extensions` directory. | |
| 4. Restart the AnyCA Gateway REST service. | |
| 5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the HID Global HydrantId plugin by hovering over the ⓘ symbol to the right of the Gateway on the top left of the portal. |
Comment on lines
199
to
282
| ### CA Connection Configuration | ||
|
|
||
| When registering the HydrantId CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: | ||
|
|
||
| | Parameter | Description | Required | Example | | ||
| |-----------|-------------|----------|---------| | ||
| | **HydrantIdBaseUrl** | Full URL to the HydrantId API endpoint | Yes | `https://acm.hydrantid.com` or `https://acm-stage.hydrantid.com` | | ||
| | **HydrantIdAuthId** | API Authentication ID provided by HydrantId | Yes | `your-auth-id` | | ||
| | **HydrantIdAuthKey** | API Authentication Key provided by HydrantId | Yes | `your-secret-auth-key` | | ||
|
|
||
| ### Gateway Registration Notes | ||
|
|
||
| - Each defined Certificate Authority in the AnyCA Gateway REST can support one HydrantId API endpoint | ||
| - If you have multiple HydrantId environments or accounts, you must define multiple Certificate Authorities in the AnyCA Gateway | ||
| - Each CA configuration will manifest in Command as a separate CA entry | ||
| - The plugin uses Hawk authentication protocol for all API communications | ||
| - Authentication uses HMAC-SHA256 for secure API access | ||
| - The plugin automatically handles: | ||
| - Policy/template discovery | ||
| - Certificate status mapping | ||
| - End-entity certificate extraction from PEM chains | ||
| - Enrollment completion polling (30-second timeout) | ||
|
|
||
| ### Security Considerations | ||
|
|
||
| 1. **Credential Storage**: Store API credentials securely and restrict access to the Gateway configuration | ||
| 2. **Secret Management**: Consider using a secrets management system for AuthKey storage | ||
| 3. **Network Security**: Ensure TLS/SSL is properly configured for all API communications | ||
| 4. **Least Privilege**: Request API credentials with minimal required permissions | ||
| 5. **Audit Logging**: Enable comprehensive logging in both the Gateway and HydrantId for security monitoring | ||
| 6. **Credential Rotation**: Regularly rotate API credentials according to your security policy | ||
|
|
||
| **CA Connection** | ||
|
|
||
| Populate using the configuration fields collected in the [requirements](#requirements) section. | ||
|
|
||
| * **HydrantIdBaseUrl** - The base URL for the HydrantId API endpoint. For example, `https://acm.hydrantid.com` or `https://acm-stage.hydrantid.com`. | ||
| * **HydrantIdAuthId** - The API Authentication ID provided by HydrantId for API access. | ||
| * **HydrantIdAuthKey** - The API Authentication Key (secret) provided by HydrantId for API access. | ||
|
|
||
| 2. **Certificate Template Configuration** | ||
|
|
||
| After adding the CA to the Gateway, configure each certificate template: | ||
|
|
||
| 1. Navigate to the Templates/Products section for the newly added CA | ||
| 2. For each template (policy) discovered from HydrantId, configure: | ||
| - **ValidityPeriod**: Select `Days`, `Months`, or `Years` | ||
| - **ValidityUnits**: Enter the numeric value (e.g., `365` for one year in days) | ||
| - **RenewalDays**: Enter the renewal window in days (e.g., `30`) | ||
|
|
||
| Example configurations: | ||
| - **1-Year Certificate (Days)**: ValidityPeriod=`Days`, ValidityUnits=`365`, RenewalDays=`30` | ||
| - **2-Year Certificate (Years)**: ValidityPeriod=`Years`, ValidityUnits=`2`, RenewalDays=`60` | ||
| - **6-Month Certificate (Months)**: ValidityPeriod=`Months`, ValidityUnits=`6`, RenewalDays=`30` | ||
|
|
||
| 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. | ||
|
|
||
| * **CA Connection** | ||
|
|
||
| Populate using the configuration fields collected in the [requirements](#requirements) section. | ||
|
|
||
| * **HydrantIdBaseUrl** - The Base URL For the HydrantId Endpoint similar to https://acm-stage.hydrantid.com. Get this from HydrantId. | ||
| * **HydrantIdAuthId** - The AuthId Obtained from HydrantId. | ||
| * **HydrantIdAuthKey** - The AuthKey Obtained from HydrantId. | ||
| * **Enabled** - Flag to Enable or Disable the CA connector. | ||
|
|
||
| 2. ### Template (Product) Configuration | ||
|
|
||
| 2. Define [Certificate Profiles](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCP-Gateway.htm) and [Certificate Templates](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Gateway.htm) for the Certificate Authority as required. One Certificate Profile must be defined per Certificate Template. It's recommended that each Certificate Profile be named after the Product ID. | ||
| Each certificate template (policy) discovered from HydrantId requires configuration for enrollment: | ||
|
|
||
| The GCP CAS AnyCA Gateway REST plugin downloads all Certificate Templates in the configured GCP Region/Project and interprets them as 'Product IDs' in the Gateway Portal. | ||
| | Parameter | Description | Required | Example | | ||
| |-----------|-------------|----------|---------| | ||
| | **ValidityPeriod** | Time unit for certificate lifetime | Yes | `Days`, `Months`, or `Years` | | ||
| | **ValidityUnits** | Numeric value for the validity period | Yes | `365` (for 1 year in days), `12` (for 1 year in months), `2` (for 2 years) | | ||
| | **RenewalDays** | Days before expiration to trigger renewal | Yes | `30` (renew within 30 days of expiration) | | ||
|
|
||
| > For example, if the connected GCP project has the following Certificate Templates: | ||
| > | ||
| > * `ServerAuth` | ||
| > * `ClientAuth` | ||
| > | ||
| > The `Edit Templates` > `Product ID` dialog dropdown will show the following available 'ProductIDs': | ||
| > | ||
| > * `Default` -> Don't use a certificate template when enrolling certificates with this Template. | ||
| > * `ServerAuth` -> Use the `ServerAuth` certificate template in GCP when enrolling certificates with this Template. | ||
| > * `ClientAuth` -> Use the `ClientAuth` certificate template in GCP when enrolling certificates with this Template. | ||
| **Important Notes:** | ||
| - Template names (Product IDs) are automatically discovered from HydrantId using the GET /api/v2/policies endpoint | ||
| - The ValidityPeriod and ValidityUnits combine to determine the certificate lifetime | ||
| - RenewalDays determines the behavior for certificate renewal: | ||
| - Within window: Performs a renewal operation (maintains certificate lineage) | ||
| - Outside window: Performs a re-issue operation (new certificate enrollment) | ||
|
|
||
| 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. |
There was a problem hiding this comment.
The Configuration section contains duplicate and overlapping content. Lines 199-254 contain detailed CA Connection Configuration, Gateway Registration Notes, Security Considerations, and Certificate Template Configuration. This same information is then repeated in a different format at lines 256-282 under "CA Connection" and "Template (Product) Configuration". This creates confusion and redundancy. Consider consolidating this information into a single, well-organized section.
| - Remove template references from README | ||
| - Small bug fixes | ||
| # v1.0.1 | ||
| * SaaS Containerization Fixes, added enabled flag cleaned up some log messages |
There was a problem hiding this comment.
The CHANGELOG entry has a minor grammar issue. "added enabled flag cleaned up" should have proper punctuation. Consider: "SaaS Containerization Fixes, added enabled flag, and cleaned up some log messages" or "SaaS Containerization Fixes: added enabled flag and cleaned up some log messages".
Suggested change
| * SaaS Containerization Fixes, added enabled flag cleaned up some log messages | |
| * SaaS Containerization Fixes: added enabled flag and cleaned up some log messages |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Merge release-1.0 to main - Automated PR