The F5 Orchestrator allows for the remote management of F5 Stores. Discovery, Inventory, and Management functions are supported.
This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications.
The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Extensions, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Extension see below in this readme.
The Universal Orchestrator is the successor to the Windows Orchestrator. This Orchestrator Extension plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator.
F5 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 tab. If you want to contribute actual bug fixes or proposed enhancements, use the Pull requests tab.
The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.1
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 | ✓ | ✓ |
This orchestrator extension has the ability to connect to a variety of supported PAM providers to allow for the retrieval of various client hosted secrets right from the orchestrator server itself. This eliminates the need to set up the PAM integration on Keyfactor Command which may be in an environment that the client does not want to have access to their PAM provider.
The secrets that this orchestrator extension supports for use with a PAM Provider are:
| Name | Description |
|---|---|
| ServerUsername | The user id that will be used to authenticate to the F5 installation |
| ServerPassword | The password that will be used to authenticate to the F5 installation |
It is not necessary to use a PAM Provider for all of the secrets available above. If a PAM Provider should not be used, simply enter in the actual value to be used, as normal.
If a PAM Provider will be used for one of the fields above, start by referencing the Keyfactor Integration Catalog. 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
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 on the Universal Orchestrator.
Next, complete configuration of the PAM Provider on the UO by editing the manifest.json of the PAM Provider (e.g. located at extensions/Hashicorp-Vault/manifest.json). The "initialization" parameters need to be entered here:
"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.
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 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:
{"Secret":"my-kv-secret","Key":"myServerPassword"}This text would be entered in as the value for the Server Password, instead of entering in the actual password. The Orchestrator will attempt to use the PAM Provider to retrieve the Server Password. If PAM should not be used, just directly enter in the value for the field.
Please note that this integration will work with the Universal Orchestrator version 10.1 or earlier, OR 10.4.1 or greater
The F5 Orchestrator supports three different types of certificates stores with the capabilities for each below:
- CA Bundles
- Discovery
- Inventory*
- Management (Add and Remove)
- Web Server Device Certificates
- Inventory*
- Management (Add, but replacement/renewal of existing certificate only)
- SSL Certificates
- Discovery
- Inventory*
- Management (Add and Remove)
*Special note on private keys: One of the pieces of information that Keyfactor collects during an Inventory job is whether or not the certificate stored in F5 has a private key. The private key is NEVER actually retrieved by Keyfactor, but Keyfactor does track whether one exists. F5 does not provide an API to determine this, so by convention, all CA Bundle certificates are deemed to not have private keys, while Web Server and SSL certificates are deemed to have them. Any Management jobs adding (new or renewal) a certificate will renew without the private key for CA Bundle stores and with the private key for Web Server or SSL stores.
The version number of a the F5 Orchestrator can be verified by right clicking on the F5Orchestrator.dll file, selecting Properties, and then clicking on the Details tab.
- Stop the Keyfactor Universal Orchestrator Service.
- In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "extensions" folder. Underneath that, create a new folder named F5 or another name of your choosing.
- Download the latest version of the F5 Orchestrator from GitHub.
- Copy the contents of the download installation zip file into the folder created in step 1.
- Start the Keyfactor Universal Orchestrator Service.
1. In Keyfactor Command, if any of the aforementioned certificate store types do not already exist, create a new certificate store type for each of the 3 that you wish to manage by navigating to Settings (the "gear" icon in the top right) => Certificate Store Types.
CA Bundles:
Web Server Certificates
SSL Certificates
- Name – Required. The display name of the new Certificate Store Type
- Short Name – Required. This value must match the folder name for this store type under the "extensions" folder in the install path.
- Custom Capability - Leave unchecked
- Supported Job Types – Select Inventory and Add for all 3 types, and Discovery for CA Bundles and SSL Certificates.
- General Settings - Select Needs Server. Leave Uses PowerShell unchecked. Select Blueprint Allowed if you plan to use blueprinting.
- Password Settings - Leave both options unchecked for F5-WS-REST and F5-CA-REST. Select Needs Store Password for F5-SL-REST.
- All selections on Advanced tab - Set the values on this tab exactly as they are shown in the above screen prints for each applicable store type.
The Custom Fields tab contains 10 custom store parameters (3 of which, Server Username, Server Password, and Use SSL were set up on the Basic tab and are not actually custom parameters you need or want to modify on this tab). The set up is consistent across store types, and should look as follows:
If any or all of the 3 certificate store types were already set up on installation of Keyfactor, you may only need to add Primary Node Online Required and Ignore SSL Warning. These parameters, however, are optional and only necessary if needed to be set to true. Please see the descriptions below in "2a. Create a F5 Certificate Store wihin Keyfactor Command.
2a. Create a F5 Certificate Store within Keyfactor Command
If you choose to manually create a F5 store In Keyfactor Command rather than running a Discovery job (Step 2b) to automatically find the store, you can navigate to Certificate Locations => Certificate Stores within Keyfactor Command to add the store. Below are the values that should be entered.
-
Category – Required. One of the 3 F5 store types - F5 Web Server REST, F5 CA Bundles REST, or F5 SSL Profiles REST (your configured names may be different based on what you entered when creating the certificate store types in Step 1).
-
Container – Optional. Select a container if utilized.
-
Client Machine – Required. The server name or IP Address for the F5 device.
-
Store Path – Required. Enter the name of the partition on the F5 device you wish to manage. This value is case sensitive, so if the partition name is "Common", it must be entered as "Common" and not "common".
-
Orchestrator – Required. Select the orchestrator you wish to use to manage this store
-
Primary Node Online Required – Optional. Select this if you wish to stop the orchestrator from adding, replacing or renewing certificates on nodes that are inactive. If this is not selected, adding, replacing and renewing certificates on inactive nodes will be allowed. If you choose not to add this custom field, the default value of False will be assumed.
-
Primary Node - Only required (and shown) if Primary Node Online Required is added and selected. Enter the fully qualified domain name of the F5 device that acts as the primary node in a highly available F5 implementation. If you're using a single F5 device, this will typically be the same value you entered in the Client Machine field.
-
Primary Node Check Retry Wait Seconds - Only required (and shown) if Primary Node Online Required is added and selected. Enter the number of seconds to wait between attempts to add/replace/renew a certificate if the node is inactive.
-
Primary Node Check Retry Maximum - Only required (and shown) if Primary Node Online Required is added and selected. Enter the number of times a Management-Add job will attempt to add/replace/renew a certificate if the node is inactive before failing.
-
Version of F5 - Required. Select v13, v14, or v15 to match the version for the F5 device being managed
-
Server Username/Server Password - Required. The credentials for server login can be any of:
-
UserId/Password
-
PAM provider information to pass the UserId/Password or UserId/SSH private key credentials
-
-
Use SSL - Required. True if using https to access the F5 device. False if using http.
-
Ignore SSL Warning - Optional. Select this if you wish to ignore SSL warnings from F5 that occur during API calls when the site does not have a trusted certificate with the proper SAN bound to it. If you choose not to add this custom field, the default value of False will be assumed and SSL warnings will cause errors during orchestrator extension jobs.
-
Use Token Authentication - Optional. Select this if you wish to use F5's token authentiation instead of basic authentication for all API requests. If you choose not to add this custom field, the default value of False will be assumed and basic authentication will be used for all API requests for all jobs. Setting this value to True will enable an initial basic authenticated request to acquire an authentication token, which will then be used for all subsequent API requests.
-
Store Password - Required for F5-SL-REST only. Check "No Password" if you wish the private key of any added certificate to be set to Key Security Type "Normal". Enter a value (either a password or pointer to an installed PAM provider key for the password) to be used to encrypt the private key of any added certificate for Key Security Type of "Password".
-
Inventory Schedule – Set a schedule for running Inventory jobs or none, if you choose not to schedule Inventory at this time.
2b. (Optional) Schedule a F5 Discovery Job
Rather than manually creating F5 certificate stores, you can schedule a Discovery job to search find them (CA Bundle and SSL Certificate store types only).
First, in Keyfactor Command navigate to Certificate Locations => Certificate Stores. Select the Discover tab and then the Schedule button. Complete the dialog and click Done to schedule.
-
Category – Required. The F5 store type you wish to find stores for.
-
Orchestrator – Select the orchestrator you wish to use to manage this store
-
Client Machine & Credentials – Required. The server name or IP Address and login credentials for the F5 device. The credentials for server login can be any of:
- UserId/Password
- PAM provider information to pass the UserId/Password or UserId/SSH private key credentials
When entering the credentials, UseSSL must be selected.
-
When – Required. The date and time when you would like this to execute.
-
Directories to search – Required but not used. This field is not used in the search to Discover certificate stores, but is a required field in this dialog, so just enter any value. It will not be used.
-
Directories to ignore/Extensions/File name patterns to match/Follow SymLinks/Include PKCS12 Files – Not used. Leave blank.
Once the Discovery job has completed, a list of F5 certificate store locations should show in the Certificate Stores Discovery tab in Keyfactor Command. Right click on a store and select Approve to bring up a dialog that will ask for the remaining necessary certificate store parameters described in Step 2a. Complete those and click Save, and the Certificate Store should now show up in the list of stores in the Certificate Stores tab.
When creating cert store type manually, that store property names and entry parameter names are case sensitive