Skip to content

Commit ee9828c

Browse files
joevanwanzeeleKFjoevanwanzeeleKF
committed
Merge branch 'add_procedures_AB#81415' of https://github.com/Keyfactor/nexus-certificate-manager-caplugin into add_procedures_AB#81415
2 parents 9a5bbf8 + 91bc7cd commit ee9828c

3 files changed

Lines changed: 208 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
<h1 align="center" style="border-bottom: none">
2+
Nexus Certificate Manager AnyCA Gateway REST Plugin
3+
</h1>
4+
5+
<p align="center">
6+
<!-- Badges -->
7+
<img src="https://img.shields.io/badge/integration_status-prototype-3D1973?style=flat-square" alt="Integration Status: prototype" />
8+
<a href="https://github.com/Keyfactor/nexus-certificate-manager-caplugin/releases"><img src="https://img.shields.io/github/v/release/Keyfactor/nexus-certificate-manager-caplugin?style=flat-square" alt="Release" /></a>
9+
<img src="https://img.shields.io/github/issues/Keyfactor/nexus-certificate-manager-caplugin?style=flat-square" alt="Issues" />
10+
<img src="https://img.shields.io/github/downloads/Keyfactor/nexus-certificate-manager-caplugin/total?style=flat-square&label=downloads&color=28B905" alt="GitHub Downloads (all assets, all releases)" />
11+
</p>
12+
13+
<p align="center">
14+
<!-- TOC -->
15+
<a href="#support">
16+
<b>Support</b>
17+
</a>
18+
·
19+
<a href="#requirements">
20+
<b>Requirements</b>
21+
</a>
22+
·
23+
<a href="#installation">
24+
<b>Installation</b>
25+
</a>
26+
·
27+
<a href="#license">
28+
<b>License</b>
29+
</a>
30+
·
31+
<a href="https://github.com/orgs/Keyfactor/repositories?q=anycagateway">
32+
<b>Related Integrations</b>
33+
</a>
34+
</p>
35+
36+
37+
The Nexus Certificate Manager AnyCA Gateway REST Plugin integrates Keyfactor Command with Nexus Smart ID Certificate Manager via the Keyfactor AnyCA Gateway REST framework. It supports the following operations:
38+
39+
- **Certificate Enrollment** — issues certificates against a named Nexus CA token procedure (ProductID)
40+
- **Certificate Revocation** — revokes certificates by CA request ID
41+
- **Certificate Synchronization** — optional; see [Synchronization](#synchronization) below
42+
43+
## Compatibility
44+
45+
The Nexus Certificate Manager AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 25.2.0 and later.
46+
47+
## Support
48+
The Nexus Certificate Manager AnyCA Gateway REST plugin is open source and there is **no SLA**. Keyfactor will address issues as resources become available. Keyfactor customers may request escalation by opening up a support ticket through their Keyfactor representative.
49+
50+
> 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.
51+
52+
## Requirements
53+
54+
- The host URL for the Nexus Certificate Manager instance (including port), e.g. `https://192.168.1.10:8444`
55+
- A PFX certificate for authenticating into Nexus Certificate Manager, accessible on the Gateway host
56+
- The passphrase for the PFX certificate
57+
- Server-side signing (VRO mode) must be enabled in the Nexus Protocol Gateway `api.properties`
58+
59+
## Installation
60+
61+
1. Install the AnyCA Gateway REST per the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/InstallIntroduction.htm).
62+
63+
2. On the server hosting the AnyCA Gateway REST, download and unzip the latest [Nexus Certificate Manager AnyCA Gateway REST plugin](https://github.com/Keyfactor/nexus-certificate-manager-caplugin/releases/latest) from GitHub.
64+
65+
3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory:
66+
67+
68+
```shell
69+
Depending on your AnyCA Gateway REST version, copy the unzipped directory to one of the following locations:
70+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions
71+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net8.0\Extensions
72+
```
73+
74+
> The directory containing the Nexus Certificate Manager AnyCA Gateway REST plugin DLLs (`net6.0` or `net8.0`) can be named anything, as long as it is unique within the `Extensions` directory.
75+
76+
4. Restart the AnyCA Gateway REST service.
77+
78+
5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the Nexus Certificate Manager plugin by hovering over the ⓘ symbol to the right of the Gateway on the top left of the portal.
79+
80+
## Configuration
81+
82+
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:
83+
84+
* **Gateway Registration**
85+
86+
The Keyfactor Command server must trust the CA chain used by the Nexus Certificate Manager. Identify the Root and/or Subordinate CA, download the certificate chain, and import it into the Command server certificate store before configuring the gateway.
87+
88+
* **CA Connection**
89+
90+
Populate using the configuration fields collected in the [requirements](#requirements) section.
91+
92+
* **Host** - The URI of the Nexus Certificate Manager API, including port. Example: https://192.168.1.10:8444
93+
* **AuthCertificatePath** - The full path on the AnyCA Gateway host to the PFX certificate used for authenticating into Nexus Certificate Manager.
94+
* **AuthCertPassword** - The password for the PFX authentication certificate.
95+
* **Enabled** - Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available.
96+
* **SyncProcedureField** - Optional. Enables certificate synchronization. Set this to the name of the Nexus CA ExtendedCertSearch field (e.g. "field1") that your CA administrator has configured to store the issuing procedure name at enrollment time. When provided, Synchronize will read that field from each certificate to reconstruct its ProductID (procedure name). When omitted, Synchronize is disabled because the Nexus CA API does not natively return the issuing procedure with certificate records. NOTE: Configuring the Nexus CA to populate this field requires custom Java InputView development and AWB policy changes by a CA administrator. This configuration is outside the scope of Keyfactor support.
97+
98+
2. TODO Certificate Template Creation Step is a required section
99+
100+
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.
101+
102+
103+
## CA Connection Parameters
104+
105+
| Parameter | Required | Description |
106+
|---|---|---|
107+
| `Host` | Yes | The full URI of the Nexus Certificate Manager API, including port. Example: `https://192.168.1.10:8444` |
108+
| `AuthCertificatePath` | Yes | The full path on the AnyCA Gateway host to the PFX certificate used for mutual TLS authentication. Example: `C:\certs\nexus-officer.pfx` |
109+
| `AuthCertPassword` | Yes | The password for the PFX authentication certificate. |
110+
| `Enabled` | Yes | Enables or disables gateway functionality. Set to `false` to defer configuration. |
111+
| `SyncProcedureField` | No | Enables certificate synchronization. See [Synchronization](#synchronization) for full details. |
112+
113+
## Certificate Template (Product ID) Configuration
114+
115+
Each certificate template in Command must be associated with a **ProductID** that corresponds to a Nexus CA token procedure name. The plugin calls the `/procedures` endpoint at startup to populate the list of available procedures.
116+
117+
When enrolling, the procedure name from the selected template's ProductID is passed directly as the `procname` parameter in the enrollment request.
118+
119+
## Synchronization
120+
121+
By default, certificate synchronization is **disabled**. This is an intentional design decision: the Nexus CA REST API does not return the issuing procedure name in certificate list or detail responses, making it impossible to reconstruct the correct ProductID (procedure name) for each certificate during a sync. Without a valid ProductID, synchronized certificates cannot be associated with a certificate template in Command and will not appear in the UI.
122+
123+
### Enabling Synchronization via `SyncProcedureField`
124+
125+
Synchronization can be enabled by setting the optional `SyncProcedureField` CA connection parameter to the name of a Nexus CA `ExtendedCertSearch` field (e.g. `field1`) that your CA administrator has configured to store the issuing procedure name at enrollment time.
126+
127+
When `SyncProcedureField` is set:
128+
129+
- The sync operation pages through all certificates on the CA (500 per page)
130+
- For each certificate, it reads the value of the specified `ExtendedCertSearch` field as the ProductID
131+
- Certificates where the field is empty or missing are skipped and logged as warnings
132+
- Only certificates with a resolvable ProductID are written to Command
133+
134+
### CA-Side Configuration Requirements
135+
136+
> ⚠️ **This configuration is entirely outside the scope of Keyfactor support.** The steps below describe what is required on the Nexus CA side. Keyfactor takes no responsibility for the correctness, stability, or ongoing maintenance of this configuration.
137+
138+
To populate an `ExtendedCertSearch` field with the procedure name at enrollment time, a Nexus CA administrator must:
139+
140+
1. **Develop a custom Java InputView** — InputViews are Java programs that run inside the Nexus Registration Authority (RA) and populate certificate attributes at issuance time. Custom InputViews must be compiled into a `.jar`, deployed to the CM server's `lib` directory, and registered in `cm.conf`. This requires working knowledge of the Nexus InputView API (documented in the CM Developers Guide).
141+
142+
2. **Configure the InputView to write the procedure name into an `ExtendedCertSearch` field** — the `ExtendedCertSearch` database table supports six generic fields (`field1`–`field6`). The InputView must be written to set the desired field to the issuing procedure name during enrollment.
143+
144+
3. **Associate the InputView with token procedures in the AWB** — using the Administrator's Workbench, a CA administrator must select the new InputView for each token procedure. This change must be signed by two administration officers in accordance with Nexus CM's four-eyes policy.
145+
146+
4. **Set `SyncProcedureField`** on the Keyfactor CA connection to the field name used (e.g. `field1`).
147+
148+
### Important Limitations
149+
150+
- Certificates issued **before** the CA-side configuration change was made will not have the field populated and will be skipped during sync.
151+
- If the CA admin changes or repurposes the configured `ExtendedCertSearch` field, sync will silently produce incorrect results. The plugin will log warnings for affected certificates.
152+
- The `SyncProcedureField` value must exactly match the field name (case-insensitive): `field1`, `field2`, `field3`, `field4`, `field5`, or `field6`. Any other value will cause all certificates to be skipped during sync.
153+
154+
## CHANGELOG
155+
156+
See [CHANGELOG.md](../CHANGELOG.md).
157+
158+
159+
## License
160+
161+
Apache License 2.0, see [LICENSE](LICENSE).
162+
163+
## Related Integrations
164+
165+
See all [Keyfactor Any CA Gateways (REST)](https://github.com/orgs/Keyfactor/repositories?q=anycagateway).

‎docsource/configuration.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,8 @@ To populate an `ExtendedCertSearch` field with the procedure name at enrollment
7171
## CHANGELOG
7272

7373
See [CHANGELOG.md](../CHANGELOG.md).
74+
75+
## Certificate Template Creation Step
76+
77+
TODO Certificate Template Creation Step is a required section
78+

‎integration-manifest.json‎

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,41 @@
11
{
2-
"$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json",
3-
"integration_type": "anyca-plugin",
4-
"name": "Nexus Certificate Manager AnyCA REST Gateway Plugin",
5-
"status": "prototype",
6-
"support_level": "kf-community",
7-
"link_github": false,
8-
"update_catalog": false,
9-
"description": "Nexus Certificate Manager plugin for the AnyCA REST Gateway framework",
10-
"gateway_framework": "25.2.0",
11-
"release_dir": "nexus-certificate-manager-caplugin/bin/Release",
12-
"release_project": "nexus-certificate-manager-caplugin/NexusCertManagerCAPlugin.csproj",
13-
"about": {
14-
"carest": {
15-
"product_ids": [],
16-
"ca_plugin_config": [
17-
{
18-
"name": "Host",
19-
"description": "The URI of the Nexus Certificate Manager API, including port. Example: https://192.168.1.10:8444"
20-
},
21-
{
22-
"name": "AuthCertificatePath",
23-
"description": "The full path on the AnyCA Gateway host to the PFX certificate used for mutual TLS authentication. Example: C:\\certs\\nexus-officer.pfx"
24-
},
25-
{
26-
"name": "AuthCertPassword",
27-
"description": "The password for the PFX authentication certificate."
28-
},
29-
{
30-
"name": "Enabled",
31-
"description": "Flag to enable or disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available."
32-
},
33-
{
34-
"name": "SyncProcedureField",
35-
"description": "Optional. Enables certificate synchronization. Set to the name of the Nexus CA ExtendedCertSearch field (e.g. 'field1') that the CA administrator has configured to store the issuing procedure name. When omitted, synchronization is disabled. See documentation for CA-side configuration requirements."
2+
"$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json",
3+
"integration_type": "anyca-plugin",
4+
"name": "Nexus Certificate Manager AnyCA REST Gateway Plugin",
5+
"status": "prototype",
6+
"support_level": "kf-community",
7+
"link_github": false,
8+
"update_catalog": false,
9+
"description": "Nexus Certificate Manager plugin for the AnyCA REST Gateway framework",
10+
"gateway_framework": "25.2.0",
11+
"release_dir": "nexus-certificate-manager-caplugin/bin/Release",
12+
"release_project": "nexus-certificate-manager-caplugin/NexusCertManagerCAPlugin.csproj",
13+
"about": {
14+
"carest": {
15+
"product_ids": [],
16+
"ca_plugin_config": [
17+
{
18+
"name": "Host",
19+
"description": "The URI of the Nexus Certificate Manager API, including port. Example: https://192.168.1.10:8444"
20+
},
21+
{
22+
"name": "AuthCertificatePath",
23+
"description": "The full path on the AnyCA Gateway host to the PFX certificate used for authenticating into Nexus Certificate Manager."
24+
},
25+
{
26+
"name": "AuthCertPassword",
27+
"description": "The password for the PFX authentication certificate."
28+
},
29+
{
30+
"name": "Enabled",
31+
"description": "Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available."
32+
},
33+
{
34+
"name": "SyncProcedureField",
35+
"description": "Optional. Enables certificate synchronization. Set this to the name of the Nexus CA ExtendedCertSearch field (e.g. \"field1\") that your CA administrator has configured to store the issuing procedure name at enrollment time. When provided, Synchronize will read that field from each certificate to reconstruct its ProductID (procedure name). When omitted, Synchronize is disabled because the Nexus CA API does not natively return the issuing procedure with certificate records. NOTE: Configuring the Nexus CA to populate this field requires custom Java InputView development and AWB policy changes by a CA administrator. This configuration is outside the scope of Keyfactor support."
36+
}
37+
],
38+
"enrollment_config": []
3639
}
37-
],
38-
"enrollment_config": []
3940
}
40-
}
41-
}
41+
}

0 commit comments

Comments
 (0)