Skip to content

Commit 64b82c1

Browse files
bhillkeyfactorbhillkeyfactor
authored
Update configuration.md
1 parent c9394e2 commit 64b82c1

File tree

1 file changed

+143
-2
lines changed

1 file changed

+143
-2
lines changed

‎docsource/configuration.md‎

Lines changed: 143 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,151 @@
11
## Overview
22

3-
TODO Overview is a required section
3+
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:
4+
5+
* **CA Sync**:
6+
* Download all certificates issued by the HydrantId CA
7+
* Support for incremental and full synchronization
8+
* Automatic extraction of end-entity certificates from PEM chains
9+
* **Certificate Enrollment**:
10+
* Support certificate enrollment with new key pairs
11+
* Dynamic policy (profile) discovery from the CA
12+
* Intelligent renewal vs. re-issue logic based on certificate expiration
13+
* Support for PKCS#10 CSR format
14+
* Configurable certificate validity periods
15+
* **Certificate Revocation**:
16+
* Request revocation of previously issued certificates
17+
* Support for standard CRL revocation reasons
418

519
## Requirements
620

7-
TODO Requirements is a required section
21+
### HydrantId System Prerequisites
22+
23+
Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met:
24+
25+
1. **HydrantId Account**:
26+
- Active HydrantId account with API access enabled
27+
- Access to the HydrantId management portal
28+
- HydrantId Certificate Authority Service configured and operational
29+
30+
2. **API Credentials**:
31+
- HydrantId API Authentication ID (AuthId)
32+
- HydrantId API Authentication Key (AuthKey)
33+
- These credentials must have permissions for:
34+
- Certificate enrollment (CSR submission)
35+
- Certificate retrieval
36+
- Certificate revocation
37+
- Policy/profile listing
38+
39+
3. **Network Connectivity**:
40+
- Gateway server must have HTTPS access to the HydrantId API endpoint
41+
- Default endpoint format: `https://<environment>.hydrantid.com`
42+
- Example: `https://acm-stage.hydrantid.com` or `https://acm.hydrantid.com`
43+
- TLS 1.2 or higher must be supported
44+
45+
### Obtaining Required Configuration Information
46+
47+
#### 1. HydrantId Base URL
48+
49+
The HydrantId Base URL is the root endpoint for the HydrantId API.
50+
51+
**Common HydrantId environments:**
52+
- Production: `https://acm.hydrantid.com`
53+
- Staging: `https://acm-stage.hydrantid.com`
54+
- Custom instances may have different URLs
55+
56+
**To obtain your Base URL:**
57+
1. Contact your HydrantId account representative
58+
2. Check your HydrantId account documentation
59+
3. Verify the URL is accessible from the Gateway server
60+
61+
#### 2. API Authentication Credentials
62+
63+
The Gateway authenticates to HydrantId using Hawk authentication protocol with an AuthId and AuthKey pair.
64+
65+
**Steps to obtain API credentials:**
66+
67+
1. **Access HydrantId Portal**:
68+
- Log in to your HydrantId management portal
69+
- Navigate to API or Integration settings
70+
71+
2. **Generate API Credentials**:
72+
- Request API credentials from your HydrantId administrator
73+
- You will receive:
74+
- **AuthId**: A unique identifier for your API client
75+
- **AuthKey**: A secret key used for HMAC-based authentication
76+
- Store these credentials securely
77+
78+
3. **Verify Permissions**:
79+
- Ensure the API credentials have the following permissions:
80+
- Certificate enrollment (POST /api/v2/csr)
81+
- Certificate renewal (POST /api/v2/certificates/{id}/renew)
82+
- Certificate retrieval (GET /api/v2/certificates)
83+
- Certificate revocation (PATCH /api/v2/certificates/{id})
84+
- Policy listing (GET /api/v2/policies)
85+
86+
#### 3. Certificate Policies
87+
88+
Certificate policies define the types of certificates that can be issued. The plugin automatically discovers available policies from the HydrantId system.
89+
90+
**Policy discovery:**
91+
- Policies are automatically retrieved when the CA is configured
92+
- Policies appear in Keyfactor Command as "Product IDs" after CA registration
93+
- Each policy represents a certificate template configured in HydrantId
94+
95+
**To view available policies:**
96+
1. Policies are retrieved automatically using the GET /api/v2/policies endpoint
97+
2. Ensure the API credentials have permissions to list policies
98+
3. Policies will be displayed during CA configuration in the Gateway
99+
100+
#### 4. Certificate Validity Configuration
101+
102+
For each certificate template, you can configure:
103+
104+
| Parameter | Description | Example Values |
105+
|-----------|-------------|----------------|
106+
| **ValidityPeriod** | Time unit for certificate lifetime | `Days`, `Months`, `Years` |
107+
| **ValidityUnits** | Numeric value for the validity period | `365` (for days), `12` (for months), `2` (for years) |
108+
| **RenewalDays** | Days before expiration to trigger renewal vs. re-issue | `30`, `60`, `90` |
109+
110+
**Renewal vs. Re-issue Logic:**
111+
- If a certificate is within the RenewalDays window before expiration, the plugin performs a **renewal**
112+
- If a certificate is outside the RenewalDays window, the plugin performs a **re-issue** (new enrollment)
113+
114+
### Supported Revocation Reasons
115+
116+
The plugin supports the following standard CRL revocation reasons:
117+
118+
| Reason Code | Reason Name | HydrantId API Value |
119+
|-------------|-------------|---------------------|
120+
| 0 | Unspecified | `Unspecified` |
121+
| 1 | Key Compromise | `KeyCompromise` |
122+
| 2 | CA Compromise | `CaCompromise` |
123+
| 3 | Affiliation Changed | `AffiliationChanged` |
124+
| 4 | Superseded | `Superseded` |
125+
| 5 | Cessation of Operation | `CessationOfOperation` |
126+
127+
**Note**: Verify with your HydrantId administrator which revocation reasons are supported in your environment.
128+
129+
## Installation
130+
131+
1. Install the AnyCA Gateway REST per the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/InstallIntroduction.htm).
132+
133+
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.
134+
135+
3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory:
136+
137+
```shell
138+
Depending on your AnyCA Gateway REST version, copy the unzipped directory to one of the following locations:
139+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions
140+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net8.0\Extensions
141+
```
142+
143+
> 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.
144+
145+
4. Restart the AnyCA Gateway REST service.
146+
147+
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.
148+
8149

9150
## Gateway Registration
10151

0 commit comments

Comments
 (0)