-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Keyfactor
committed
Jan 29, 2024
1 parent
9e791dc
commit af6b210
Showing
1 changed file
with
105 additions
and
87 deletions.
There are no files selected for viewing
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,87 +1,105 @@ | ||
| # cpr-orchestrator-template | ||
|
|
||
| ## Template for new Orchestrator projects | ||
|
|
||
| Use this repository to create new integrations for orcehstrator types. | ||
|
|
||
|
|
||
| ## Update the following properties in the integration-manifest.json | ||
|
|
||
| * "name": "Friendly name for the integration" | ||
| * "description": "Brief description of the integration. This will be used in the readme file generation and should be used for the repository description as well" | ||
|
|
||
| For each platform (win and linux) define which capabilities are present for this orchestrator extension. You must update the boolean properties for both win and linux platforms. | ||
|
|
||
| * "supportsCreateStore" | ||
| * "supportsDiscovery" | ||
| * "supportsManagementAdd" | ||
| * "supportsManagementRemove" | ||
| * "supportsReenrollment" | ||
| * "supportsInventory" | ||
|
|
||
| ### Cert Store Definitions | ||
|
|
||
| The integration-manifest.json contains cert-store definitions for use with [kfutil](https://github.com/keyfactor/kfutil). | ||
| ``` | ||
| Sample definition | ||
| { | ||
| "A10vThunder": { | ||
| "Name": "A10vThunder", | ||
| "ShortName": "vThunderU", | ||
| "Capability": "vThunderU", | ||
| "SupportedOperations": { | ||
| "Add": true, | ||
| "Create": false, | ||
| "Discovery": false, | ||
| "Enrollment": false, | ||
| "Remove": true | ||
| }, | ||
| "Properties": [ | ||
| { | ||
| "StoreTypeId;omitempty": 0, | ||
| "Name": "protocol", | ||
| "DisplayName": "Protocol", | ||
| "Type": "String", | ||
| "DependsOn": "", | ||
| "DefaultValue": null, | ||
| "Required": true | ||
| }, | ||
| { | ||
| "StoreTypeId;omitempty": 0, | ||
| "Name": "allowInvalidCert", | ||
| "DisplayName": "Allow Invalid Cert", | ||
| "Type": "Bool", | ||
| "DependsOn": "", | ||
| "DefaultValue": "false", | ||
| "Required": true | ||
| } | ||
| ], | ||
| "EntryParameters": [], | ||
| "PasswordOptions": { | ||
| "EntrySupported": false, | ||
| "StoreRequired": false, | ||
| "Style": "Default" | ||
| }, | ||
| "StorePathType": "", | ||
| "StorePathValue": "", | ||
| "PrivateKeyAllowed": "Optional", | ||
| "JobProperties": [], | ||
| "ServerRequired": true, | ||
| "PowerShell": false, | ||
| "BlueprintAllowed": true, | ||
| "CustomAliasAllowed": "Required" | ||
| }, | ||
| ``` | ||
|
|
||
| ---- | ||
|
|
||
| When the repository is ready for SE Demo, change the following property: | ||
| * "status": "pilot" | ||
|
|
||
| When the integration has been approved by Support and Delivery teams, change the following property: | ||
| * "status": "production" | ||
|
|
||
| If the repository is ready to be published in the public catalog, the following properties must be updated: | ||
| * "update_catalog": true | ||
| * "link_github": true | ||
|
|
||
| # Integration Template | ||
|
|
||
| This project is meant to be a template to quickly build a basic integration product build. Currently in dev, a work in progress, | ||
|
|
||
| #### Integration status: Prototype - Demonstration quality. Not for use in customer environments. | ||
|
|
||
| ## About the Keyfactor Universal Orchestrator Extension | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| ## Support for Integration Template | ||
|
|
||
| Integration Template is open source and community supported, meaning that there is no support guaranteed from Keyfactor Support for these tools. | ||
|
|
||
| ###### 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. | ||
|
|
||
| --- | ||
|
|
||
|
|
||
| --- | ||
|
|
||
|
|
||
|
|
||
| ## Keyfactor Version Supported | ||
|
|
||
| The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.1 | ||
| ## Platform Specific Notes | ||
|
|
||
| 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| | | | ||
|
|
||
|
|
||
| ## PAM Integration | ||
|
|
||
| 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 into the server hosting the store| | ||
| |ServerPassword|The password that will be used to authenticate into the server hosting the store| | ||
| |StorePassword|The optional password used to secure the certificate store being managed| | ||
|
|
||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| <details><summary>General PAM Provider Configuration</summary> | ||
| <p> | ||
|
|
||
|
|
||
|
|
||
| ### Example PAM Provider Setup | ||
|
|
||
| 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. | ||
|
|
||
| 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: | ||
|
|
||
| ~~~ json | ||
| "Keyfactor:PAMProviders:Hashicorp-Vault:InitializationInfo": { | ||
| "Host": "http://127.0.0.1:8200", | ||
| "Path": "v1/secret/data", | ||
| "Token": "xxxxxx" | ||
| } | ||
| ~~~ | ||
|
|
||
| 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. | ||
|
|
||
| ### 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"} | ||
| ~~~ | ||
|
|
||
| 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. | ||
| </p> | ||
| </details> | ||
|
|
||
|
|
||
|
|
||
|
|
||
| --- | ||
|
|
||
|
|
||
|
|
||
| ### License | ||
| [Apache](https://apache.org/licenses/LICENSE-2.0) | ||
|
|