From 44d51d5e7078eba832ec1addf0af60448c4999b3 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Fri, 20 Dec 2024 19:30:46 +0000 Subject: [PATCH 01/16] ab#66563 --- ...low.yml => keyfactor-starter-workflow.yml} | 5 +- F5WafOrchestrator.sln | 16 +- F5WafOrchestrator/CA/Discovery.cs | 4 + F5WafOrchestrator/CA/Inventory.cs | 4 + F5WafOrchestrator/CA/Management.cs | 2 + F5WafOrchestrator/F5WafClient.cs | 7 +- F5WafOrchestrator/F5WafOrchestrator.csproj | 32 +--- F5WafOrchestrator/TLS/Discovery.cs | 4 + F5WafOrchestrator/TLS/Inventory.cs | 4 + F5WafOrchestrator/TLS/Management.cs | 2 + docsource/content.md | 19 ++ docsource/f5wafTls.md | 1 + integration-manifest.json | 50 ++--- readme-src/readme-pam-support.md | 5 - readme_source.md | 173 ------------------ 15 files changed, 87 insertions(+), 241 deletions(-) rename .github/workflows/{keyfactor-bootstrap-workflow.yml => keyfactor-starter-workflow.yml} (73%) create mode 100644 docsource/content.md create mode 100644 docsource/f5wafTls.md delete mode 100644 readme-src/readme-pam-support.md delete mode 100644 readme_source.md diff --git a/.github/workflows/keyfactor-bootstrap-workflow.yml b/.github/workflows/keyfactor-starter-workflow.yml similarity index 73% rename from .github/workflows/keyfactor-bootstrap-workflow.yml rename to .github/workflows/keyfactor-starter-workflow.yml index 6d8de53..61ea7a0 100644 --- a/.github/workflows/keyfactor-bootstrap-workflow.yml +++ b/.github/workflows/keyfactor-starter-workflow.yml @@ -1,4 +1,4 @@ -name: Keyfactor Bootstrap Workflow +name: Keyfactor Bootstrap Workflow on: workflow_dispatch: @@ -11,9 +11,10 @@ on: jobs: call-starter-workflow: - uses: keyfactor/actions/.github/workflows/starter.yml@v2 + uses: keyfactor/actions/.github/workflows/starter.yml@3.1.2 secrets: token: ${{ secrets.V2BUILDTOKEN}} APPROVE_README_PUSH: ${{ secrets.APPROVE_README_PUSH}} gpg_key: ${{ secrets.KF_GPG_PRIVATE_KEY }} gpg_pass: ${{ secrets.KF_GPG_PASSPHRASE }} + scan_token: ${{ secrets.SAST_TOKEN }} diff --git a/F5WafOrchestrator.sln b/F5WafOrchestrator.sln index 6d9f3f1..d5e7da0 100644 --- a/F5WafOrchestrator.sln +++ b/F5WafOrchestrator.sln @@ -1,8 +1,9 @@  Microsoft Visual Studio Solution File, Format Version 12.00 -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "F5WafOrchestrator", "F5WafOrchestrator\F5WafOrchestrator.csproj", "{3645725A-2C84-4536-9A04-4F4CEDF30B21}" -EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "F5WafOrchestrator.Tests", "F5WafOrchestrator.Tests\F5WafOrchestrator.Tests.csproj", "{E53E4095-667E-4F26-B596-28DC0E5CEEED}" +# Visual Studio Version 17 +VisualStudioVersion = 17.11.35312.102 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "F5WafOrchestrator", "F5WafOrchestrator\F5WafOrchestrator.csproj", "{3645725A-2C84-4536-9A04-4F4CEDF30B21}" EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution @@ -12,12 +13,11 @@ Global GlobalSection(ProjectConfigurationPlatforms) = postSolution {3645725A-2C84-4536-9A04-4F4CEDF30B21}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {3645725A-2C84-4536-9A04-4F4CEDF30B21}.Debug|Any CPU.Build.0 = Debug|Any CPU + {3645725A-2C84-4536-9A04-4F4CEDF30B21}.Debug|Any CPU.Deploy.0 = Debug|Any CPU {3645725A-2C84-4536-9A04-4F4CEDF30B21}.Release|Any CPU.ActiveCfg = Release|Any CPU {3645725A-2C84-4536-9A04-4F4CEDF30B21}.Release|Any CPU.Build.0 = Release|Any CPU - {3645725A-2C84-4536-9A04-4F4CEDF30B21}.Debug|Any CPU.Deploy.0 = Debug|Any CPU - {E53E4095-667E-4F26-B596-28DC0E5CEEED}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {E53E4095-667E-4F26-B596-28DC0E5CEEED}.Debug|Any CPU.Build.0 = Debug|Any CPU - {E53E4095-667E-4F26-B596-28DC0E5CEEED}.Release|Any CPU.ActiveCfg = Release|Any CPU - {E53E4095-667E-4F26-B596-28DC0E5CEEED}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE EndGlobalSection EndGlobal diff --git a/F5WafOrchestrator/CA/Discovery.cs b/F5WafOrchestrator/CA/Discovery.cs index 1f52c0b..9a04d51 100644 --- a/F5WafOrchestrator/CA/Discovery.cs +++ b/F5WafOrchestrator/CA/Discovery.cs @@ -18,6 +18,10 @@ using Keyfactor.Orchestrators.Extensions; using Microsoft.Extensions.Logging; +using System; +using System.Collections.Generic; +using System.Linq; + namespace Keyfactor.Extensions.Orchestrator.F5WafOrchestrator.CA; public class Discovery : Job, IDiscoveryJobExtension diff --git a/F5WafOrchestrator/CA/Inventory.cs b/F5WafOrchestrator/CA/Inventory.cs index 7a4a388..780c086 100644 --- a/F5WafOrchestrator/CA/Inventory.cs +++ b/F5WafOrchestrator/CA/Inventory.cs @@ -18,6 +18,10 @@ using Keyfactor.Orchestrators.Extensions; using Microsoft.Extensions.Logging; +using System; +using System.Collections.Generic; +using System.Linq; + namespace Keyfactor.Extensions.Orchestrator.F5WafOrchestrator.CA; public class Inventory : Job, IInventoryJobExtension diff --git a/F5WafOrchestrator/CA/Management.cs b/F5WafOrchestrator/CA/Management.cs index 43db82b..c16609d 100644 --- a/F5WafOrchestrator/CA/Management.cs +++ b/F5WafOrchestrator/CA/Management.cs @@ -18,6 +18,8 @@ using Keyfactor.Orchestrators.Extensions; using Microsoft.Extensions.Logging; +using System; + namespace Keyfactor.Extensions.Orchestrator.F5WafOrchestrator.CA; public class Management : Job, IManagementJobExtension diff --git a/F5WafOrchestrator/F5WafClient.cs b/F5WafOrchestrator/F5WafClient.cs index f017abe..a10de07 100644 --- a/F5WafOrchestrator/F5WafClient.cs +++ b/F5WafOrchestrator/F5WafClient.cs @@ -12,6 +12,10 @@ // See the License for the specific language governing permissions and // limitations under the License. +using System; +using System.IO; +using System.Linq; +using System.Collections.Generic; using System.Net.Http.Headers; using System.Text; using System.Text.Json; @@ -24,8 +28,7 @@ using Newtonsoft.Json.Linq; using Org.BouncyCastle.Pkcs; using System.Net; -using Org.BouncyCastle.Asn1.Ocsp; -using System.Xml.Linq; +using System.Net.Http; namespace Keyfactor.Extensions.Orchestrator.F5WafOrchestrator.Client; diff --git a/F5WafOrchestrator/F5WafOrchestrator.csproj b/F5WafOrchestrator/F5WafOrchestrator.csproj index e2ce2df..84d1728 100644 --- a/F5WafOrchestrator/F5WafOrchestrator.csproj +++ b/F5WafOrchestrator/F5WafOrchestrator.csproj @@ -1,13 +1,10 @@ - false - net6.0 - true - enable - enable - Keyfactor.Extensions.Orchestrator.F5WafOrchestrator - latest + true + net6.0;net8.0 + true + disable @@ -19,31 +16,10 @@ - - Always - - - ..\..\..\..\..\..\Program Files\Keyfactor\Keyfactor Orchestrator\BouncyCastle.Crypto.dll - - - - - - - $(BaseOutputPath) - false - false - - - - - - - diff --git a/F5WafOrchestrator/TLS/Discovery.cs b/F5WafOrchestrator/TLS/Discovery.cs index f0306cf..0f006ee 100644 --- a/F5WafOrchestrator/TLS/Discovery.cs +++ b/F5WafOrchestrator/TLS/Discovery.cs @@ -18,6 +18,10 @@ using Keyfactor.Orchestrators.Extensions; using Microsoft.Extensions.Logging; +using System; +using System.Collections.Generic; +using System.Linq; + namespace Keyfactor.Extensions.Orchestrator.F5WafOrchestrator.TLS; public class Discovery : Job, IDiscoveryJobExtension diff --git a/F5WafOrchestrator/TLS/Inventory.cs b/F5WafOrchestrator/TLS/Inventory.cs index d75c47c..8cbe16a 100644 --- a/F5WafOrchestrator/TLS/Inventory.cs +++ b/F5WafOrchestrator/TLS/Inventory.cs @@ -17,6 +17,10 @@ using Keyfactor.Orchestrators.Common.Enums; using Keyfactor.Orchestrators.Extensions; using Microsoft.Extensions.Logging; + +using System; +using System.Collections.Generic; +using System.Linq; using System.Text.RegularExpressions; namespace Keyfactor.Extensions.Orchestrator.F5WafOrchestrator.TLS; diff --git a/F5WafOrchestrator/TLS/Management.cs b/F5WafOrchestrator/TLS/Management.cs index 076df2b..1220dc4 100644 --- a/F5WafOrchestrator/TLS/Management.cs +++ b/F5WafOrchestrator/TLS/Management.cs @@ -18,6 +18,8 @@ using Keyfactor.Orchestrators.Extensions; using Microsoft.Extensions.Logging; +using System; + namespace Keyfactor.Extensions.Orchestrator.F5WafOrchestrator.TLS; public class Management : Job, IManagementJobExtension diff --git a/docsource/content.md b/docsource/content.md new file mode 100644 index 0000000..d4342a4 --- /dev/null +++ b/docsource/content.md @@ -0,0 +1,19 @@ +## Overview + +The Fortigate Orchestrator Extension supports the following use cases: +1. Inventory of local user and factory cerificates +2. Ability to add new local certificates +3. Ability to renew **unbound** local user certificates +4. Ability to delete **unbound** local user certificates + +The Fortigate Orchestrator Extension DOES NOT support the following use cases: +1. The renewal or removal of certificates enrolled through the internal Fortigate CA +2. The renewal or removal of factory certificates +3. The renewal or removal of ANY certificate bound to a Fortigate object +4. Certificate enrollment using the internal Fortigate CA (Keyfactor's "reenrollment" or "on device key generation" use case) + + +## Requirements + +The Fortigate Orchestrator Extension requires an API token be created in the Fortigate environment being managed. Please review the following [instructions](https://docs.fortinet.com/document/forticonverter/7.0.1/online-help/866905/connect-fortigate-device-via-api-token) for creating an API token to be used in this integration. + diff --git a/docsource/f5wafTls.md b/docsource/f5wafTls.md new file mode 100644 index 0000000..ed37e8e --- /dev/null +++ b/docsource/f5wafTls.md @@ -0,0 +1 @@ +## Overview diff --git a/integration-manifest.json b/integration-manifest.json index 7cd4ebc..363a0b2 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -6,6 +6,7 @@ "link_github": true, "update_catalog": true, "release_dir": "F5WafOrchestrator/bin/Release", + "release_project": "F5WafOrchestrator/F5WafOrchestrator.csproj", "support_level": "kf-supported", "description": "The F5 WAF Orchestrator is an extension to the Keyfactor Universal Orchestrator. It Integrates with Multi-Cloud App Connect, which is F5 Distributed Cloud's service for connecting apps across clouds and within on premise installationss using load balancers. The purpose of the F5 WAF orchestrator is to manage the TLS and CA Root certificates. The TLS certificates may be bound to load balancers. The orchestrator facilitates the inventory, addition, renewal, and removal of these certificates as well as the discovery of namespaces (certificate stores) within the F5 Multi-Cloud App Connect instance.", "about": { @@ -13,26 +14,8 @@ "UOFramework": "10.4.1", "pam_support": true, "keyfactor_platform_version": "9.10", - "win": { - "supportsCreateStore": false, - "supportsDiscovery": true, - "supportsManagementAdd": true, - "supportsManagementRemove": true, - "supportsReenrollment": false, - "supportsInventory": true, - "platformSupport": "Unused" - }, - "linux": { - "supportsCreateStore": false, - "supportsDiscovery": true, - "supportsManagementAdd": true, - "supportsManagementRemove": true, - "supportsReenrollment": false, - "supportsInventory": true, - "platformSupport": "Unused" - }, - "store_types": { - "f5WafTls": { + "store_types": [ + { "Name": "F5 WAF TLS", "ShortName": "f5WafTls", "Capability": "f5WafTls", @@ -57,7 +40,7 @@ "BlueprintAllowed": true, "CustomAliasAllowed": "Required" }, - "f5WafCa": { + { "Name": "F5 WAF CA", "ShortName": "f5WafCa", "Capability": "f5WafCa", @@ -68,7 +51,28 @@ "Enrollment": false, "Remove": true }, - "Properties": [], + "Properties": [ + { + "Name": "ServerUsername", + "DisplayName": "Server Username", + "Type": "Secret", + "DependsOn": "", + "DefaultValue": "", + "Required": false, + "IsPAMEligible": true, + "Description": "A username (or valid PAM key if the username is stored in a KF Command configured PAM integration). If acting as an *agent* using local file access, just check *No Value*" + }, + { + "Name": "ServerPassword", + "DisplayName": "Server Password", + "Type": "Secret", + "DependsOn": "", + "DefaultValue": "", + "Required": false, + "IsPAMEligible": true, + "Description": "A password (or valid PAM key if the password is stored in a KF Command configured PAM integration). The password can also be an SSH private key if connecting via SSH to a server using SSH private key authentication. If acting as an *agent* using local file access, just check *No Value*" + } + ], "EntryParameters": [], "PasswordOptions": { "EntrySupported": false, @@ -82,7 +86,7 @@ "BlueprintAllowed": true, "CustomAliasAllowed": "Required" } - } + ] } } } diff --git a/readme-src/readme-pam-support.md b/readme-src/readme-pam-support.md deleted file mode 100644 index afa937b..0000000 --- a/readme-src/readme-pam-support.md +++ /dev/null @@ -1,5 +0,0 @@ -|Name|Description| -|----|-----------| -|ServerUsername|The user id that will be used to authenticate to the F5 WAF API endpoints| -|ServerPassword|The API token that will be used to authenticate to the F5 WAF API endpoints| - diff --git a/readme_source.md b/readme_source.md deleted file mode 100644 index bacb491..0000000 --- a/readme_source.md +++ /dev/null @@ -1,173 +0,0 @@ -## Overview -The F5 WAF Orchestrator extension remotely manages TLS and CA Root certificates uploaded to F5 Distributed Multi-Cloud App Connect, which is the F5 platform that manages WAF services. Certificates bound to Http Load Balancers within Multi-Cloud App Connect can be renewed/replaced, but they cannot be removed. Certificate store types f5WafTls and f5WafCa are used to manage stores containing TLS and CA Root certificates, respectively. - -
-f5WafTls - -The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. - -Use cases supported: -1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. -2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. -3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. -4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. - -
- -
-f5WafCa - -The f5WafCa certificate store type is used to manage F5 Distributed Multi-Cloud App Connect CA Root certificates. - -Use cases supported: -1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. -2. Inventory of a TLS store. All CA Root certificates within a namespace will be returned to Keyfactor Command. -3. Management-Add. Add a new certificate or renew an existing one. -4. Management-Delete. Remove an existing certificate. Please note, for CA Root certicates, deleting an existing certificate will replace ALL instances of the same certificate and not only the one represented by the intended alias. This is an F5 WAF feature that the integration has no control over. - -
- - -## F5 WAF Orchestrator Extension Installation - -1. Refer to the [Creating Certificate Store Types](#creating-certificate-store-types) section to create the certificate store types you wish to manage. -2. Stop the Keyfactor Universal Orchestrator Service on the server 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 for a Windows install or /opt/keyfactor/orchestrator/ for a Linux install), find the "Extensions" folder. Underneath that, create a new folder named "F5Waf". You may choose to use a different name if you wish. -4. Download the latest version of the F5 WAF orchestrator extension from [GitHub](https://github.com/Keyfactor/f5-waf-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 one or more certificate store types with short names different than the suggested values, 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 respective certificate store type. -7. Start the Keyfactor Universal Orchestrator Service. - - -## Creating Certificate Store Types - -Below are the two certificate store types that the F5 WAF Orchestator Extension manages. To create a new Certificate Store Type in Keyfactor Command, first click on settings (the gear icon on the top right) => Certificate Store Types => Add. Next, follow the instructions under each store type you wish to set up. - -
-f5WafTls - TLS certificates in a namespace - -- Basic Tab: - - - **Name** – Required. The display name you wish to use for the new Certificate Store Type. - - **Short Name** – Required. Suggested value - **f5WafTls**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [F5 WAF Orchestrator Extension Installation](#f5-waf-orchestrator-extension-installation), step 6 above. - - **Custom Capability** - Unchecked - - **Supported Job Types** - Inventory, Add, Remove, and Discovery should all 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 PowerShell** - Unchecked - - **Requires Store Password** - Unchecked - - **Supports Entry Password** - Unchecked - -- Advanced Tab: - - - **Store Path Type** - Freeform - - **Supports Custom Alias** - Required. - - **Private Key Handling** - Required. - - **PFX Password Style** - Default - -- Custom Fields Tab: - - - no additional custom fields - -- Entry Parameters Tab: - - - no additional entry parameters - -
- -
-f5WafCa - CA Root certificates in a namespace - -- Basic Tab: - - - **Name** – Required. The display name you wish to use for the new Certificate Store Type. - - **Short Name** – Required. Suggested value - **f5WafCa**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [F5 WAF Orchestrator Extension Installation](#f5-waf-orchestrator-extension-installation), step 6 above. - - **Custom Capability** - Unchecked - - **Supported Job Types** - Inventory, Add, Remove, and Discovery should all 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 PowerShell** - Unchecked - - **Requires Store Password** - Unchecked - - **Supports Entry Password** - Unchecked - -- Advanced Tab: - - - **Store Path Type** - Freeform - - **Supports Custom Alias** - Required. - - **Private Key Handling** - Forbidden. - - **PFX Password Style** - Default - -- Custom Fields Tab: - - - no additional custom fields - -- Entry Parameters Tab: - - - no additional entry parameters - -
- - -## Creating Certificate Stores and Scheduling Discovery Jobs - -When creating new certificate stores or scheduling discovery jobs in Keyfactor Command, there are a few fields that are important to highlight here: - -
-Certificate Stores - -The following table describes the required and optional fields for the `f5WafTls` and `f5WafCa` certificate store types when creating a certificate store. - -In Keyfactor Command, navigate to Certificate Stores from the Locations Menu. Click the Add button to create a new Certificate Store. - -| Attribute | Description | -| --------- |------------------------------------------------------------------------------------------------------------------------------------------------| -| Category | Select either f5WafTls or f5WafCa depending on whether you want to manage TLS certificates or Root CA certificates. | -| Container | Optional container to associate certificate store with. | -| Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'). | -| Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | -| Orchestrator | Select an approved orchestrator capable of managing F5 WAF certificates. Specifically, one with the f5WafTls and f5WafCa capabilities. | -| Server Username | The username used to log in to the F5 Distributed Cloud instance (typically an email). | -| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#creating-an-f5-waf-api-token) for more details on creating this token. | -| Use SSL | Not used for this integration, so either setting is fine. | - -
- -
-Discovery Jobs - -The following table describes the required and optional fields to schedule a Discovery job for the `f5WafTls` and `f5WafCa` certificate store types. - -In Keyfactor Command, navigate to Certificate Stores from the Locations Menu and then click on the Discover tab. - -| Attribute | Description | -| --------- |------------------------------------------------------------------------------------------------------------------------------------------------| -| Category | Select either F5WafTls or F5WafCa depending on whether you want to return namespaces for TLS certificates or CA Root certificates. | -| Orchestrator | Select an approved orchestrator capable of managing F5 WAF certificates. Specifically, one with the f5WafTls and f5WafCa capabilities. | -| Schedule | Enter the schedule for when you want the job to run | -| Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'. | -| Server Username | The username used to log in to the F5 Distributed Cloud instance (typically an email). | -| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#creating-an-f5-waf-api-token) for more details on creating this token. | -| Directories to Search | Not used for this integration. Leave Blank. | -| Directories to ignore | Not used for this integration. Leave Blank. | -| Extensions | Not used for this integration. Leave Blank. | -| File name patterns to match | Not used for this integration. Leave Blank. | -| Follow SymLinks | Not used for this integration. Leave Unchecked. | -| Follow SymLinks | Not used for this integration. Leave Unchecked. | -| Use SSL? | Not used for this integration. Leave Unchecked. | - -Discovery jobs will return all known namespaces for this F5 WAF instance. Please note that because Keyfactor Command has a restriction on multiple certificate stores having the same Client Machine and Store Path, certificate stores for f5WafTls will return stores with a "tls-" prefixed to the beginning of the store path (namespace); while f5WafCA stores will have "ca-" prefixed. Any jobs that run for stores with these prefixes will have these prefixes removed before calling any F5 WAF APIs. What this means is a store path (namespace) for an f5WafTls store of "tls-namespace1" will be the same as one labeled "namespace1". - -
- - -## Creating an F5 WAF API Token - -In lieu of providing a server password when setting up an F5 WAF certificate store, F5 Multi-Cloud App Connect uses API tokens combined with the user id to authenticate when calling APIs. API Tokens can be created through the F5 Distributed Cloud Console after logging in with the ID you wish to use for the Keyfactor certificate store. Once logged in, select Multi-Cloud App Connect from the options under "Common services". Next, select Account Services from the pull down at the top right of the screen, and select "Account Settings". From there, click on "Credentials" on the left nav and "Add Credentials" on the subsequent screen. In the form shown, select "API Token" from the Credential Type dropdown, and enter the name of the credential and the expiration date. Please note that credentials can only be created for up to 90 day periods of time. After 90 days, a new API token will need to be generated and replaced in your F5 WAF certificate store(s). Clicking Generate will then show the value of the newly created API Token. Copy this and save to a safe place, as this will be the value you will enter in the Server Password field when setting up your certificate store. If you forget or lose this token value, there is no way to access it again in the F5 Distributed Cloud portal. You will need to create a new API Token. - -![](Images/image1.gif) -![](Images/image2.gif) -![](Images/image3.gif) -![](Images/image4.gif) -![](Images/image5.gif) -![](Images/image6.gif) - From 609166aa9cd164f1373cb8070a87e061d0684406 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 20 Dec 2024 19:31:40 +0000 Subject: [PATCH 02/16] Update generated docs --- README.md | 424 +++++++++++++++++++++++++----------------- docsource/f5wafca.md | 20 ++ docsource/f5waftls.md | 20 ++ 3 files changed, 290 insertions(+), 174 deletions(-) create mode 100644 docsource/f5wafca.md create mode 100644 docsource/f5waftls.md diff --git a/README.md b/README.md index e737332..b8d3609 100644 --- a/README.md +++ b/README.md @@ -1,277 +1,353 @@ +

+ F5 WAF Universal Orchestrator Extension +

+ +

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

+ +

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

+ +## Overview + +The Fortigate Orchestrator Extension supports the following use cases: +1. Inventory of local user and factory cerificates +2. Ability to add new local certificates +3. Ability to renew **unbound** local user certificates +4. Ability to delete **unbound** local user certificates -# F5 WAF +The Fortigate Orchestrator Extension DOES NOT support the following use cases: +1. The renewal or removal of certificates enrolled through the internal Fortigate CA +2. The renewal or removal of factory certificates +3. The renewal or removal of ANY certificate bound to a Fortigate object +4. Certificate enrollment using the internal Fortigate CA (Keyfactor's "reenrollment" or "on device key generation" use case) -The F5 WAF Orchestrator is an extension to the Keyfactor Universal Orchestrator. It Integrates with Multi-Cloud App Connect, which is F5 Distributed Cloud's service for connecting apps across clouds and within on premise installationss using load balancers. The purpose of the F5 WAF orchestrator is to manage the TLS and CA Root certificates. The TLS certificates may be bound to load balancers. The orchestrator facilitates the inventory, addition, renewal, and removal of these certificates as well as the discovery of namespaces (certificate stores) within the F5 Multi-Cloud App Connect instance. +The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types. Depending on your use case, you may elect to use one, or both of these Certificate Store Types. Descriptions of each are provided below. -#### Integration status: Production - Ready for use in production environments. +
F5 WAF TLS (f5WafTls) -## 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. +### f5WafTls +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -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. +TODO Overview is a required section +
-## Support for F5 WAF +
F5 WAF CA (f5WafCa) -F5 WAF is supported by Keyfactor for Keyfactor customers. 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. +### f5WafCa +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info ---- +TODO Overview is a required section +
---- +## Compatibility +This integration is compatible with Keyfactor Universal Orchestrator version 10.4.1 and later. -## Keyfactor Version Supported +## Support +The F5 WAF 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. -The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.4.1 -## Platform Specific Notes +## Requirements & Prerequisites -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 Reenrollment| | | -|Supports Inventory|✓ |✓ | +Before installing the F5 WAF 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. -## PAM Integration +The Fortigate Orchestrator Extension requires an API token be created in the Fortigate environment being managed. Please review the following [instructions](https://docs.fortinet.com/document/forticonverter/7.0.1/online-help/866905/connect-fortigate-device-via-api-token) for creating an API token to be used in this 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. +
F5 WAF TLS (f5WafTls) -The secrets that this orchestrator extension supports for use with a PAM Provider are: +### F5 WAF TLS Requirements +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -|Name|Description| -|----|-----------| -|ServerUsername|The user id that will be used to authenticate to the F5 WAF API endpoints| -|ServerPassword|The API token that will be used to authenticate to the F5 WAF 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. +TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +
-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. -
General PAM Provider Configuration -

+

F5 WAF CA (f5WafCa) +### F5 WAF CA Requirements +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -### 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. +TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +
-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: +## Create Certificate Store Types -~~~ json -{"Secret":"my-kv-secret","Key":"myServerPassword"} -~~~ +To use the F5 WAF Universal Orchestrator extension, you **must** create the Certificate Store Types required for your usecase. This only needs to happen _once_ per Keyfactor Command instance. -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. -

-
+The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types. Depending on your use case, you may elect to use one, or both of these Certificate Store Types. +
F5 WAF TLS (f5WafTls) +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info ---- +* **Create f5WafTls using kfutil**: + ```shell + # F5 WAF TLS + kfutil store-types create f5WafTls + ``` -## Overview -The F5 WAF Orchestrator extension remotely manages TLS and CA Root certificates uploaded to F5 Distributed Multi-Cloud App Connect, which is the F5 platform that manages WAF services. Certificates bound to Http Load Balancers within Multi-Cloud App Connect can be renewed/replaced, but they cannot be removed. Certificate store types f5WafTls and f5WafCa are used to manage stores containing TLS and CA Root certificates, respectively. +* **Create f5WafTls manually in the Command UI**: +
Create f5WafTls manually in the Command UI -
-f5WafTls + Create a store type called `f5WafTls` with the attributes in the tables below: -The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. + #### Basic Tab + | Attribute | Value | Description | + | --------- | ----- | ----- | + | Name | F5 WAF TLS | Display name for the store type (may be customized) | + | Short Name | f5WafTls | Short display name for the store type | + | Capability | f5WafTls | Store type name orchestrator will register with. Check the box to allow entry of value | + | Supports Add | ✅ Checked | Check the box. Indicates that the Store Type supports Management Add | + | Supports Remove | ✅ Checked | Check the box. Indicates that the Store Type supports Management Remove | + | Supports Discovery | ✅ Checked | Check the box. Indicates that the Store Type supports Discovery | + | Supports Reenrollment | 🔲 Unchecked | Indicates that the Store Type supports Reenrollment | + | Supports Create | 🔲 Unchecked | Indicates that the Store Type supports store creation | + | Needs Server | ✅ Checked | Determines if a target server name is required when creating store | + | Blueprint Allowed | ✅ Checked | Determines if store type may be included in an Orchestrator blueprint | + | Uses PowerShell | 🔲 Unchecked | Determines if underlying implementation is PowerShell | + | Requires Store Password | 🔲 Unchecked | Enables users to optionally specify a store password when defining a Certificate Store. | + | Supports Entry Password | 🔲 Unchecked | Determines if an individual entry within a store can have a password. | -Use cases supported: -1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. -2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. -3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. -4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. + The Basic tab should look like this: + ![f5WafTls Basic Tab](docsource/images/f5WafTls-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: + + ![f5WafTls Advanced Tab](docsource/images/f5WafTls-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 | Description | Type | Default Value/Options | Required | + | ---- | ------------ | ---- | --------------------- | -------- | ----------- | + + The Custom Fields tab should look like this: + + ![f5WafTls Custom Fields Tab](docsource/images/f5WafTls-custom-fields-store-type-dialog.png) + + + +
-
-f5WafCa +
F5 WAF CA (f5WafCa) + +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + -The f5WafCa certificate store type is used to manage F5 Distributed Multi-Cloud App Connect CA Root certificates. +* **Create f5WafCa using kfutil**: -Use cases supported: -1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. -2. Inventory of a TLS store. All CA Root certificates within a namespace will be returned to Keyfactor Command. -3. Management-Add. Add a new certificate or renew an existing one. -4. Management-Delete. Remove an existing certificate. Please note, for CA Root certicates, deleting an existing certificate will replace ALL instances of the same certificate and not only the one represented by the intended alias. This is an F5 WAF feature that the integration has no control over. + ```shell + # F5 WAF CA + kfutil store-types create f5WafCa + ``` +* **Create f5WafCa manually in the Command UI**: +
Create f5WafCa manually in the Command UI + + Create a store type called `f5WafCa` with the attributes in the tables below: + + #### Basic Tab + | Attribute | Value | Description | + | --------- | ----- | ----- | + | Name | F5 WAF CA | Display name for the store type (may be customized) | + | Short Name | f5WafCa | Short display name for the store type | + | Capability | f5WafCa | Store type name orchestrator will register with. Check the box to allow entry of value | + | Supports Add | ✅ Checked | Check the box. Indicates that the Store Type supports Management Add | + | Supports Remove | ✅ Checked | Check the box. Indicates that the Store Type supports Management Remove | + | Supports Discovery | ✅ Checked | Check the box. Indicates that the Store Type supports Discovery | + | Supports Reenrollment | 🔲 Unchecked | Indicates that the Store Type supports Reenrollment | + | Supports Create | 🔲 Unchecked | Indicates that the Store Type supports store creation | + | Needs Server | ✅ Checked | Determines if a target server name is required when creating store | + | Blueprint Allowed | ✅ Checked | Determines if store type may be included in an Orchestrator blueprint | + | Uses PowerShell | 🔲 Unchecked | Determines if underlying implementation is PowerShell | + | Requires Store Password | 🔲 Unchecked | Enables users to optionally specify a store password when defining a Certificate Store. | + | Supports Entry Password | 🔲 Unchecked | Determines if an individual entry within a store can have a password. | + + The Basic tab should look like this: + + ![f5WafCa Basic Tab](docsource/images/f5WafCa-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 | Forbidden | 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: + + ![f5WafCa Advanced Tab](docsource/images/f5WafCa-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 | Description | Type | Default Value/Options | Required | + | ---- | ------------ | ---- | --------------------- | -------- | ----------- | + | ServerUsername | Server Username | A username (or valid PAM key if the username is stored in a KF Command configured PAM integration). If acting as an *agent* using local file access, just check *No Value* | Secret | | 🔲 Unchecked | + | ServerPassword | Server Password | A password (or valid PAM key if the password is stored in a KF Command configured PAM integration). The password can also be an SSH private key if connecting via SSH to a server using SSH private key authentication. If acting as an *agent* using local file access, just check *No Value* | Secret | | 🔲 Unchecked | + + The Custom Fields tab should look like this: + + ![f5WafCa Custom Fields Tab](docsource/images/f5WafCa-custom-fields-store-type-dialog.png) + + + +
-## F5 WAF Orchestrator Extension Installation +## Installation + +1. **Download the latest F5 WAF Universal Orchestrator extension from GitHub.** + + Navigate to the [F5 WAF Universal Orchestrator extension GitHub version page](https://github.com/Keyfactor/f5-waf-orchestrator/releases/latest). Refer to the compatibility matrix below to determine whether the `net6.0` or `net8.0` asset should be downloaded. Then, click the corresponding asset to download the zip archive. + | Universal Orchestrator Version | Latest .NET version installed on the Universal Orchestrator server | `rollForward` condition in `Orchestrator.runtimeconfig.json` | `f5-waf-orchestrator` .NET version to download | + | --------- | ----------- | ----------- | ----------- | + | Older than `11.0.0` | | | `net6.0` | + | Between `11.0.0` and `11.5.1` (inclusive) | `net6.0` | | `net6.0` | + | Between `11.0.0` and `11.5.1` (inclusive) | `net8.0` | `Disable` | `net6.0` | + | Between `11.0.0` and `11.5.1` (inclusive) | `net8.0` | `LatestMajor` | `net8.0` | + | `11.6` _and_ newer | `net8.0` | | `net8.0` | + + Unzip the archive containing extension assemblies to a known location. + + > **Note** If you don't see an asset with a corresponding .NET version, you should always assume that it was compiled for `net6.0`. -1. Refer to the [Creating Certificate Store Types](#creating-certificate-store-types) section to create the certificate store types you wish to manage. -2. Stop the Keyfactor Universal Orchestrator Service on the server 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 for a Windows install or /opt/keyfactor/orchestrator/ for a Linux install), find the "Extensions" folder. Underneath that, create a new folder named "F5Waf". You may choose to use a different name if you wish. -4. Download the latest version of the F5 WAF orchestrator extension from [GitHub](https://github.com/Keyfactor/f5-waf-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 one or more certificate store types with short names different than the suggested values, 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 respective certificate store type. -7. Start the Keyfactor Universal Orchestrator Service. +2. **Locate the Universal Orchestrator extensions directory.** + * **Default on Windows** - `C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions` + * **Default on Linux** - `/opt/keyfactor/orchestrator/extensions` + +3. **Create a new directory for the F5 WAF Universal Orchestrator extension inside the extensions directory.** + + Create a new directory called `f5-waf-orchestrator`. + > The directory name does not need to match any names used elsewhere; it just has to be unique within the extensions directory. -## Creating Certificate Store Types +4. **Copy the contents of the downloaded and unzipped assemblies from __step 2__ to the `f5-waf-orchestrator` directory.** -Below are the two certificate store types that the F5 WAF Orchestator Extension manages. To create a new Certificate Store Type in Keyfactor Command, first click on settings (the gear icon on the top right) => Certificate Store Types => Add. Next, follow the instructions under each store type you wish to set up. +5. **Restart the Universal Orchestrator service.** -
-f5WafTls - TLS certificates in a namespace + Refer to [Starting/Restarting the Universal Orchestrator service](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/StarttheService.htm). -- Basic Tab: - - **Name** – Required. The display name you wish to use for the new Certificate Store Type. - - **Short Name** – Required. Suggested value - **f5WafTls**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [F5 WAF Orchestrator Extension Installation](#f5-waf-orchestrator-extension-installation), step 6 above. - - **Custom Capability** - Unchecked - - **Supported Job Types** - Inventory, Add, Remove, and Discovery should all 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 PowerShell** - Unchecked - - **Requires Store Password** - Unchecked - - **Supports Entry Password** - Unchecked +6. **(optional) PAM Integration** -- Advanced Tab: + The F5 WAF Universal Orchestrator extension is compatible with all supported Keyfactor PAM extensions to resolve PAM-eligible secrets. PAM extensions running on Universal Orchestrators enable secure retrieval of secrets from a connected PAM provider. - - **Store Path Type** - Freeform - - **Supports Custom Alias** - Required. - - **Private Key Handling** - Required. - - **PFX Password Style** - Default + To configure a PAM provider, [reference the Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam) to select an extension, and follow the associated instructions to install it on the Universal Orchestrator (remote). -- Custom Fields Tab: - - no additional custom fields +> 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). -- Entry Parameters Tab: - - no additional entry parameters -
+## Defining Certificate Stores -
-f5WafCa - CA Root certificates in a namespace +The F5 WAF Universal Orchestrator extension implements 2 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. -- Basic Tab: +
F5 WAF TLS (f5WafTls) - - **Name** – Required. The display name you wish to use for the new Certificate Store Type. - - **Short Name** – Required. Suggested value - **f5WafCa**. If you choose to use a different value you must make the corresponding modification to the manifest.json file. See [F5 WAF Orchestrator Extension Installation](#f5-waf-orchestrator-extension-installation), step 6 above. - - **Custom Capability** - Unchecked - - **Supported Job Types** - Inventory, Add, Remove, and Discovery should all 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 PowerShell** - Unchecked - - **Requires Store Password** - Unchecked - - **Supports Entry Password** - Unchecked +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -- Advanced Tab: +TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - - **Store Path Type** - Freeform - - **Supports Custom Alias** - Required. - - **Private Key Handling** - Forbidden. - - **PFX Password Style** - Default -- Custom Fields Tab: - - no additional custom fields +> The content in this section can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store). -- Entry Parameters Tab: - - no additional entry parameters +
+ +
F5 WAF CA (f5WafCa) + +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -
+TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -## Creating Certificate Stores and Scheduling Discovery Jobs -When creating new certificate stores or scheduling discovery jobs in Keyfactor Command, there are a few fields that are important to highlight here: +> The content in this section can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store). + + +
-
-Certificate Stores +## Discovering Certificate Stores with the Discovery Job +
F5 WAF TLS -The following table describes the required and optional fields for the `f5WafTls` and `f5WafCa` certificate store types when creating a certificate store. -In Keyfactor Command, navigate to Certificate Stores from the Locations Menu. Click the Add button to create a new Certificate Store. +### F5 WAF TLS Discovery Job +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -| Attribute | Description | -| --------- |------------------------------------------------------------------------------------------------------------------------------------------------| -| Category | Select either f5WafTls or f5WafCa depending on whether you want to manage TLS certificates or Root CA certificates. | -| Container | Optional container to associate certificate store with. | -| Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'). | -| Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | -| Orchestrator | Select an approved orchestrator capable of managing F5 WAF certificates. Specifically, one with the f5WafTls and f5WafCa capabilities. | -| Server Username | The username used to log in to the F5 Distributed Cloud instance (typically an email). | -| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#creating-an-f5-waf-api-token) for more details on creating this token. | -| Use SSL | Not used for this integration, so either setting is fine. | +TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
-
-Discovery Jobs -The following table describes the required and optional fields to schedule a Discovery job for the `f5WafTls` and `f5WafCa` certificate store types. +
F5 WAF CA -In Keyfactor Command, navigate to Certificate Stores from the Locations Menu and then click on the Discover tab. -| Attribute | Description | -| --------- |------------------------------------------------------------------------------------------------------------------------------------------------| -| Category | Select either F5WafTls or F5WafCa depending on whether you want to return namespaces for TLS certificates or CA Root certificates. | -| Orchestrator | Select an approved orchestrator capable of managing F5 WAF certificates. Specifically, one with the f5WafTls and f5WafCa capabilities. | -| Schedule | Enter the schedule for when you want the job to run | -| Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'. | -| Server Username | The username used to log in to the F5 Distributed Cloud instance (typically an email). | -| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#creating-an-f5-waf-api-token) for more details on creating this token. | -| Directories to Search | Not used for this integration. Leave Blank. | -| Directories to ignore | Not used for this integration. Leave Blank. | -| Extensions | Not used for this integration. Leave Blank. | -| File name patterns to match | Not used for this integration. Leave Blank. | -| Follow SymLinks | Not used for this integration. Leave Unchecked. | -| Follow SymLinks | Not used for this integration. Leave Unchecked. | -| Use SSL? | Not used for this integration. Leave Unchecked. | +### F5 WAF CA Discovery Job +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -Discovery jobs will return all known namespaces for this F5 WAF instance. Please note that because Keyfactor Command has a restriction on multiple certificate stores having the same Client Machine and Store Path, certificate stores for f5WafTls will return stores with a "tls-" prefixed to the beginning of the store path (namespace); while f5WafCA stores will have "ca-" prefixed. Any jobs that run for stores with these prefixes will have these prefixes removed before calling any F5 WAF APIs. What this means is a store path (namespace) for an f5WafTls store of "tls-namespace1" will be the same as one labeled "namespace1". +TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
-## Creating an F5 WAF API Token -In lieu of providing a server password when setting up an F5 WAF certificate store, F5 Multi-Cloud App Connect uses API tokens combined with the user id to authenticate when calling APIs. API Tokens can be created through the F5 Distributed Cloud Console after logging in with the ID you wish to use for the Keyfactor certificate store. Once logged in, select Multi-Cloud App Connect from the options under "Common services". Next, select Account Services from the pull down at the top right of the screen, and select "Account Settings". From there, click on "Credentials" on the left nav and "Add Credentials" on the subsequent screen. In the form shown, select "API Token" from the Credential Type dropdown, and enter the name of the credential and the expiration date. Please note that credentials can only be created for up to 90 day periods of time. After 90 days, a new API token will need to be generated and replaced in your F5 WAF certificate store(s). Clicking Generate will then show the value of the newly created API Token. Copy this and save to a safe place, as this will be the value you will enter in the Server Password field when setting up your certificate store. If you forget or lose this token value, there is no way to access it again in the F5 Distributed Cloud portal. You will need to create a new API Token. -![](Images/image1.gif) -![](Images/image2.gif) -![](Images/image3.gif) -![](Images/image4.gif) -![](Images/image5.gif) -![](Images/image6.gif) +## License -When creating cert store type manually, that store property names and entry parameter names are case sensitive +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/docsource/f5wafca.md b/docsource/f5wafca.md new file mode 100644 index 0000000..d53d056 --- /dev/null +++ b/docsource/f5wafca.md @@ -0,0 +1,20 @@ +## Overview + +TODO Overview is a required section + +## Requirements + +TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Discovery Job Configuration + +TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Certificate Store Configuration + +TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Global Store Type Section + +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + diff --git a/docsource/f5waftls.md b/docsource/f5waftls.md new file mode 100644 index 0000000..d53d056 --- /dev/null +++ b/docsource/f5waftls.md @@ -0,0 +1,20 @@ +## Overview + +TODO Overview is a required section + +## Requirements + +TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Discovery Job Configuration + +TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Certificate Store Configuration + +TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Global Store Type Section + +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + From 4ca77439be7e669803b73870730b291a314ea970 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Mon, 23 Dec 2024 19:25:36 +0000 Subject: [PATCH 03/16] ab#66563 --- docsource/content.md | 45 ++++++++++++++++++++++++++++----------- docsource/f5wafTls.md | 8 +++++++ docsource/f5wafca.md | 9 ++++++++ integration-manifest.json | 37 ++++++++++++++++++++++++++------ 4 files changed, 81 insertions(+), 18 deletions(-) create mode 100644 docsource/f5wafca.md diff --git a/docsource/content.md b/docsource/content.md index d4342a4..1f84152 100644 --- a/docsource/content.md +++ b/docsource/content.md @@ -1,19 +1,40 @@ ## Overview -The Fortigate Orchestrator Extension supports the following use cases: -1. Inventory of local user and factory cerificates -2. Ability to add new local certificates -3. Ability to renew **unbound** local user certificates -4. Ability to delete **unbound** local user certificates - -The Fortigate Orchestrator Extension DOES NOT support the following use cases: -1. The renewal or removal of certificates enrolled through the internal Fortigate CA -2. The renewal or removal of factory certificates -3. The renewal or removal of ANY certificate bound to a Fortigate object -4. Certificate enrollment using the internal Fortigate CA (Keyfactor's "reenrollment" or "on device key generation" use case) +The F5 WAF Orchestrator extension remotely manages TLS and CA Root certificates uploaded to F5 Distributed Multi-Cloud App Connect, which is the F5 platform that manages WAF services. Certificates bound to Http Load Balancers within Multi-Cloud App Connect can be renewed/replaced, but they cannot be removed. Certificate store types f5WafTls and f5WafCa are used to manage stores containing TLS and CA Root certificates, respectively. ## Requirements -The Fortigate Orchestrator Extension requires an API token be created in the Fortigate environment being managed. Please review the following [instructions](https://docs.fortinet.com/document/forticonverter/7.0.1/online-help/866905/connect-fortigate-device-via-api-token) for creating an API token to be used in this integration. +F5 Multi-Cloud App Connect uses API tokens to authenticate when calling APIs. API Tokens can be created through the F5 Distributed Cloud Console. Once logged in, select Multi-Cloud App Connect from the options under "Common services". Next, select Account Services from the pull down at the top right of the screen, and select "Account Settings". From there, click on "Credentials" on the left nav and "Add Credentials" on the subsequent screen. In the form shown, select "API Token" from the Credential Type dropdown, and enter the name of the credential and the expiration date. Please note that credentials can only be created for up to 90 day periods of time. After 90 days, a new API token will need to be generated and replaced in your F5 WAF certificate store(s). Clicking Generate will then show the value of the newly created API Token. Copy this and save to a safe place, as this will be the value you will enter in the Server Password field when setting up your certificate store. If you forget or lose this token value, there is no way to access it again in the F5 Distributed Cloud portal. You will need to create a new API Token. + +![](Images/image1.gif) +![](Images/image2.gif) +![](Images/image3.gif) +![](Images/image4.gif) +![](Images/image5.gif) +![](Images/image6.gif) + + +## Discovery + +The following table describes the required and optional fields to schedule a Discovery job for the `f5WafTls` and `f5WafCa` certificate store types. + +In Keyfactor Command, navigate to Certificate Stores from the Locations Menu and then click on the Discover tab. + +| Attribute | Description | +| --------- |------------------------------------------------------------------------------------------------------------------------------------------------| +| Category | Select either F5WafTls or F5WafCa depending on whether you want to return namespaces for TLS certificates or CA Root certificates. | +| Orchestrator | Select an approved orchestrator capable of managing F5 WAF certificates. Specifically, one with the f5WafTls and f5WafCa capabilities. | +| Schedule | Enter the schedule for when you want the job to run | +| Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'. | +| Server Username | This is not used but required in the UI. Enter any value. | +| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Requirements](#requirements) for more details on creating this token. | +| Directories to Search | Not used for this integration. Leave Blank. | +| Directories to ignore | Not used for this integration. Leave Blank. | +| Extensions | Not used for this integration. Leave Blank. | +| File name patterns to match | Not used for this integration. Leave Blank. | +| Follow SymLinks | Not used for this integration. Leave Unchecked. | +| Follow SymLinks | Not used for this integration. Leave Unchecked. | +| Use SSL? | Not used for this integration. Leave Unchecked. | +Discovery jobs will return all known namespaces for this F5 WAF instance. Please note that because Keyfactor Command has a restriction on multiple certificate stores having the same Client Machine and Store Path, certificate stores for f5WafTls will return stores with a "tls-" prefixed to the beginning of the store path (namespace); while f5WafCA stores will have "ca-" prefixed. Any jobs that run for stores with these prefixes will have these prefixes removed before calling any F5 WAF APIs. What this means is a store path (namespace) for an f5WafTls store of "tls-namespace1" will be the same as one labeled "namespace1". \ No newline at end of file diff --git a/docsource/f5wafTls.md b/docsource/f5wafTls.md index ed37e8e..1a698e5 100644 --- a/docsource/f5wafTls.md +++ b/docsource/f5wafTls.md @@ -1 +1,9 @@ ## Overview + +The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. + +Use cases supported: +1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. +2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. +3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. +4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. diff --git a/docsource/f5wafca.md b/docsource/f5wafca.md new file mode 100644 index 0000000..7a70db8 --- /dev/null +++ b/docsource/f5wafca.md @@ -0,0 +1,9 @@ +## Overview + +The f5WafCa certificate store type is used to manage F5 Distributed Multi-Cloud App Connect CA Root certificates. + +Use cases supported: +1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. +2. Inventory of a TLS store. All CA Root certificates within a namespace will be returned to Keyfactor Command. +3. Management-Add. Add a new certificate or renew an existing one. +4. Management-Delete. Remove an existing certificate. Please note, for CA Root certicates, deleting an existing certificate will replace ALL instances of the same certificate and not only the one represented by the intended alias. This is an F5 WAF feature that the integration has no control over. \ No newline at end of file diff --git a/integration-manifest.json b/integration-manifest.json index 363a0b2..907f170 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -26,7 +26,28 @@ "Enrollment": false, "Remove": true }, - "Properties": [], + "Properties": [ + { + "Name": "ServerUsername", + "DisplayName": "Server Username", + "Type": "Secret", + "DependsOn": "", + "DefaultValue": "", + "Required": false, + "IsPAMEligible": false, + "Description": "Not used, but a value is required. Enter anything into this field." + }, + { + "Name": "ServerPassword", + "DisplayName": "Server Password", + "Type": "Secret", + "DependsOn": "", + "DefaultValue": "", + "Required": false, + "IsPAMEligible": false, + "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token." + } + ], "EntryParameters": [], "PasswordOptions": { "EntrySupported": false, @@ -38,7 +59,9 @@ "ServerRequired": true, "PowerShell": false, "BlueprintAllowed": true, - "CustomAliasAllowed": "Required" + "CustomAliasAllowed": "Required", + "ClientMachineDescription": "The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io').", + "StorePathDescription": "The Multi-Cloud App Connect namespace containing the certificates you wish to manage." }, { "Name": "F5 WAF CA", @@ -59,8 +82,8 @@ "DependsOn": "", "DefaultValue": "", "Required": false, - "IsPAMEligible": true, - "Description": "A username (or valid PAM key if the username is stored in a KF Command configured PAM integration). If acting as an *agent* using local file access, just check *No Value*" + "IsPAMEligible": false, + "Description": "Not used, but a value is required. Enter anything into this field." }, { "Name": "ServerPassword", @@ -70,7 +93,7 @@ "DefaultValue": "", "Required": false, "IsPAMEligible": true, - "Description": "A password (or valid PAM key if the password is stored in a KF Command configured PAM integration). The password can also be an SSH private key if connecting via SSH to a server using SSH private key authentication. If acting as an *agent* using local file access, just check *No Value*" + "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token." } ], "EntryParameters": [], @@ -84,7 +107,9 @@ "ServerRequired": true, "PowerShell": false, "BlueprintAllowed": true, - "CustomAliasAllowed": "Required" + "CustomAliasAllowed": "Required", + "ClientMachineDescription": "The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io').", + "StorePathDescription": "The Multi-Cloud App Connect namespace containing the certificates you wish to manage." } ] } From b677535e428f672dc58be117f371e67c014247cc Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Mon, 23 Dec 2024 20:16:39 +0000 Subject: [PATCH 04/16] ab#66563 --- docsource/f5wafTls.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docsource/f5wafTls.md b/docsource/f5wafTls.md index 1a698e5..d53d056 100644 --- a/docsource/f5wafTls.md +++ b/docsource/f5wafTls.md @@ -1,9 +1,20 @@ ## Overview -The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. +TODO Overview is a required section + +## Requirements + +TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Discovery Job Configuration + +TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Certificate Store Configuration + +TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Global Store Type Section + +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -Use cases supported: -1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. -2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. -3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. -4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. From 3c4636c3a7cb43bc7511b441730e43413dbe2353 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Mon, 23 Dec 2024 20:17:36 +0000 Subject: [PATCH 05/16] Update generated docs --- README.md | 159 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 118 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index b8d3609..8554f1a 100644 --- a/README.md +++ b/README.md @@ -31,17 +31,7 @@ ## Overview -The Fortigate Orchestrator Extension supports the following use cases: -1. Inventory of local user and factory cerificates -2. Ability to add new local certificates -3. Ability to renew **unbound** local user certificates -4. Ability to delete **unbound** local user certificates - -The Fortigate Orchestrator Extension DOES NOT support the following use cases: -1. The renewal or removal of certificates enrolled through the internal Fortigate CA -2. The renewal or removal of factory certificates -3. The renewal or removal of ANY certificate bound to a Fortigate object -4. Certificate enrollment using the internal Fortigate CA (Keyfactor's "reenrollment" or "on device key generation" use case) +The F5 WAF Orchestrator extension remotely manages TLS and CA Root certificates uploaded to F5 Distributed Multi-Cloud App Connect, which is the F5 platform that manages WAF services. Certificates bound to Http Load Balancers within Multi-Cloud App Connect can be renewed/replaced, but they cannot be removed. Certificate store types f5WafTls and f5WafCa are used to manage stores containing TLS and CA Root certificates, respectively. The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types. Depending on your use case, you may elect to use one, or both of these Certificate Store Types. Descriptions of each are provided below. @@ -59,10 +49,14 @@ TODO Overview is a required section ### f5WafCa -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +The f5WafCa certificate store type is used to manage F5 Distributed Multi-Cloud App Connect CA Root certificates. -TODO Overview is a required section +Use cases supported: +1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. +2. Inventory of a TLS store. All CA Root certificates within a namespace will be returned to Keyfactor Command. +3. Management-Add. Add a new certificate or renew an existing one. +4. Management-Delete. Remove an existing certificate. Please note, for CA Root certicates, deleting an existing certificate will replace ALL instances of the same certificate and not only the one represented by the intended alias. This is an F5 WAF feature that the integration has no control over.
@@ -80,7 +74,14 @@ The F5 WAF Universal Orchestrator extension is supported by Keyfactor for Keyfac Before installing the F5 WAF 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. -The Fortigate Orchestrator Extension requires an API token be created in the Fortigate environment being managed. Please review the following [instructions](https://docs.fortinet.com/document/forticonverter/7.0.1/online-help/866905/connect-fortigate-device-via-api-token) for creating an API token to be used in this integration. +F5 Multi-Cloud App Connect uses API tokens to authenticate when calling APIs. API Tokens can be created through the F5 Distributed Cloud Console. Once logged in, select Multi-Cloud App Connect from the options under "Common services". Next, select Account Services from the pull down at the top right of the screen, and select "Account Settings". From there, click on "Credentials" on the left nav and "Add Credentials" on the subsequent screen. In the form shown, select "API Token" from the Credential Type dropdown, and enter the name of the credential and the expiration date. Please note that credentials can only be created for up to 90 day periods of time. After 90 days, a new API token will need to be generated and replaced in your F5 WAF certificate store(s). Clicking Generate will then show the value of the newly created API Token. Copy this and save to a safe place, as this will be the value you will enter in the Server Password field when setting up your certificate store. If you forget or lose this token value, there is no way to access it again in the F5 Distributed Cloud portal. You will need to create a new API Token. + +![](Images/image1.gif) +![](Images/image2.gif) +![](Images/image3.gif) +![](Images/image4.gif) +![](Images/image5.gif) +![](Images/image6.gif)
F5 WAF TLS (f5WafTls) @@ -93,17 +94,6 @@ TODO Requirements is an optional section. If this section doesn't seem necessary -
F5 WAF CA (f5WafCa) - -### F5 WAF CA Requirements -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - - -TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -
- - - ## Create Certificate Store Types @@ -166,6 +156,8 @@ TODO Global Store Type Section is an optional section. If this section doesn't s | Name | Display Name | Description | Type | Default Value/Options | Required | | ---- | ------------ | ---- | --------------------- | -------- | ----------- | + | ServerUsername | Server Username | Not used, but a value is required. Enter anything into this field. | Secret | | 🔲 Unchecked | + | ServerPassword | Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | Secret | | 🔲 Unchecked | The Custom Fields tab should look like this: @@ -178,8 +170,6 @@ TODO Global Store Type Section is an optional section. If this section doesn't s
F5 WAF CA (f5WafCa) -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - * **Create f5WafCa using kfutil**: @@ -230,8 +220,8 @@ TODO Global Store Type Section is an optional section. If this section doesn't s | Name | Display Name | Description | Type | Default Value/Options | Required | | ---- | ------------ | ---- | --------------------- | -------- | ----------- | - | ServerUsername | Server Username | A username (or valid PAM key if the username is stored in a KF Command configured PAM integration). If acting as an *agent* using local file access, just check *No Value* | Secret | | 🔲 Unchecked | - | ServerPassword | Server Password | A password (or valid PAM key if the password is stored in a KF Command configured PAM integration). The password can also be an SSH private key if connecting via SSH to a server using SSH private key authentication. If acting as an *agent* using local file access, just check *No Value* | Secret | | 🔲 Unchecked | + | ServerUsername | Server Username | Not used, but a value is required. Enter anything into this field. | Secret | | 🔲 Unchecked | + | ServerPassword | Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | Secret | | 🔲 Unchecked | The Custom Fields tab should look like this: @@ -307,38 +297,125 @@ TODO Certificate Store Configuration is an optional section. If this section doe
F5 WAF CA (f5WafCa) -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +* **Manually with the Command UI** +
Create Certificate Stores manually in the UI + 1. **Navigate to the _Certificate Stores_ page in Keyfactor Command.** -> The content in this section can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store). + Log into Keyfactor Command, toggle the _Locations_ dropdown, and click _Certificate Stores_. + 2. **Add a Certificate Store.** -
+ Click the Add button to add a new Certificate Store. Use the table below to populate the **Attributes** in the **Add** form. + | Attribute | Description | + | --------- | ----------- | + | Category | Select "F5 WAF CA" or the customized certificate store name from the previous step. | + | Container | Optional container to associate certificate store with. | + | Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'). | + | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | + | Orchestrator | Select an approved orchestrator capable of managing `f5WafCa` certificates. Specifically, one with the `f5WafCa` capability. | + | ServerUsername | Not used, but a value is required. Enter anything into this field. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | -## Discovering Certificate Stores with the Discovery Job -
F5 WAF TLS + -### F5 WAF TLS Discovery Job -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +
Attributes eligible for retrieval by a PAM Provider on the Universal Orchestrator + + If a PAM provider was installed _on the Universal Orchestrator_ in the [Installation](#Installation) section, the following parameters can be configured for retrieval _on the Universal Orchestrator_. + | Attribute | Description | + | --------- | ----------- | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + + + Please refer to the **Universal Orchestrator (remote)** usage section ([PAM providers on the Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam)) for your selected PAM provider for instructions on how to load attributes orchestrator-side. + + > Any secret can be rendered by a PAM provider _installed on the Keyfactor Command server_. The above parameters are specific to attributes that can be fetched by an installed PAM provider running on the Universal Orchestrator server itself. +
+ + +
+ +* **Using kfutil** + +
Create Certificate Stores with kfutil + + 1. **Generate a CSV template for the f5WafCa certificate store** + + ```shell + kfutil stores import generate-template --store-type-name f5WafCa --outpath f5WafCa.csv + ``` + 2. **Populate the generated CSV file** + + Open the CSV file, and reference the table below to populate parameters for each **Attribute**. + | Attribute | Description | + | --------- | ----------- | + | Category | Select "F5 WAF CA" or the customized certificate store name from the previous step. | + | Container | Optional container to associate certificate store with. | + | Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'). | + | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | + | Orchestrator | Select an approved orchestrator capable of managing `f5WafCa` certificates. Specifically, one with the `f5WafCa` capability. | + | ServerUsername | Not used, but a value is required. Enter anything into this field. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + + + + +
Attributes eligible for retrieval by a PAM Provider on the Universal Orchestrator + + If a PAM provider was installed _on the Universal Orchestrator_ in the [Installation](#Installation) section, the following parameters can be configured for retrieval _on the Universal Orchestrator_. + | Attribute | Description | + | --------- | ----------- | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + + + > Any secret can be rendered by a PAM provider _installed on the Keyfactor Command server_. The above parameters are specific to attributes that can be fetched by an installed PAM provider running on the Universal Orchestrator server itself. +
+ + + 3. **Import the CSV file to create the certificate stores** + + ```shell + kfutil stores import csv --store-type-name f5WafCa --file f5WafCa.csv + ``` +
+ +> The content in this section can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store). -TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info
+## Discovering Certificate Stores with the Discovery Job +The following table describes the required and optional fields to schedule a Discovery job for the `f5WafTls` and `f5WafCa` certificate store types. + +In Keyfactor Command, navigate to Certificate Stores from the Locations Menu and then click on the Discover tab. -
F5 WAF CA +| Attribute | Description | +| --------- |------------------------------------------------------------------------------------------------------------------------------------------------| +| Category | Select either F5WafTls or F5WafCa depending on whether you want to return namespaces for TLS certificates or CA Root certificates. | +| Orchestrator | Select an approved orchestrator capable of managing F5 WAF certificates. Specifically, one with the f5WafTls and f5WafCa capabilities. | +| Schedule | Enter the schedule for when you want the job to run | +| Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'. | +| Server Username | This is not used but required in the UI. Enter any value. | +| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Requirements](#requirements) for more details on creating this token. | +| Directories to Search | Not used for this integration. Leave Blank. | +| Directories to ignore | Not used for this integration. Leave Blank. | +| Extensions | Not used for this integration. Leave Blank. | +| File name patterns to match | Not used for this integration. Leave Blank. | +| Follow SymLinks | Not used for this integration. Leave Unchecked. | +| Follow SymLinks | Not used for this integration. Leave Unchecked. | +| Use SSL? | Not used for this integration. Leave Unchecked. | +Discovery jobs will return all known namespaces for this F5 WAF instance. Please note that because Keyfactor Command has a restriction on multiple certificate stores having the same Client Machine and Store Path, certificate stores for f5WafTls will return stores with a "tls-" prefixed to the beginning of the store path (namespace); while f5WafCA stores will have "ca-" prefixed. Any jobs that run for stores with these prefixes will have these prefixes removed before calling any F5 WAF APIs. What this means is a store path (namespace) for an f5WafTls store of "tls-namespace1" will be the same as one labeled "namespace1". -### F5 WAF CA Discovery Job + +### F5 WAF TLS Discovery Job TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -
From 6f6d854a81d508b1217ddf894fa71c1fb8cdd28e Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Mon, 23 Dec 2024 20:45:20 +0000 Subject: [PATCH 06/16] ab#66563 --- docsource/f5wafTls.md | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/docsource/f5wafTls.md b/docsource/f5wafTls.md index d53d056..1a698e5 100644 --- a/docsource/f5wafTls.md +++ b/docsource/f5wafTls.md @@ -1,20 +1,9 @@ ## Overview -TODO Overview is a required section - -## Requirements - -TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - -## Discovery Job Configuration - -TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - -## Certificate Store Configuration - -TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - -## Global Store Type Section - -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. +Use cases supported: +1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. +2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. +3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. +4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. From 4a8504d3ab7a27af7b4cf3f62e14c3f84ffd5558 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Mon, 23 Dec 2024 20:47:57 +0000 Subject: [PATCH 07/16] ab#66563 --- docsource/f5wafTls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsource/f5wafTls.md b/docsource/f5wafTls.md index 1a698e5..c8df687 100644 --- a/docsource/f5wafTls.md +++ b/docsource/f5wafTls.md @@ -6,4 +6,4 @@ Use cases supported: 1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. 2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. 3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. -4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. +4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. \ No newline at end of file From f7caf02877b77c0842f7a0d6d91f63210bdd57c1 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Mon, 23 Dec 2024 20:49:19 +0000 Subject: [PATCH 08/16] ab#66563 --- .gitignore | 1 + docsource/f5wafTls.md | 9 --------- 2 files changed, 1 insertion(+), 9 deletions(-) delete mode 100644 docsource/f5wafTls.md diff --git a/.gitignore b/.gitignore index dfcfd56..fa10bf3 100644 --- a/.gitignore +++ b/.gitignore @@ -348,3 +348,4 @@ MigrationBackup/ # Ionide (cross platform F# VS Code tools) working folder .ionide/ +/docsource/f5waftls.md diff --git a/docsource/f5wafTls.md b/docsource/f5wafTls.md deleted file mode 100644 index c8df687..0000000 --- a/docsource/f5wafTls.md +++ /dev/null @@ -1,9 +0,0 @@ -## Overview - -The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. - -Use cases supported: -1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. -2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. -3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. -4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. \ No newline at end of file From 2e1af3ef78d5186ce988f4a8fa3538db743e2028 Mon Sep 17 00:00:00 2001 From: Lee Fine <50836957+leefine02@users.noreply.github.com> Date: Mon, 23 Dec 2024 15:51:07 -0500 Subject: [PATCH 09/16] Delete docsource/f5waftls.md --- docsource/f5waftls.md | 20 -------------------- 1 file changed, 20 deletions(-) delete mode 100644 docsource/f5waftls.md diff --git a/docsource/f5waftls.md b/docsource/f5waftls.md deleted file mode 100644 index d53d056..0000000 --- a/docsource/f5waftls.md +++ /dev/null @@ -1,20 +0,0 @@ -## Overview - -TODO Overview is a required section - -## Requirements - -TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - -## Discovery Job Configuration - -TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - -## Certificate Store Configuration - -TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - -## Global Store Type Section - -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - From 0497eb5059c023ffd3041628fd98ee89c12ccbdf Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Mon, 23 Dec 2024 20:51:58 +0000 Subject: [PATCH 10/16] Update generated docs --- docsource/f5waftls.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docsource/f5waftls.md diff --git a/docsource/f5waftls.md b/docsource/f5waftls.md new file mode 100644 index 0000000..d53d056 --- /dev/null +++ b/docsource/f5waftls.md @@ -0,0 +1,20 @@ +## Overview + +TODO Overview is a required section + +## Requirements + +TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Discovery Job Configuration + +TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Certificate Store Configuration + +TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Global Store Type Section + +TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + From f8a7388f4addc391c9d311f8a41a6b1da6324b60 Mon Sep 17 00:00:00 2001 From: Lee Fine <50836957+leefine02@users.noreply.github.com> Date: Mon, 23 Dec 2024 15:55:20 -0500 Subject: [PATCH 11/16] ab#66563 --- .gitignore | 3 --- 1 file changed, 3 deletions(-) diff --git a/.gitignore b/.gitignore index fa10bf3..7b6d294 100644 --- a/.gitignore +++ b/.gitignore @@ -346,6 +346,3 @@ healthchecksdb # Backup folder for Package Reference Convert tool in Visual Studio 2017 MigrationBackup/ -# Ionide (cross platform F# VS Code tools) working folder -.ionide/ -/docsource/f5waftls.md From a4b1a2fc037defe03dcb14b0190de0dcf5a8bf6a Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Mon, 23 Dec 2024 20:56:59 +0000 Subject: [PATCH 12/16] ab#66563 --- .gitignore | 2 +- docsource/f5waftls.md | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 docsource/f5waftls.md diff --git a/.gitignore b/.gitignore index fa10bf3..7e03d23 100644 --- a/.gitignore +++ b/.gitignore @@ -348,4 +348,4 @@ MigrationBackup/ # Ionide (cross platform F# VS Code tools) working folder .ionide/ -/docsource/f5waftls.md + diff --git a/docsource/f5waftls.md b/docsource/f5waftls.md new file mode 100644 index 0000000..c8df687 --- /dev/null +++ b/docsource/f5waftls.md @@ -0,0 +1,9 @@ +## Overview + +The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. + +Use cases supported: +1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. +2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. +3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. +4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates. \ No newline at end of file From 4c8e95349aa03ca6a971843eca23756f426b9cf2 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Mon, 23 Dec 2024 20:59:23 +0000 Subject: [PATCH 13/16] Update generated docs --- README.md | 85 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 8554f1a..2c90e6b 100644 --- a/README.md +++ b/README.md @@ -39,10 +39,14 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types ### f5WafTls -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +The f5WafTls certificate store type is used to manage F5 Distributed Multi-Cloud App Connect TLS certificates. -TODO Overview is a required section +Use cases supported: +1. Discovery of TLS stores. Discovery for F5 WAF returns any discoverable namespaces in the F5 WAF instance. +2. Inventory of a TLS store. All TLS certificates, bound or unbound, within a namespace will be returned to Keyfactor Command. +3. Management-Add. Add a new certificate or renew an existing one. Renew will work for both bound and unbound certificates. All existing binding will remain in place, bound to the same alias with the newly replaced/renewed certificate. +4. Management-Delete. Remove an existing certificate. Will only work for unbound certificates.
F5 WAF CA (f5WafCa) @@ -83,18 +87,6 @@ F5 Multi-Cloud App Connect uses API tokens to authenticate when calling APIs. A ![](Images/image5.gif) ![](Images/image6.gif) -
F5 WAF TLS (f5WafTls) - -### F5 WAF TLS Requirements -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - - -TODO Requirements is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -
- - - - ## Create Certificate Store Types @@ -104,8 +96,6 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types
F5 WAF TLS (f5WafTls) -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - * **Create f5WafTls using kfutil**: @@ -284,11 +274,64 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types
F5 WAF TLS (f5WafTls) -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info -TODO Certificate Store Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +* **Manually with the Command UI** + +
Create Certificate Stores manually in the UI + + 1. **Navigate to the _Certificate Stores_ page in Keyfactor Command.** + + Log into Keyfactor Command, toggle the _Locations_ dropdown, and click _Certificate Stores_. + + 2. **Add a Certificate Store.** + + Click the Add button to add a new Certificate Store. Use the table below to populate the **Attributes** in the **Add** form. + | Attribute | Description | + | --------- | ----------- | + | Category | Select "F5 WAF TLS" or the customized certificate store name from the previous step. | + | Container | Optional container to associate certificate store with. | + | Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'). | + | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | + | Orchestrator | Select an approved orchestrator capable of managing `f5WafTls` certificates. Specifically, one with the `f5WafTls` capability. | + | ServerUsername | Not used, but a value is required. Enter anything into this field. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + + +
+ +* **Using kfutil** + +
Create Certificate Stores with kfutil + + 1. **Generate a CSV template for the f5WafTls certificate store** + + ```shell + kfutil stores import generate-template --store-type-name f5WafTls --outpath f5WafTls.csv + ``` + 2. **Populate the generated CSV file** + + Open the CSV file, and reference the table below to populate parameters for each **Attribute**. + | Attribute | Description | + | --------- | ----------- | + | Category | Select "F5 WAF TLS" or the customized certificate store name from the previous step. | + | Container | Optional container to associate certificate store with. | + | Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'). | + | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | + | Orchestrator | Select an approved orchestrator capable of managing `f5WafTls` certificates. Specifically, one with the `f5WafTls` capability. | + | ServerUsername | Not used, but a value is required. Enter anything into this field. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + + + + + 3. **Import the CSV file to create the certificate stores** + + ```shell + kfutil stores import csv --store-type-name f5WafTls --file f5WafTls.csv + ``` +
> The content in this section can be supplimented by the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Certificate%20Stores.htm?Highlight=certificate%20store). @@ -411,12 +454,6 @@ In Keyfactor Command, navigate to Certificate Stores from the Locations Menu and Discovery jobs will return all known namespaces for this F5 WAF instance. Please note that because Keyfactor Command has a restriction on multiple certificate stores having the same Client Machine and Store Path, certificate stores for f5WafTls will return stores with a "tls-" prefixed to the beginning of the store path (namespace); while f5WafCA stores will have "ca-" prefixed. Any jobs that run for stores with these prefixes will have these prefixes removed before calling any F5 WAF APIs. What this means is a store path (namespace) for an f5WafTls store of "tls-namespace1" will be the same as one labeled "namespace1". -### F5 WAF TLS Discovery Job -TODO Global Store Type Section is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - - -TODO Discovery Job Configuration is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info - From a98826be78658814d70879e6bdde8b7c50d20861 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Thu, 26 Dec 2024 14:43:48 +0000 Subject: [PATCH 14/16] ab#66563 --- integration-manifest.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/integration-manifest.json b/integration-manifest.json index 907f170..a58383f 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -45,7 +45,7 @@ "DefaultValue": "", "Required": false, "IsPAMEligible": false, - "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token." + "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites)." } ], "EntryParameters": [], @@ -93,7 +93,7 @@ "DefaultValue": "", "Required": false, "IsPAMEligible": true, - "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token." + "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites)." } ], "EntryParameters": [], From 4134ad83e0ab0b47cb33bc4412e0c545d8b3cdb0 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Thu, 26 Dec 2024 14:45:56 +0000 Subject: [PATCH 15/16] Update generated docs --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 2c90e6b..80b78ca 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types | Name | Display Name | Description | Type | Default Value/Options | Required | | ---- | ------------ | ---- | --------------------- | -------- | ----------- | | ServerUsername | Server Username | Not used, but a value is required. Enter anything into this field. | Secret | | 🔲 Unchecked | - | ServerPassword | Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | Secret | | 🔲 Unchecked | + | ServerPassword | Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | Secret | | 🔲 Unchecked | The Custom Fields tab should look like this: @@ -211,7 +211,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types | Name | Display Name | Description | Type | Default Value/Options | Required | | ---- | ------------ | ---- | --------------------- | -------- | ----------- | | ServerUsername | Server Username | Not used, but a value is required. Enter anything into this field. | Secret | | 🔲 Unchecked | - | ServerPassword | Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | Secret | | 🔲 Unchecked | + | ServerPassword | Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | Secret | | 🔲 Unchecked | The Custom Fields tab should look like this: @@ -294,7 +294,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | | Orchestrator | Select an approved orchestrator capable of managing `f5WafTls` certificates. Specifically, one with the `f5WafTls` capability. | | ServerUsername | Not used, but a value is required. Enter anything into this field. | - | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | @@ -321,7 +321,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | | Orchestrator | Select an approved orchestrator capable of managing `f5WafTls` certificates. Specifically, one with the `f5WafTls` capability. | | ServerUsername | Not used, but a value is required. Enter anything into this field. | - | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | @@ -360,7 +360,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | | Orchestrator | Select an approved orchestrator capable of managing `f5WafCa` certificates. Specifically, one with the `f5WafCa` capability. | | ServerUsername | Not used, but a value is required. Enter anything into this field. | - | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | @@ -370,7 +370,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types If a PAM provider was installed _on the Universal Orchestrator_ in the [Installation](#Installation) section, the following parameters can be configured for retrieval _on the Universal Orchestrator_. | Attribute | Description | | --------- | ----------- | - | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | Please refer to the **Universal Orchestrator (remote)** usage section ([PAM providers on the Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam)) for your selected PAM provider for instructions on how to load attributes orchestrator-side. @@ -401,7 +401,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types | Store Path | The Multi-Cloud App Connect namespace containing the certificates you wish to manage. | | Orchestrator | Select an approved orchestrator capable of managing `f5WafCa` certificates. Specifically, one with the `f5WafCa` capability. | | ServerUsername | Not used, but a value is required. Enter anything into this field. | - | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | @@ -411,7 +411,7 @@ The F5 WAF Universal Orchestrator extension implements 2 Certificate Store Types If a PAM provider was installed _on the Universal Orchestrator_ in the [Installation](#Installation) section, the following parameters can be configured for retrieval _on the Universal Orchestrator_. | Attribute | Description | | --------- | ----------- | - | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](https://github.com/Keyfactor/f5-waf-orchestrator#creating-an-f5-waf-api-token) for more details on creating this token. | + | ServerPassword | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites). | > Any secret can be rendered by a PAM provider _installed on the Keyfactor Command server_. The above parameters are specific to attributes that can be fetched by an installed PAM provider running on the Universal Orchestrator server itself. From 36da4d1213e7d23434bb96945447b8825b46e5a8 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Thu, 26 Dec 2024 15:09:45 +0000 Subject: [PATCH 16/16] ab#66563 --- docsource/content.md | 2 +- integration-manifest.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docsource/content.md b/docsource/content.md index 1f84152..476aa28 100644 --- a/docsource/content.md +++ b/docsource/content.md @@ -28,7 +28,7 @@ In Keyfactor Command, navigate to Certificate Stores from the Locations Menu and | Schedule | Enter the schedule for when you want the job to run | | Client Machine | The URL for the F5 Distributed Cloud instance (typically ending in '.console.ves.volterra.io'. | | Server Username | This is not used but required in the UI. Enter any value. | -| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Requirements](#requirements) for more details on creating this token. | +| Server Password | The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see Requirements & Prerequisites for more information on creating this token. | | Directories to Search | Not used for this integration. Leave Blank. | | Directories to ignore | Not used for this integration. Leave Blank. | | Extensions | Not used for this integration. Leave Blank. | diff --git a/integration-manifest.json b/integration-manifest.json index a58383f..c7e110e 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -45,7 +45,7 @@ "DefaultValue": "", "Required": false, "IsPAMEligible": false, - "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites)." + "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please review Requirements & Prerequisites for more information on creating this API token." } ], "EntryParameters": [], @@ -93,7 +93,7 @@ "DefaultValue": "", "Required": false, "IsPAMEligible": true, - "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please see [Creating an F5 WAF API Token](#requirements-&-prerequisites)." + "Description": "The API Token configured in the F5 Distributed Cloud instance's Account Settings. Please review Requirements & Prerequisites for more information on creating this API token." } ], "EntryParameters": [],