Merge branch 'ab#62167' of https://github.com/Keyfactor/remote-file-o…

…rchestrator into ab#62167
Keyfactor · Sep 19, 2024 · 50089d4 · 50089d4
2 parents 194e5de + ce8977a
commit 50089d4
Show file tree

Hide file tree

Showing 2 changed files with 315 additions and 75 deletions.
diff --git a/README.md b/README.md
@@ -63,126 +63,176 @@ The Remote File Universal Orchestrator extension is supported by Keyfactor for K
 > 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 Remote File 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.
 
-The Remote File Universal Orchestrator extension implements 6 Certificate Store Types. Depending on your use case, you may elect to install one, or all of these Certificate Store Types. An overview for each type is linked below:
-* [RFJKS](docs/rfjks.md)
-* [RFPEM](docs/rfpem.md)
-* [RFPkcs12](docs/rfpkcs12.md)
-* [RFDER](docs/rfder.md)
-* [RFKDB](docs/rfkdb.md)
-* [RFORA](docs/rfora.md)
+Before installing the Remote File Universal Orchestrator extension, we recommend that you 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.
 
-<details><summary>RFJKS</summary>
+1. **Create Certificate Store Types in Keyfactor Command**  
+The Remote File Universal Orchestrator extension implements 6 Certificate Store Types. Depending on your use case, you may elect to install one, or all of these Certificate Store Types.
 
+    <details><summary>RFJKS</summary>
 
-1. Follow the [requirements section](docs/rfjks.md#requirements) to configure a Service Account and grant necessary API permissions.
 
-    <details><summary>Requirements</summary>
+    > More information on the RFJKS Certificate Store Type can be found [here](docs/rfjks.md).
 
-    <details>
-    <summary><b>Certificate stores hosted on Linux servers:</b></summary>
+    * **Create RFJKS using kfutil**:
 
-    1. The Remote File Orchestrator Extension makes use of a few common Linux commands when managing stores on Linux servers. If the credentials you will be connecting with need elevated access to run these commands or to access the certificate store files these commands operate against, you must set up the user id as a sudoer with no password necessary and set the config.json "UseSudo" value to "Y".  When RemoteFile is using orchestration, managing local or external certificate stores using SSH or WinRM, the security context is determined by the user id entered in the Keyfactor Command certificate store or discovery job screens.  When RemoteFile is running as an agent, managing local stores only, the security context is the user id running the Keyfactor Command Universal Orchestrator service account.  The full list of these commands below:
+        ```shell
+        # RFJKS
+        kfutil store-types create RFJKS
+        ```
 
-    |Shell Command|Used For|
-    |---|---|
-    |echo|Used to append a newline and terminate all commands sent.|
-    |find|Used by Discovery jobs to locate potential certificate stores on the file system.|
-    |cp|Used by Inventory and Management Add/Remove jobs to copy the certificate store file to a temporary file (only when an alternate download folder has been configured).|
-    |chown|Used by the Inventory and Management Add/Remove jobs to set the permissions on the temporary file (only when an alternate download folder has been configured).|
-    |tee|Used by Management Add/Remove jobs to copy the temporary uploaded certificate file to the certificate store file (only when an alternate upload folder has been configured).|
-    |rm|Used by Inventory and Management Add/Remove jobs to remove temporary files (only when an alternate upload/download folder has been configured).|
-    |install|Used by the Management Create Store job when initializing a certificate store file.|
-    |orapki|Oracle Wallet CLI utility used by Inventory and Management Add/Remove jobs to manipulate an Oracle Wallet certificate store.  Used for the RFORA store type only.|
-    |gskcapicmd|IBM Key Database CLI utility used by Inventory and Management Add/Remove jobs to manipulate an IBM Key Database certificate store.  Used for the RFKDB store type only.|  
+    * **Create RFJKS manually in the Command UI**:
+        
+        Refer to the [RFJKS](docs/rfjks.md#certificate-store-type-configuration) creation docs.
+    </details>
 
-    2. When orchestrating management of local or external certificate stores, the Remote File Orchestrator Extension makes use of SFTP and/or SCP to transfer files to and from the orchestrated server.  SFTP/SCP cannot make use of sudo, so all folders containing certificate stores will need to allow SFTP/SCP file transfer for the user assigned to the certificate store/discovery job.  If this is not possible, set the values in the config.json apprpriately to use an alternative upload/download folder that does allow SFTP/SCP file transfer.  If the certificate store/discovery job is configured for local (agent) access, the account running the Keyfactor Universal Orchestrator service must have access to read/write to the certificate store location, OR the config.json file must be set up to use the alternative upload/download file.  
+    <details><summary>RFPEM</summary>
 
-    3. SSH Authentication: When creating a Keyfactor certificate store for the remote file orchestrator extension, you may supply either a user id and password for the certificate store credentials (directly or through one of Keyfactor Command's PAM integrations), or supply a user id and SSH private key.  When using a password, the connection is attempted using SSH Password Authentication.  If that fails, Keyboard Interactive Authentication is automatically attempted.  One or both of these must be enabled on the Linux box being managed.  If private key authentication is desired, copy and paste the full SSH private key into the Password textbox (or pointer to the private key if using a PAM provider).  Please note that SSH Private Key Authentication is not available when running locally as an agent.  The following private key formats are supported: 
-    - PKCS#1 (BEGIN RSA PRIVATE KEY) 
-    - PKCS#8 (BEGIN PRIVATE KEY)
-    - ECDSA OPENSSH (BEGIN OPENSSH PRIVATE KEY)   
 
-    Please reference [Configuration File Setup](#configuration-file-setup) for more information on setting up the config.json file and [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) for more information on the items above.    
-    </details>  
+    > More information on the RFPEM Certificate Store Type can be found [here](docs/rfpem.md).
 
-    <details>  
-    <summary><b>Certificate stores hosted on Windows servers:</b></summary>
-    1. When orchestrating management of external (and potentially local) certificate stores, the RemoteFile Orchestrator Extension makes use of WinRM to connect to external certificate store servers.  The security context used is the user id entered in the Keyfactor Command certificate store or discovery job screen.  Make sure that WinRM is set up on the orchestrated server and that the WinRM port (by convention, 5585 for HTTP and 5586 for HTTPS) is part of the certificate store path when setting up your certificate stores/discovery jobs.  If running as an agent, managing local certificate stores, local commands are run under the security context of the user account running the Keyfactor Universal Orchestrator Service.  Please reference [Certificate Stores and Discovery Jobs](#certificate-stores-and-discovery-jobs) for more information on creating certificate stores for the RemoteFile Orchestrator Extension.  
+    * **Create RFPEM using kfutil**:
 
+        ```shell
+        # RFPEM
+        kfutil store-types create RFPEM
+        ```
+
+    * **Create RFPEM manually in the Command UI**:
+        
+        Refer to the [RFPEM](docs/rfpem.md#certificate-store-type-configuration) creation docs.
     </details>
 
-    Please consult with your company's system administrator for more information on configuring SSH/SFTP/SCP or WinRM in your environment.
+    <details><summary>RFPkcs12</summary>
+
+
+    > More information on the RFPkcs12 Certificate Store Type can be found [here](docs/rfpkcs12.md).
+
+    * **Create RFPkcs12 using kfutil**:
+
+        ```shell
+        # RFPkcs12
+        kfutil store-types create RFPkcs12
+        ```
 
+    * **Create RFPkcs12 manually in the Command UI**:
+        
+        Refer to the [RFPkcs12](docs/rfpkcs12.md#certificate-store-type-configuration) creation docs.
     </details>
 
-2. Create Certificate Store Types for the Remote File Orchestrator extension. 
+    <details><summary>RFDER</summary>
+
+
+    > More information on the RFDER Certificate Store Type can be found [here](docs/rfder.md).
 
-    * **Using kfutil**:
+    * **Create RFDER using kfutil**:
 
         ```shell
-        # RFJKS
-        kfutil store-types create RFJKS
+        # RFDER
+        kfutil store-types create RFDER
         ```
 
-    * **Manually**:
-        * [RFJKS](docs/rfjks.md#certificate-store-type-configuration)
+    * **Create RFDER manually in the Command UI**:
+        
+        Refer to the [RFDER](docs/rfder.md#certificate-store-type-configuration) creation docs.
+    </details>
 
-3. Install the Remote File Universal Orchestrator extension.
-
-    * **Using kfutil**: On the server that that hosts the Universal Orchestrator, run the following command:
+    <details><summary>RFKDB</summary>
+
+
+    > More information on the RFKDB Certificate Store Type can be found [here](docs/rfkdb.md).
+
+    * **Create RFKDB using kfutil**:
 
         ```shell
-        # Windows Server
-        kfutil orchestrator extension -e remote-file-orchestrator@latest --out "C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions"
+        # RFKDB
+        kfutil store-types create RFKDB
+        ```
 
-        # Linux
-        kfutil orchestrator extension -e remote-file-orchestrator@latest --out "/opt/keyfactor/orchestrator/extensions"
+    * **Create RFKDB manually in the Command UI**:
+        
+        Refer to the [RFKDB](docs/rfkdb.md#certificate-store-type-configuration) creation docs.
+    </details>
+
+    <details><summary>RFORA</summary>
+
+
+    > More information on the RFORA Certificate Store Type can be found [here](docs/rfora.md).
+
+    * **Create RFORA using kfutil**:
+
+        ```shell
+        # RFORA
+        kfutil store-types create RFORA
         ```
 
-    * **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Remote File Universal Orchestrator extension](https://github.com/Keyfactor/remote-file-orchestrator/releases/latest).
+    * **Create RFORA manually in the Command UI**:
+        
+        Refer to the [RFORA](docs/rfora.md#certificate-store-type-configuration) creation docs.
+    </details>
 
-4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension.
+2. **Download the latest Remote File Universal Orchestrator extension from GitHub.** 
 
-    * [RFJKS](docs/rfjks.md#certificate-store-configuration)
+    On the [Remote File Universal Orchestrator extension GitHub version page](https://github.com/Keyfactor/remote-file-orchestrator/releases/latest), click the `remote-file-orchestrator` asset to download the zip archive. Unzip the archive containing extension assemblies to a known location.
 
+3. **Locate the Universal Orchestrator extensions directory.**
 
-</details>
+    * **Default on Windows** - `C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions`
+    * **Default on Linux** - `/opt/keyfactor/orchestrator/extensions`
+
+4. **Create a new directory for the Remote File Universal Orchestrator extension inside the extensions directory.**
+
+    Create a new directory called `remote-file-orchestrator`.
+    > The directory name does not need to match any names used elsewhere; it just has to be unique within the extensions directory.
 
-<details><summary>RFPEM</summary>
+5. **Copy the contents of the downloaded and unzipped assemblies from __step 2__ to the `remote-file-orchestrator` directory.**
 
-TODO Installation is an optional section - if you don't need it, feel free to remove it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
+6. **Restart the Universal Orchestrator service.**
 
+    Refer to [Starting/Restarting the Universal Orchestrator service](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/StarttheService.htm).
 
-</details>
 
-<details><summary>RFPkcs12</summary>
 
-TODO Installation is an optional section - if you don't need it, feel free to remove it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
+> The above installation steps can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions).
 
+## Configuration and Usage
 
-</details>
+The Remote File Universal Orchestrator extension implements 6 Certificate Store Types, each of which implements different functionality. Refer to the individual instructions below for each Certificate Store Type that you deemed necessary for your use case from the installation section.
 
-<details><summary>RFDER</summary>
+<details><summary>RFJKS</summary>
 
-TODO Installation is an optional section - if you don't need it, feel free to remove it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
+1. Refer to the [requirements section](docs/rfjks.md#requirements) to ensure all prerequisites are met before using the RFJKS Certificate Store Type.
+2. Create new [RFJKS](docs/rfjks.md#certificate-store-configuration) Certificate Stores in Keyfactor Command.
+</details>
 
+<details><summary>RFPEM</summary>
 
+1. Refer to the [requirements section](docs/rfpem.md#requirements) to ensure all prerequisites are met before using the RFPEM Certificate Store Type.
+2. Create new [RFPEM](docs/rfpem.md#certificate-store-configuration) Certificate Stores in Keyfactor Command.
 </details>
 
-<details><summary>RFKDB</summary>
+<details><summary>RFPkcs12</summary>
 
-TODO Installation is an optional section - if you don't need it, feel free to remove it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
+1. Refer to the [requirements section](docs/rfpkcs12.md#requirements) to ensure all prerequisites are met before using the RFPkcs12 Certificate Store Type.
+2. Create new [RFPkcs12](docs/rfpkcs12.md#certificate-store-configuration) Certificate Stores in Keyfactor Command.
+</details>
 
+<details><summary>RFDER</summary>
 
+1. Refer to the [requirements section](docs/rfder.md#requirements) to ensure all prerequisites are met before using the RFDER Certificate Store Type.
+2. Create new [RFDER](docs/rfder.md#certificate-store-configuration) Certificate Stores in Keyfactor Command.
 </details>
 
-<details><summary>RFORA</summary>
+<details><summary>RFKDB</summary>
 
-TODO Installation is an optional section - if you don't need it, feel free to remove it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
+1. Refer to the [requirements section](docs/rfkdb.md#requirements) to ensure all prerequisites are met before using the RFKDB Certificate Store Type.
+2. Create new [RFKDB](docs/rfkdb.md#certificate-store-configuration) Certificate Stores in Keyfactor Command.
+</details>
 
+<details><summary>RFORA</summary>
 
+1. Refer to the [requirements section](docs/rfora.md#requirements) to ensure all prerequisites are met before using the RFORA Certificate Store Type.
+2. Create new [RFORA](docs/rfora.md#certificate-store-configuration) Certificate Stores in Keyfactor Command.
 </details>