diff --git a/.github/workflows/keyfactor-configure-repository-workflow.yml b/.github/workflows/keyfactor-configure-repository-workflow.yml deleted file mode 100644 index daa0f96..0000000 --- a/.github/workflows/keyfactor-configure-repository-workflow.yml +++ /dev/null @@ -1,19 +0,0 @@ -name: Configure Repository Workflow -on: [workflow_dispatch] - -jobs: - call-update-topic: - uses: Keyfactor/actions/.github/workflows/kf-update-topics.yml@main - secrets: - token: ${{ secrets.GH_REPO_CONFIG }} - - call-update-description: - uses: Keyfactor/actions/.github/workflows/kf-update-description.yml@main - secrets: - token: ${{ secrets.GH_REPO_CONFIG }} - - call-update-teams: - uses: Keyfactor/actions/.github/workflows/kf-update-teams.yml@main - secrets: - token: ${{ secrets.GH_REPO_CONFIG }} - diff --git a/.github/workflows/keyfactor-merge-store-types.yml b/.github/workflows/keyfactor-merge-store-types.yml deleted file mode 100644 index e8b1e82..0000000 --- a/.github/workflows/keyfactor-merge-store-types.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Keyfactor Merge Cert Store Types -on: [workflow_dispatch] - -jobs: - get-manifest-properties: - runs-on: windows-latest - outputs: - update_catalog: ${{ steps.read-json.outputs.update_catalog }} - integration_type: ${{ steps.read-json.outputs.integration_type }} - steps: - - uses: actions/checkout@v3 - - name: Store json - id: read-json - shell: pwsh - run: | - $json = Get-Content integration-manifest.json | ConvertFrom-Json - $myvar = $json.update_catalog - echo "update_catalog=$myvar" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append - $myvar = $json.integration_type - echo "integration_type=$myvar" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append - - call-update-store-types-workflow: - needs: get-manifest-properties - if: needs.get-manifest-properties.outputs.integration_type == 'orchestrator' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') - uses: Keyfactor/actions/.github/workflows/update-store-types.yml@main - secrets: - token: ${{ secrets.UPDATE_STORE_TYPES }} diff --git a/.github/workflows/keyfactor-release-workflow.yml b/.github/workflows/keyfactor-release-workflow.yml new file mode 100644 index 0000000..3071ff4 --- /dev/null +++ b/.github/workflows/keyfactor-release-workflow.yml @@ -0,0 +1,20 @@ +name: Keyfactor Release 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 }} + \ No newline at end of file diff --git a/.github/workflows/keyfactor-starter-workflow.yml b/.github/workflows/keyfactor-starter-workflow.yml deleted file mode 100644 index eb977c6..0000000 --- a/.github/workflows/keyfactor-starter-workflow.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: Starter Workflow -on: [workflow_dispatch, push, pull_request] - -jobs: - call-create-github-release-workflow: - uses: Keyfactor/actions/.github/workflows/github-release.yml@main - - call-assign-from-json-workflow: - uses: Keyfactor/actions/.github/workflows/assign-env-from-json.yml@main - - call-dotnet-build-and-release-workflow: - needs: [call-create-github-release-workflow, call-assign-from-json-workflow] - uses: Keyfactor/actions/.github/workflows/dotnet-build-and-release.yml@main - with: - release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} - release_url: ${{ needs.call-create-github-release-workflow.outputs.release_url }} - release_dir: ${{ needs.call-assign-from-json-workflow.outputs.release_dir }} - - secrets: - token: ${{ secrets.PRIVATE_PACKAGE_ACCESS }} - - call-generate-readme-workflow: - if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' - uses: Keyfactor/actions/.github/workflows/generate-readme.yml@main - secrets: - token: ${{ secrets.APPROVE_README_PUSH }} - - call-update-catalog-workflow: - needs: call-assign-from-json-workflow - if: needs.call-assign-from-json-workflow.outputs.update_catalog == 'True' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') - uses: Keyfactor/actions/.github/workflows/update-catalog.yml@main - secrets: - token: ${{ secrets.SDK_SYNC_PAT }} \ No newline at end of file diff --git a/README.md b/README.md index dc98db0..452e02b 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,138 @@ -# Signum Orchestrator Extension - -The Signum Orchestrator Extension allows for the Inventorying of Signum private certificates. Discovery, Managment, and ReEnrollment are NOT supported in this integration. A Signum instance must be installed to use this integration along with the ability to consume Signum SOAP-based API endpoints using basic authentication. - -#### Integration status: Production - Ready for use in production environments. - - -## About the Keyfactor Universal Orchestrator Extension +

+ Signum Universal Orchestrator Extension +

+ +

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

-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. +

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

-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. +## Overview +The Signum Universal Orchestrator extension enables seamless integration between Keyfactor Command and the Signum platform for remote management of cryptographic certificates. Signum uses certificates for securing communications and ensuring the authenticity and integrity of data exchanged within its ecosystem. -## Support for Signum Orchestrator Extension +In Keyfactor Command, defined Certificate Stores of the Certificate Store Type represent collections of certificates or a single certificate stored in a remote location. For the Signum integration, these Certificate Stores refer to endpoints within the Signum platform that handle certificates as specified in the integration configuration. This setup allows for efficient management, inventory, and automation of certificate-related operations within the Signum environment. -Signum Orchestrator Extension is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative. +## Compatibility -###### 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. +This integration is compatible with Keyfactor Universal Orchestrator version 10.4.1 and later. +## Support +The Signum 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. ---- +## Installation +Before installing the Signum Universal Orchestrator extension, it's recommended to 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. +1. Follow the [requirements section](docs/signum.md#requirements) to configure a Service Account and grant necessary API permissions. +
Requirements -## Keyfactor Version Supported + ### Signum Orchestrator Extension Installation + 1. Create the Signum certificate store type manually in Keyfactor Command by clicking on Settings (the gear icon on the top right) => Certificate Store Types => Add and then entering the settings described in the next section - Certificate Store Type Settings, OR by utilizing the CURL script found under the Certificate Store Type CURL Script folder in this repo. + 2. Stop the Keyfactor Universal Orchestrator Service for the orchestrator you plan to install this extension to run on. + 3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "Extensions" folder. Underneath that, create a new folder named "Signum" (you may choose to use a different name if you wish). + 4. Download the latest version of the Signum Orchestrator Extension from [GitHub](https://github.com/Keyfactor/signum-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. + 5. Copy the contents of the download installation zip file to the folder created in Step 3. + 6. (Optional) If you decide to create the certificate store type with a short name different than the suggested value of "Signum", edit the manifest.json file in the folder you created in step 3, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the certificate store type in Keyfactor Command. If you created it with the suggested value, this step can be skipped. + 7. Start the Keyfactor Universal Orchestrator Service. + 8. In Keyfactor Command, go to Orchestrators => Management and approve the Keyfactor Orchestrator containing the Signum capability that you just installed by selecting the orchestrator and clicking APPROVE. +   +   -The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.4.1 + ### Certificate Store Type Settings + Below are the values you need to enter if you choose to manually create the Signum certificate store type in the Keyfactor Command UI (related to Step 1 of Signum Orchestrator Extension Installation above). -## Platform Specific Notes + *Basic Tab:* + - **Name** – Required. The display name you wish to use for the new certificate store type. Suggested value - Signum + - **ShortName** - Required. Suggested value - Signum. If you choose to use a different value, please refer to Step 6 under Signum Orchestrator Extension Installation above. + - **Custom Capability** - Unchecked + - **Supported Job Types** - Inventory is the only one that should be checked. + - **Needs Server** - Checked + - **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. + - **Uses PoserShell** - Unchecked + - **Requires Store Password** - Unchecked. + - **Supports Entry Password** - Unchecked. -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 Renrollment| | | -|Supports Inventory|✓ |✓ | + *Advanced Tab:* + - **Store Path Type** - Fixed (with a value of NA underneath to represent "not applicable") + - **Supports Custom Alias** - Required + - **Private Key Handling** - Required + - **PFX Password Style** - Default + *Custom Fields Tab:* + None -## PAM Integration + *Entry Parameters:* + None +   +   -This orchestrator extension has the ability to connect to a variety of supported PAM providers to allow for the retrieval of various client hosted secrets right from the orchestrator server itself. This eliminates the need to set up the PAM integration on Keyfactor Command which may be in an environment that the client does not want to have access to their PAM provider. -The secrets that this orchestrator extension supports for use with a PAM Provider are: -|Name|Description| -|----|-----------| -|ServerUsername|The user id that will be used to authenticate to the Signum API endpoints| -|ServerPassword|The password that will be used to authenticate to the Signum API endpoints| - +
-It is not necessary to use a PAM Provider for all of the secrets available above. If a PAM Provider should not be used, simply enter in the actual value to be used, as normal. +2. Create Certificate Store Types for the Signum Orchestrator extension. -If a PAM Provider will be used for one of the fields above, start by referencing the [Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam). The GitHub repo for the PAM Provider to be used contains important information such as the format of the `json` needed. What follows is an example but does not reflect the `json` values for all PAM Providers as they have different "instance" and "initialization" parameter names and values. + * **Using kfutil**: -
General PAM Provider Configuration -

+ ```shell + # Signum + kfutil store-types create Signum + ``` + * **Manually**: + * [Signum](docs/signum.md#certificate-store-type-configuration) +3. Install the Signum Universal Orchestrator extension. + + * **Using kfutil**: On the server that that hosts the Universal Orchestrator, run the following command: -### Example PAM Provider Setup + ```shell + # Windows Server + kfutil orchestrator extension -e signum-orchestrator@latest --out "C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions" -To use a PAM Provider to resolve a field, in this example the __Server Password__ will be resolved by the `Hashicorp-Vault` provider, first install the PAM Provider extension from the [Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam) on the Universal Orchestrator. + # Linux + kfutil orchestrator extension -e signum-orchestrator@latest --out "/opt/keyfactor/orchestrator/extensions" + ``` -Next, complete configuration of the PAM Provider on the UO by editing the `manifest.json` of the __PAM Provider__ (e.g. located at extensions/Hashicorp-Vault/manifest.json). The "initialization" parameters need to be entered here: + * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Signum Universal Orchestrator extension](https://github.com/Keyfactor/signum-orchestrator/releases/latest). -~~~ json - "Keyfactor:PAMProviders:Hashicorp-Vault:InitializationInfo": { - "Host": "http://127.0.0.1:8200", - "Path": "v1/secret/data", - "Token": "xxxxxx" - } -~~~ +4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension. -After these values are entered, the Orchestrator needs to be restarted to pick up the configuration. Now the PAM Provider can be used on other Orchestrator Extensions. + * [Signum](docs/signum.md#certificate-store-configuration) -### Use the PAM Provider -With the PAM Provider configured as an extenion on the UO, a `json` object can be passed instead of an actual value to resolve the field with a PAM Provider. Consult the [Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam) for the specific format of the `json` object. -To have the __Server Password__ field resolved by the `Hashicorp-Vault` provider, the corresponding `json` object from the `Hashicorp-Vault` extension needs to be copied and filed in with the correct information: -~~~ json -{"Secret":"my-kv-secret","Key":"myServerPassword"} -~~~ +## License -This text would be entered in as the value for the __Server Password__, instead of entering in the actual password. The Orchestrator will attempt to use the PAM Provider to retrieve the __Server Password__. If PAM should not be used, just directly enter in the value for the field. -

-
- - - - ---- - - - -## Versioning - -The version number of a the Signum Orchestrator Extension can be verified by right clicking on the Signum.dll file in the Extensions/Signum installation folder, selecting Properties, and then clicking on the Details tab. -  -  -## Signum Orchestrator Extension Installation -1. Create the Signum certificate store type manually in Keyfactor Command by clicking on Settings (the gear icon on the top right) => Certificate Store Types => Add and then entering the settings described in the next section - Certificate Store Type Settings, OR by utilizing the CURL script found under the Certificate Store Type CURL Script folder in this repo. -2. Stop the Keyfactor Universal Orchestrator Service for the orchestrator you plan to install this extension to run on. -3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "Extensions" folder. Underneath that, create a new folder named "Signum" (you may choose to use a different name if you wish). -4. Download the latest version of the Signum Orchestrator Extension from [GitHub](https://github.com/Keyfactor/signum-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. -5. Copy the contents of the download installation zip file to the folder created in Step 3. -6. (Optional) If you decide to create the certificate store type with a short name different than the suggested value of "Signum", edit the manifest.json file in the folder you created in step 3, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the certificate store type in Keyfactor Command. If you created it with the suggested value, this step can be skipped. -7. Start the Keyfactor Universal Orchestrator Service. -8. In Keyfactor Command, go to Orchestrators => Management and approve the Keyfactor Orchestrator containing the Signum capability that you just installed by selecting the orchestrator and clicking APPROVE. -  -  -## Certificate Store Type Settings -Below are the values you need to enter if you choose to manually create the Signum certificate store type in the Keyfactor Command UI (related to Step 1 of Signum Orchestrator Extension Installation above). - -*Basic Tab:* -- **Name** – Required. The display name you wish to use for the new certificate store type. Suggested value - Signum -- **ShortName** - Required. Suggested value - Signum. If you choose to use a different value, please refer to Step 6 under Signum Orchestrator Extension Installation above. -- **Custom Capability** - Unchecked -- **Supported Job Types** - Inventory is the only one that should be checked. -- **Needs Server** - Checked -- **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. -- **Uses PoserShell** - Unchecked -- **Requires Store Password** - Unchecked. -- **Supports Entry Password** - Unchecked. - -*Advanced Tab:* -- **Store Path Type** - Fixed (with a value of NA underneath to represent "not applicable") -- **Supports Custom Alias** - Required -- **Private Key Handling** - Required -- **PFX Password Style** - Default - -*Custom Fields Tab:* -None - -*Entry Parameters:* -None -  -  -## Creating an Signum Certificate Store in Keyfactor Command -To create a Keyfactor Command certificate store of certificate store type Signum, go to Locations => Certificate Stores and click ADD. Then enter the following: -- Category - Signum (or the alternate ShortName value you entered when creating your certificate store type). -- Container - Optional. Refer to Keyfactor Command documentation about this feature. -- Client Machine - The URL that will be used as the base URL for Signum endpoint calls. Should be something like https://{base url for your signum install}:8888/rtadminservice.svc/basic. The port number of 8888 is a convention that is generally followed in Signum installations, but yours may vary. The "/basic" at the end is required, as this integration makes use of Basic Authentication only when consuming the Signum SOAP API library. -- Store Path - Not used and hardcoded to NA for "not applicable" -- Server Username and Server Password - The id/password credentials that have authorization to execute Signum SOAP endpoints in your Signum environment. -### License -[Apache](https://apache.org/licenses/LICENSE-2.0) +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/docs/signum.md b/docs/signum.md new file mode 100644 index 0000000..644b21e --- /dev/null +++ b/docs/signum.md @@ -0,0 +1,168 @@ +## Signum + +The Signum Certificate Store Type in Keyfactor Command is designed to facilitate the management and automation of cryptographic certificates within the Signum platform. Specifically, it defines how certificates are stored, managed, and retrieved from Signum endpoints using the Keyfactor Universal Orchestrator extension. + +### What Does the Certificate Store Type Do? +The Certificate Store Type enables Keyfactor Command to interface with the Signum platform, allowing users to perform various certificate management tasks such as inventory, adding, and removing certificates. It streamlines the process of handling certificates, ensuring consistency and reliability in certificate operations. + +### What Does It Represent? +In this context, the Certificate Store Type represents a configuration that maps to endpoints within the Signum platform. These endpoints are defined to handle certificates and integrate with the Signum SOAP API for secure communications and operations. + +### Caveats +One significant caveat to note is that the integration utilizes Basic Authentication when consuming the Signum SOAP API library. Therefore, it's crucial to ensure that the credentials used possess the appropriate authorization to execute the required Signum SOAP endpoints. + +### SDK Usage +The Signum Certificate Store Type does not rely on an SDK. Instead, it uses direct SOAP API calls for its operations. This simplifies the integration but also underscores the importance of accurate endpoint configuration. + +### Significant Limitations or Areas for Confusion +There are a few key areas to be aware of: +- The `Store Path` parameter is fixed and hardcoded to `NA`, representing "not applicable." +- The Store relies on a base URL configuration, which typically follows the pattern `https://{base url for your signum install}:8888/rtadminservice.svc/basic`, and uses Basic Authentication only. +- Custom capability is not enabled, limiting flexibility for advanced customizations without altering the base configuration significantly. + +Understanding these key points and configuring the Certificate Store Type accordingly will help avoid potential pitfalls and ensure smooth operation within the Signum platform. + + + +### Supported Job Types + +| Job Name | Supported | +| -------- | --------- | +| Inventory | ✅ | +| Management Add | | +| Management Remove | | +| Discovery | | +| Create | | +| Reenrollment | | + +## Requirements + +### Signum Orchestrator Extension Installation +1. Create the Signum certificate store type manually in Keyfactor Command by clicking on Settings (the gear icon on the top right) => Certificate Store Types => Add and then entering the settings described in the next section - Certificate Store Type Settings, OR by utilizing the CURL script found under the Certificate Store Type CURL Script folder in this repo. +2. Stop the Keyfactor Universal Orchestrator Service for the orchestrator you plan to install this extension to run on. +3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "Extensions" folder. Underneath that, create a new folder named "Signum" (you may choose to use a different name if you wish). +4. Download the latest version of the Signum Orchestrator Extension from [GitHub](https://github.com/Keyfactor/signum-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. +5. Copy the contents of the download installation zip file to the folder created in Step 3. +6. (Optional) If you decide to create the certificate store type with a short name different than the suggested value of "Signum", edit the manifest.json file in the folder you created in step 3, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the certificate store type in Keyfactor Command. If you created it with the suggested value, this step can be skipped. +7. Start the Keyfactor Universal Orchestrator Service. +8. In Keyfactor Command, go to Orchestrators => Management and approve the Keyfactor Orchestrator containing the Signum capability that you just installed by selecting the orchestrator and clicking APPROVE. +  +  + +### Certificate Store Type Settings +Below are the values you need to enter if you choose to manually create the Signum certificate store type in the Keyfactor Command UI (related to Step 1 of Signum Orchestrator Extension Installation above). + +*Basic Tab:* +- **Name** – Required. The display name you wish to use for the new certificate store type. Suggested value - Signum +- **ShortName** - Required. Suggested value - Signum. If you choose to use a different value, please refer to Step 6 under Signum Orchestrator Extension Installation above. +- **Custom Capability** - Unchecked +- **Supported Job Types** - Inventory is the only one that should be checked. +- **Needs Server** - Checked +- **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. +- **Uses PoserShell** - Unchecked +- **Requires Store Password** - Unchecked. +- **Supports Entry Password** - Unchecked. + +*Advanced Tab:* +- **Store Path Type** - Fixed (with a value of NA underneath to represent "not applicable") +- **Supports Custom Alias** - Required +- **Private Key Handling** - Required +- **PFX Password Style** - Default + +*Custom Fields Tab:* +None + +*Entry Parameters:* +None +  +  + + + +## Certificate Store Type Configuration + +The recommended method for creating the `Signum` Certificate Store Type is to use [kfutil](https://github.com/Keyfactor/kfutil). After installing, use the following command to create the `` Certificate Store Type: + +```shell +kfutil store-types create Signum +``` + +
Signum + +Create a store type called `Signum` with the attributes in the tables below: + +### Basic Tab +| Attribute | Value | Description | +| --------- | ----- | ----- | +| Name | Signum | Display name for the store type (may be customized) | +| Short Name | Signum | Short display name for the store type | +| Capability | Signum | Store type name orchestrator will register with. Check the box to allow entry of value | +| Supported Job Types (check the box for each) | Add, Discovery, Remove | Job types the extension supports | +| Supports Add | | Indicates that the Store Type supports Management Add | +| Supports Remove | | Indicates that the Store Type supports Management Remove | +| Supports Discovery | | Indicates that the Store Type supports Discovery | +| Supports Reenrollment | | Indicates that the Store Type supports Reenrollment | +| Supports Create | | Indicates that the Store Type supports store creation | +| Needs Server | ✅ | Determines if a target server name is required when creating store | +| Blueprint Allowed | | Determines if store type may be included in an Orchestrator blueprint | +| Uses PowerShell | | Determines if underlying implementation is PowerShell | +| Requires Store Password | | Determines if a store password is required when configuring an individual store. | +| Supports Entry Password | | Determines if an individual entry within a store can have a password. | + +The Basic tab should look like this: + +![Signum Basic Tab](../docsource/images/Signum-basic-store-type-dialog.png) + +### 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.) | + +The Advanced tab should look like this: + +![Signum Advanced Tab](../docsource/images/Signum-advanced-store-type-dialog.png) + +### 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 | Type | Default Value/Options | Required | Description | +| ---- | ------------ | ---- | --------------------- | -------- | ----------- | + + +The Custom Fields tab should look like this: + +![Signum Custom Fields Tab](../docsource/images/Signum-custom-fields-store-type-dialog.png) + + + +
+ +## Certificate Store Configuration + +After creating the `Signum` Certificate Store Type and installing the Signum Universal Orchestrator extension, you can create new [Certificate Stores](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store) to manage certificates in the remote platform. + +The following table describes the required and optional fields for the `Signum` certificate store type. + +| Attribute | Description | Attribute is PAM Eligible | +| --------- | ----------- | ------------------------- | +| Category | Select "Signum" or the customized certificate store name from the previous step. | | +| Container | Optional container to associate certificate store with. | | +| Client Machine | For the Client Machine field, enter the base URL used for Signum endpoint calls, formatted as 'https://{base url for your signum install}:8888/rtadminservice.svc/basic'. The port number is generally 8888, but it may vary depending on your Signum configuration. | | +| Store Path | For the Store Path field, enter 'NA' as it is hardcoded to represent 'not applicable' for Signum Certificate Stores. | | +| Orchestrator | Select an approved orchestrator capable of managing `Signum` certificates. Specifically, one with the `Signum` capability. | | + +* **Using kfutil** + + ```shell + # Generate a CSV template for the AzureApp certificate store + kfutil stores import generate-template --store-type-name Signum --outpath Signum.csv + + # Open the CSV file and fill in the required fields for each certificate store. + + # Import the CSV file to create the certificate stores + kfutil stores import csv --store-type-name Signum --file Signum.csv + ``` + +* **Manually with the Command UI**: In Keyfactor Command, navigate to Certificate Stores from the Locations Menu. Click the Add button to create a new Certificate Store using the attributes in the table above. \ No newline at end of file diff --git a/docsource/overview.md b/docsource/overview.md new file mode 100644 index 0000000..b87e096 --- /dev/null +++ b/docsource/overview.md @@ -0,0 +1,6 @@ +## Overview + +The Signum Universal Orchestrator extension enables seamless integration between Keyfactor Command and the Signum platform for remote management of cryptographic certificates. Signum uses certificates for securing communications and ensuring the authenticity and integrity of data exchanged within its ecosystem. + +In Keyfactor Command, defined Certificate Stores of the Certificate Store Type represent collections of certificates or a single certificate stored in a remote location. For the Signum integration, these Certificate Stores refer to endpoints within the Signum platform that handle certificates as specified in the integration configuration. This setup allows for efficient management, inventory, and automation of certificate-related operations within the Signum environment. + diff --git a/docsource/signum.md b/docsource/signum.md new file mode 100644 index 0000000..9d1e035 --- /dev/null +++ b/docsource/signum.md @@ -0,0 +1,66 @@ +## Overview + +The Signum Certificate Store Type in Keyfactor Command is designed to facilitate the management and automation of cryptographic certificates within the Signum platform. Specifically, it defines how certificates are stored, managed, and retrieved from Signum endpoints using the Keyfactor Universal Orchestrator extension. + +### What Does the Certificate Store Type Do? +The Certificate Store Type enables Keyfactor Command to interface with the Signum platform, allowing users to perform various certificate management tasks such as inventory, adding, and removing certificates. It streamlines the process of handling certificates, ensuring consistency and reliability in certificate operations. + +### What Does It Represent? +In this context, the Certificate Store Type represents a configuration that maps to endpoints within the Signum platform. These endpoints are defined to handle certificates and integrate with the Signum SOAP API for secure communications and operations. + +### Caveats +One significant caveat to note is that the integration utilizes Basic Authentication when consuming the Signum SOAP API library. Therefore, it's crucial to ensure that the credentials used possess the appropriate authorization to execute the required Signum SOAP endpoints. + +### SDK Usage +The Signum Certificate Store Type does not rely on an SDK. Instead, it uses direct SOAP API calls for its operations. This simplifies the integration but also underscores the importance of accurate endpoint configuration. + +### Significant Limitations or Areas for Confusion +There are a few key areas to be aware of: +- The `Store Path` parameter is fixed and hardcoded to `NA`, representing "not applicable." +- The Store relies on a base URL configuration, which typically follows the pattern `https://{base url for your signum install}:8888/rtadminservice.svc/basic`, and uses Basic Authentication only. +- Custom capability is not enabled, limiting flexibility for advanced customizations without altering the base configuration significantly. + +Understanding these key points and configuring the Certificate Store Type accordingly will help avoid potential pitfalls and ensure smooth operation within the Signum platform. + +## Requirements + +### Signum Orchestrator Extension Installation +1. Create the Signum certificate store type manually in Keyfactor Command by clicking on Settings (the gear icon on the top right) => Certificate Store Types => Add and then entering the settings described in the next section - Certificate Store Type Settings, OR by utilizing the CURL script found under the Certificate Store Type CURL Script folder in this repo. +2. Stop the Keyfactor Universal Orchestrator Service for the orchestrator you plan to install this extension to run on. +3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "Extensions" folder. Underneath that, create a new folder named "Signum" (you may choose to use a different name if you wish). +4. Download the latest version of the Signum Orchestrator Extension from [GitHub](https://github.com/Keyfactor/signum-orchestrator). Click on the "Latest" release link on the right hand side of the main page and download the first zip file. +5. Copy the contents of the download installation zip file to the folder created in Step 3. +6. (Optional) If you decide to create the certificate store type with a short name different than the suggested value of "Signum", edit the manifest.json file in the folder you created in step 3, and modify each "ShortName" in each "Certstores.{ShortName}.{Operation}" line with the ShortName you used to create the certificate store type in Keyfactor Command. If you created it with the suggested value, this step can be skipped. +7. Start the Keyfactor Universal Orchestrator Service. +8. In Keyfactor Command, go to Orchestrators => Management and approve the Keyfactor Orchestrator containing the Signum capability that you just installed by selecting the orchestrator and clicking APPROVE. +  +  + +### Certificate Store Type Settings +Below are the values you need to enter if you choose to manually create the Signum certificate store type in the Keyfactor Command UI (related to Step 1 of Signum Orchestrator Extension Installation above). + +*Basic Tab:* +- **Name** – Required. The display name you wish to use for the new certificate store type. Suggested value - Signum +- **ShortName** - Required. Suggested value - Signum. If you choose to use a different value, please refer to Step 6 under Signum Orchestrator Extension Installation above. +- **Custom Capability** - Unchecked +- **Supported Job Types** - Inventory is the only one that should be checked. +- **Needs Server** - Checked +- **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. +- **Uses PoserShell** - Unchecked +- **Requires Store Password** - Unchecked. +- **Supports Entry Password** - Unchecked. + +*Advanced Tab:* +- **Store Path Type** - Fixed (with a value of NA underneath to represent "not applicable") +- **Supports Custom Alias** - Required +- **Private Key Handling** - Required +- **PFX Password Style** - Default + +*Custom Fields Tab:* +None + +*Entry Parameters:* +None +  +  + diff --git a/integration-manifest.json b/integration-manifest.json index 16867e2..4ab65df 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -1,63 +1,65 @@ -{ - "$schema": "https://keyfactor.github.io/integration-manifest-schema.json", - "integration_type": "orchestrator", - "name": "Signum Orchestrator Extension", - "status": "production", - "support_level": "kf-supported", - "description": "The Signum Orchestrator Extension allows for the Inventorying of Signum private certificates. Discovery, Managment, and ReEnrollment are NOT supported in this integration. A Signum instance must be installed to use this integration along with the ability to consume Signum SOAP-based API endpoints using basic authentication.", - "link_github": true, - "update_catalog": true, - "release_dir": "Signum/bin/Release", - "about": { - "orchestrator": { - "UOFramework": "10.4.1", - "pam_support": true, - "win": { - "supportsCreateStore": false, - "supportsDiscovery": false, - "supportsManagementAdd": false, - "supportsManagementRemove": false, - "supportsReenrollment": false, - "supportsInventory": true - }, - "linux": { - "supportsCreateStore": false, - "supportsDiscovery": false, - "supportsManagementAdd": false, - "supportsManagementRemove": false, - "supportsReenrollment": false, - "supportsInventory": true - }, - "store_types": [ - { - "Name": "Signum", - "ShortName": "Signum", - "Capability": "Signum", - "LocalStore": false, - "SupportedOperations": { - "Add": false, - "Create": false, - "Discovery": false, - "Enrollment": false, - "Remove": false - }, - "Properties": [], - "EntryParameters": [], - "PasswordOptions": { - "EntrySupported": false, - "StoreRequired": false, - "Style": "Default" - }, - "StorePathType": "", - "StorePathValue": "na", - "PrivateKeyAllowed": "Required", - "JobProperties": [], - "ServerRequired": true, - "PowerShell": false, - "BlueprintAllowed": false, - "CustomAliasAllowed": "Required" - } - ] - } - } -} +{ + "$schema": "/Users/hroszell/coding/dev/staff-tools/keyfactor.github.io/v2/integration-manifest-schema.json", + "integration_type": "orchestrator", + "name": "Signum Orchestrator Extension", + "status": "production", + "support_level": "kf-supported", + "description": "The Signum Orchestrator Extension allows for the Inventorying of Signum private certificates. Discovery, Managment, and ReEnrollment are NOT supported in this integration. A Signum instance must be installed to use this integration along with the ability to consume Signum SOAP-based API endpoints using basic authentication.", + "link_github": true, + "update_catalog": true, + "release_dir": "Signum/bin/Release", + "about": { + "orchestrator": { + "UOFramework": "10.4.1", + "pam_support": true, + "win": { + "supportsCreateStore": false, + "supportsDiscovery": false, + "supportsManagementAdd": false, + "supportsManagementRemove": false, + "supportsReenrollment": false, + "supportsInventory": true + }, + "linux": { + "supportsCreateStore": false, + "supportsDiscovery": false, + "supportsManagementAdd": false, + "supportsManagementRemove": false, + "supportsReenrollment": false, + "supportsInventory": true + }, + "store_types": [ + { + "Name": "Signum", + "ShortName": "Signum", + "Capability": "Signum", + "LocalStore": false, + "SupportedOperations": { + "Add": false, + "Create": false, + "Discovery": false, + "Enrollment": false, + "Remove": false + }, + "Properties": [], + "EntryParameters": [], + "PasswordOptions": { + "EntrySupported": false, + "StoreRequired": false, + "Style": "Default" + }, + "StorePathType": "", + "StorePathValue": "na", + "PrivateKeyAllowed": "Required", + "JobProperties": [], + "ServerRequired": true, + "PowerShell": false, + "BlueprintAllowed": false, + "CustomAliasAllowed": "Required", + "ClientMachineDescription": "For the Client Machine field, enter the base URL used for Signum endpoint calls, formatted as 'https://{base url for your signum install}:8888/rtadminservice.svc/basic'. The port number is generally 8888, but it may vary depending on your Signum configuration.", + "StorePathDescription": "For the Store Path field, enter 'NA' as it is hardcoded to represent 'not applicable' for Signum Certificate Stores." + } + ] + } + } +} \ No newline at end of file