From e8510dfdb80bd01b9f7c3b5846639037a4535276 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Mon, 16 Dec 2024 20:52:58 +0000 Subject: [PATCH 1/6] ab#66269 --- .../Imperva.curl | 45 --- Fortigate/FortigateStore.cs | 370 ++++++++++-------- Fortigate/Management.cs | 9 +- docsource/content.md | 49 +++ docsource/fortigate.md | 1 + readme-src/readme-pam-support.md | 4 - 6 files changed, 269 insertions(+), 209 deletions(-) delete mode 100644 Certificate Store Type CURL Script/Imperva.curl create mode 100644 docsource/content.md create mode 100644 docsource/fortigate.md delete mode 100644 readme-src/readme-pam-support.md diff --git a/Certificate Store Type CURL Script/Imperva.curl b/Certificate Store Type CURL Script/Imperva.curl deleted file mode 100644 index c269023..0000000 --- a/Certificate Store Type CURL Script/Imperva.curl +++ /dev/null @@ -1,45 +0,0 @@ -###CURL script to create Fortigate certificate store type - -###Replacement Variables - Manually replace these before running### -# {URL} - Base URL for your Keyfactor deployment -# {UserName} - User name with access to run Keyfactor APIs -# {UserPassword} - Password for the UserName above - -curl -X POST {URL}/keyfactorapi/certificatestoretypes -H "Content-Type: application/json" -H "x-keyfactor-requested-with: APIClient" -u {UserName}:{UserPassword} -d '{ - "Name": "Fortigate", - "ShortName": "Fortigate", - "Capability": "Fortigate", - "ServerRequired": false, - "BlueprintAllowed": true, - "CustomAliasAllowed": "Required", - "PowerShell": false, - "PrivateKeyAllowed": "Required", - "SupportedOperations": { - "Add": true, - "Create": false, - "Discovery": false, - "Enrollment": false, - "Remove": true - }, - "PasswordOptions": { - "Style": "Default", - "EntrySupported": false, - "StoreRequired": true - }, - "Properties": [], - "EntryParameters": [] -}' -Footer -© 2022 GitHub, Inc. -Footer navigation -Terms -Privacy -Security -Status -Docs -Contact GitHub -Pricing -API -Training -Blog -About diff --git a/Fortigate/FortigateStore.cs b/Fortigate/FortigateStore.cs index be5baae..d33363d 100644 --- a/Fortigate/FortigateStore.cs +++ b/Fortigate/FortigateStore.cs @@ -33,6 +33,7 @@ using Microsoft.Extensions.Logging; using Keyfactor.Orchestrators.Common.Enums; using System.Reflection.Metadata; +using System.Linq.Expressions; namespace Keyfactor.Extensions.Orchestrator.Fortigate { @@ -80,16 +81,26 @@ public FortigateStore(string fortigateHost, string accessToken) public void Delete(string alias) { - logger = LogHandler.GetClassLogger(this.GetType()); - - var result = DeleteResource(delete_certificate_api + alias); + logger.MethodEntry(LogLevel.Debug); - logger.MethodExit(LogLevel.Debug); + try + { + DeleteResource(delete_certificate_api + alias); + } + catch (Exception ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, $"Error deleting certificate {alias}: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); + } } public bool Exists(string alias) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); try { @@ -106,12 +117,11 @@ public bool Exists(string alias) { logger.MethodExit(LogLevel.Debug); } - } public void UpdateUsage(string alias, string path, string name, string attribute) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); var attributeValue = new Dictionary(); attributeValue.Add("q_origin_key", alias); @@ -122,99 +132,130 @@ public void UpdateUsage(string alias, string path, string name, string attribute var parameters = new Dictionary(); parameters.Add("vdom", "root"); - var result = PutAsJson(endpoint, main, parameters); - logger.LogDebug(result); - logger.MethodExit(LogLevel.Debug); + try + { + PutAsJson(endpoint, main, parameters); + } + catch (Exception ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, $"Error updating usage for {alias}: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); + } } public Usage Usage(string alias) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); var parameters = new Dictionary(); parameters.Add("vdom", "root"); parameters.Add("scope", "global"); parameters.Add("mkey", alias); parameters.Add("qtypes", "[160]"); - var result = GetResource(cert_usage_api, parameters); - var response = JsonConvert.DeserializeObject>(result); - logger.MethodExit(LogLevel.Debug); - return response.results; + try + { + var result = GetResource(cert_usage_api, parameters); + var response = JsonConvert.DeserializeObject>(result); + return response.results; + } + catch (Exception ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, $"Error checking usage for {alias}: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); + } } public void Insert(string alias, string cert, string privateKey, bool overwrite, string password = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); - if (overwrite) + try { - var tmpAlias = alias + "_kftmp"; - var existing = Exists(alias); - var tmpExisting = Exists(tmpAlias); - - //if there is an existing record - if (existing) + if (overwrite) { - //check to see if it's in use - var existingUsage = Usage(alias); + var tmpAlias = alias + "_kftmp"; + var existing = Exists(alias); + var tmpExisting = Exists(tmpAlias); - //if it's currently in use - if (existingUsage.currently_using.Length > 0) + //if there is an existing record + if (existing) { - //if we don't have a tmp create a temp - if (!tmpExisting) - { - //create tmp - Insert(tmpAlias, cert, privateKey); - - tmpExisting = true; - } + //check to see if it's in use + var existingUsage = Usage(alias); - foreach (var existingUsing in existingUsage.currently_using) + //if it's currently in use + if (existingUsage.currently_using.Length > 0) { - UpdateUsage(tmpAlias, existingUsing.path, existingUsing.name, existingUsing.attribute); + //if we don't have a tmp create a temp + if (!tmpExisting) + { + //create tmp + Insert(tmpAlias, cert, privateKey); + + tmpExisting = true; + } + + foreach (var existingUsing in existingUsage.currently_using) + { + UpdateUsage(tmpAlias, existingUsing.path, existingUsing.name, existingUsing.attribute); + } } - } - logger.LogDebug("Deleting alias:" + alias); - Delete(alias); - } + logger.LogDebug("Deleting alias:" + alias); + Delete(alias); + } - logger.LogDebug("Inserting alias:" + alias); - Insert(alias, cert, privateKey, password); + logger.LogDebug("Inserting alias:" + alias); + Insert(alias, cert, privateKey, password); - //if we have an existing temp record - if (tmpExisting) - { - //check to see if it has any binds - var tmpUsage = Usage(tmpAlias); - if (tmpUsage.currently_using.Length > 0) + //if we have an existing temp record + if (tmpExisting) { - //transfer binds back to original - foreach (var tmpUsing in tmpUsage.currently_using) + //check to see if it has any binds + var tmpUsage = Usage(tmpAlias); + if (tmpUsage.currently_using.Length > 0) { - UpdateUsage(alias, tmpUsing.path, tmpUsing.name, tmpUsing.attribute); + //transfer binds back to original + foreach (var tmpUsing in tmpUsage.currently_using) + { + UpdateUsage(alias, tmpUsing.path, tmpUsing.name, tmpUsing.attribute); + } } + logger.LogDebug("Deleting alias:" + tmpExisting); + Delete(tmpAlias); } - logger.LogDebug("Deleting alias:" + tmpExisting); - Delete(tmpAlias); + } + else + { + //no overwrite so we just try to insert + logger.LogDebug("Inserting certificate with alias: " + alias); + Insert(alias, cert, privateKey, password); } } - else + catch (Exception ex) { - //no overwrite so we just try to insert - logger.LogDebug("Inserting certificate with alias: " + alias); - Insert(alias, cert, privateKey, password); + logger.LogError(FortigateException.FlattenExceptionMessages(ex, $"Error inserting/replacing certificate {alias}: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); } - - logger.MethodExit(LogLevel.Debug); } private void Insert(string alias, string cert, string privateKey, string password = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); var cert_resource = new cmdb_certificate_resource() { @@ -226,108 +267,126 @@ private void Insert(string alias, string cert, string privateKey, string passwor type = "regular" }; - logger.LogDebug(alias); - logger.LogDebug("key_file_content:" + privateKey); - logger.LogDebug("file_content:" + cert); - - Insert(cert_resource); - - logger.MethodExit(LogLevel.Debug); - } - - private void Insert(cmdb_certificate_resource cert) - { - logger = LogHandler.GetClassLogger(this.GetType()); - var parameters = new Dictionary(); parameters.Add("vdom", "root"); - var result = PostAsJson(import_certificate_api, cert, parameters); - logger.LogDebug(result); - - logger.MethodExit(LogLevel.Debug); + try + { + PostAsJson(import_certificate_api, cert_resource, parameters); + } + catch (Exception ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, $"Error inserting certificate {alias}: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); + } } public List List() { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); List items = new List(); - var result = GetResource(available_certificates); - var response = JsonConvert.DeserializeObject>(result); + try + { + var result = GetResource(available_certificates); + var response = JsonConvert.DeserializeObject>(result); - foreach( var cert in response.results) - { - if (cert.type == "local-cer") + foreach( var cert in response.results) { - var certFile = DownloadFileAsString(cert.name, cert.type); - - var item = new CurrentInventoryItem() + if (cert.type == "local-cer") { - Alias = cert.name, - Certificates = new string[] { certFile }, - ItemStatus = OrchestratorInventoryItemStatus.Unknown, - PrivateKeyEntry = true, - UseChainLevel = false - }; - - items.Add(item); - } - } + var certFile = DownloadFileAsString(cert.name, cert.type); - logger.MethodExit(LogLevel.Debug); + var item = new CurrentInventoryItem() + { + Alias = cert.name, + Certificates = new string[] { certFile }, + ItemStatus = OrchestratorInventoryItemStatus.Unknown, + PrivateKeyEntry = true, + UseChainLevel = false + }; + + items.Add(item); + } + } - return items; + return items; + } + catch (Exception ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, "Error retrieving certificate list: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); + } } private string DownloadFileAsString(string mkey, string type) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); var parameters = new Dictionary(); parameters.Add("mkey", mkey); parameters.Add("type", type); - var response = client.GetAsync(GetUrl(download_certificate, parameters)).GetAwaiter().GetResult(); - var content = response.Content.ReadAsStringAsync().GetAwaiter().GetResult(); - if (!response.IsSuccessStatusCode) - throw new Exception($"Error retrieving certificate {mkey}: {content}"); + try + { + var response = client.GetAsync(GetUrl(download_certificate, parameters)).GetAwaiter().GetResult(); + var content = response.Content.ReadAsStringAsync().GetAwaiter().GetResult(); + if (!response.IsSuccessStatusCode) + throw new Exception($"Error retrieving certificate {mkey}: {content}"); - logger.MethodExit(LogLevel.Debug); - return content; + return content; + } + catch (Exception ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, $"Error retrieving downloading file {mkey}: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); + } } private String PostAsJson(string endpoint, cmdb_certificate_resource obj, Dictionary additionalParams = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); string content = ""; + var url = GetUrl(endpoint, additionalParams); + var stringContent = new StringContent(JsonConvert.SerializeObject(obj), Encoding.UTF8, "application/json"); + stringContent.Headers.ContentType = new MediaTypeHeaderValue("application/json"); + try { - var url = GetUrl(endpoint, additionalParams); - logger.LogDebug("postAsJson to url:" + url); - var stringContent = new StringContent(JsonConvert.SerializeObject(obj), Encoding.UTF8, "application/json"); - stringContent.Headers.ContentType = new MediaTypeHeaderValue("application/json"); HttpResponseMessage responseMessage = client.PostAsync(url, stringContent).GetAwaiter().GetResult(); - logger.LogDebug("response message received"); content = responseMessage.Content.ReadAsStringAsync().GetAwaiter().GetResult(); - logger.LogDebug("Ensuring status code.."); if (!responseMessage.IsSuccessStatusCode) throw new Exception($"Error adding certificate {obj.certname}: {content}"); - logger.MethodExit(LogLevel.Debug); return responseMessage.StatusCode.ToString(); } - catch (HttpRequestException e) + catch (HttpRequestException ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, "Error performing POST: ")); + throw; + } + finally { - logger.LogError("Error performing post resource: " + e.Message); - throw e; + logger.MethodExit(LogLevel.Debug); } } - private String DeleteResource(string endpoint, Dictionary additionalParams = null) + private void DeleteResource(string endpoint, Dictionary additionalParams = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); try { @@ -335,53 +394,54 @@ private String DeleteResource(string endpoint, Dictionary additi string content = responseMessage.Content.ReadAsStringAsync().GetAwaiter().GetResult(); if (!responseMessage.IsSuccessStatusCode) throw new Exception($"Error removing certificate: {content}"); - - logger.MethodExit(LogLevel.Debug); - return responseMessage.StatusCode.ToString(); } - catch (HttpRequestException e) + catch (HttpRequestException ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, "Error performing DELETE: ")); + throw; + } + finally { - logger.LogError("Error performing deleting resource: " + e.Message); - throw e; + logger.MethodExit(LogLevel.Debug); } } - private String PutAsJson(string endpoint, Object obj, Dictionary additionalParams = null) + private void PutAsJson(string endpoint, Object obj, Dictionary additionalParams = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); + + var stringContent = new StringContent(JsonConvert.SerializeObject(obj), Encoding.UTF8, "application/json"); + stringContent.Headers.ContentType = new MediaTypeHeaderValue("application/json"); try { - var stringContent = new StringContent(JsonConvert.SerializeObject(obj), Encoding.UTF8, "application/json"); - stringContent.Headers.ContentType = new MediaTypeHeaderValue("application/json"); - HttpResponseMessage responseMessage = client.PutAsync(GetUrl(endpoint, additionalParams), stringContent).GetAwaiter().GetResult(); string content = responseMessage.Content.ReadAsStringAsync().GetAwaiter().GetResult(); if (!responseMessage.IsSuccessStatusCode) throw new Exception(content); - - logger.MethodExit(LogLevel.Debug); - return responseMessage.StatusCode.ToString(); } - catch (HttpRequestException e) + catch (HttpRequestException ex) + { + logger.LogError(FortigateException.FlattenExceptionMessages(ex, "Error performing PUT: ")); + throw; + } + finally { - logger.LogError("Error performing put resource: " + e.Message); - throw e; + logger.MethodExit(LogLevel.Debug); } } private String GetUrl(string endpoint, Dictionary additionalParams = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); + logger.MethodExit(LogLevel.Debug); return AddQueryParams("https://" + FortigateHost + endpoint, additionalParams); - - logger.MethodExit(LogLevel.Debug); } private String AddQueryParams(string endpoint, Dictionary additionalParams = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); var parameters = new Dictionary(); parameters.Add("access_token", AccessToken); @@ -393,36 +453,28 @@ private String AddQueryParams(string endpoint, Dictionary additi } } - try - { - var queryString = endpoint + "?" + string.Join("&", parameters.Select(kvp => $"{HttpUtility.UrlEncode(kvp.Key)}={HttpUtility.UrlEncode(kvp.Value)}")); - - logger.LogDebug("QueryString:" + queryString); + var queryString = endpoint + "?" + string.Join("&", parameters.Select(kvp => $"{HttpUtility.UrlEncode(kvp.Key)}={HttpUtility.UrlEncode(kvp.Value)}")); + logger.MethodExit(LogLevel.Debug); - logger.MethodExit(LogLevel.Debug); - return queryString; - } - catch (Exception e) - { - logger.LogDebug("Exception occured while creating query string", e); - throw e; - } + return queryString; } private string GetResource(string endpoint, Dictionary additionalParams = null) { - logger = LogHandler.GetClassLogger(this.GetType()); + logger.MethodEntry(LogLevel.Debug); try { - logger.MethodExit(LogLevel.Debug); - return client.GetStringAsync(GetUrl(endpoint, additionalParams)).GetAwaiter().GetResult(); } - catch(HttpRequestException e) + catch(HttpRequestException ex) { - logger.LogError("Error performing get resource: " + e.Message); - throw e; + logger.LogError(FortigateException.FlattenExceptionMessages(ex, $"Error performing get resource: ")); + throw; + } + finally + { + logger.MethodExit(LogLevel.Debug); } } } diff --git a/Fortigate/Management.cs b/Fortigate/Management.cs index 2044d9e..7ebd5ff 100644 --- a/Fortigate/Management.cs +++ b/Fortigate/Management.cs @@ -32,6 +32,8 @@ public class Management : IManagementJobExtension { public IPAMSecretResolver _resolver; public string ExtensionName => string.Empty; + + ILogger logger; public Management(IPAMSecretResolver resolver) { @@ -41,7 +43,8 @@ public Management(IPAMSecretResolver resolver) //Job Entry Point public JobResult ProcessJob(ManagementJobConfiguration config) { - ILogger logger = LogHandler.GetClassLogger(this.GetType()); + logger = LogHandler.GetClassLogger(this.GetType()); + logger.LogDebug($"Begin {config.Capability} for job id {config.JobId}..."); logger.LogDebug($"Client Machine: {config.CertificateStoreDetails.ClientMachine}"); @@ -81,6 +84,8 @@ public JobResult ProcessJob(ManagementJobConfiguration config) private (byte[], byte[]) GetPemFromPFX(byte[] pfxBytes, char[] pfxPassword) { + logger.MethodEntry(LogLevel.Debug); + Pkcs12StoreBuilder storeBuilder = new Pkcs12StoreBuilder(); Pkcs12Store p = storeBuilder.Build(); p.Load(new MemoryStream(pfxBytes), pfxPassword); @@ -108,6 +113,8 @@ public JobResult ProcessJob(ManagementJobConfiguration config) Func pemify = null; pemify = (ss => ss.Length <= 64 ? ss : ss.Substring(0, 64) + "\n" + pemify(ss.Substring(64))); String certPem = certStart + pemify(Convert.ToBase64String(p.GetCertificate(alias).Certificate.GetEncoded())) + certEnd; + + logger.MethodExit(LogLevel.Debug); return (Encoding.ASCII.GetBytes(certPem), Encoding.ASCII.GetBytes(privateKeyString)); } } diff --git a/docsource/content.md b/docsource/content.md new file mode 100644 index 0000000..dc15197 --- /dev/null +++ b/docsource/content.md @@ -0,0 +1,49 @@ +## Overview + +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. + + +## Requirements + +An administrator account must be set up in F5 to be used with this orchestrator extension. This F5 user id is what must be used as credentials when setting up a Keyfactor Command certificate store pointing to the F5 device intending to be managed. + + +## Discovery + +For SSL Certificate (F5-SL-REST) and CA Bundle (F5-CA-REST) store types, discovery jobs can be scheduled to find F5 partitions that can be configured as Keyfactor Command certificate stores. + +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. +![](images/image14.png) + +- **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. diff --git a/docsource/fortigate.md b/docsource/fortigate.md new file mode 100644 index 0000000..ed37e8e --- /dev/null +++ b/docsource/fortigate.md @@ -0,0 +1 @@ +## Overview diff --git a/readme-src/readme-pam-support.md b/readme-src/readme-pam-support.md deleted file mode 100644 index 630cab4..0000000 --- a/readme-src/readme-pam-support.md +++ /dev/null @@ -1,4 +0,0 @@ -|Name|Description| -|----|-----------| -|StorePassword|The Fortigate API Access Token used to execute Fortigate API requests| - From 6b528eff94daabf9d5443bc39bee06536c60469f Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Tue, 17 Dec 2024 16:22:08 +0000 Subject: [PATCH 2/6] ab#66269 --- .../workflows/keyfactor-starter-workflow.yml | 56 ++++++------------- Fortigate/Fortigate.csproj | 17 +++--- Fortigate/FortigateResponse.cs | 18 ------ integration-manifest.json | 40 ++++++------- 4 files changed, 40 insertions(+), 91 deletions(-) delete mode 100644 Fortigate/FortigateResponse.cs diff --git a/.github/workflows/keyfactor-starter-workflow.yml b/.github/workflows/keyfactor-starter-workflow.yml index 6e26a91..a4649f2 100644 --- a/.github/workflows/keyfactor-starter-workflow.yml +++ b/.github/workflows/keyfactor-starter-workflow.yml @@ -1,42 +1,20 @@ -name: Starter Workflow -on: [workflow_dispatch, push, pull_request] +name: Keyfactor Bootstrap Workflow -jobs: - call-create-github-release-workflow: - uses: Keyfactor/actions/.github/workflows/github-release.yml@main - - get-manifest-properties: - runs-on: windows-latest - outputs: - update_catalog: ${{ steps.read-json.outputs.prop }} - steps: - - uses: actions/checkout@v3 - - name: Read json - id: read-json - shell: pwsh - run: | - $json = Get-Content integration-manifest.json | ConvertFrom-Json - echo "::set-output name=prop::$(echo $json.update_catalog)" - - call-dotnet-build-and-release-workflow: - needs: [call-create-github-release-workflow] - uses: Keyfactor/actions/.github/workflows/dotnet-build-and-release.yml@main - with: - release_version: ${{ needs.call-create-github-release-workflow.outputs.release_version }} - release_url: ${{ needs.call-create-github-release-workflow.outputs.release_url }} - release_dir: Fortigate/bin/Release - secrets: - token: ${{ secrets.PRIVATE_PACKAGE_ACCESS }} +on: + workflow_dispatch: + pull_request: + types: [opened, closed, synchronize, edited, reopened] + push: + create: + branches: + - 'release-*.*' - call-generate-readme-workflow: - if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' - uses: Keyfactor/actions/.github/workflows/generate-readme.yml@main +jobs: + call-starter-workflow: + uses: keyfactor/actions/.github/workflows/starter.yml@3.1.2 secrets: - token: ${{ secrets.APPROVE_README_PUSH }} - - call-update-catalog-workflow: - needs: get-manifest-properties - if: needs.get-manifest-properties.outputs.update_catalog == 'True' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') - uses: Keyfactor/actions/.github/workflows/update-catalog.yml@main - secrets: - token: ${{ secrets.SDK_SYNC_PAT }} + 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/Fortigate/Fortigate.csproj b/Fortigate/Fortigate.csproj index 9a9e58f..2d7f9a1 100644 --- a/Fortigate/Fortigate.csproj +++ b/Fortigate/Fortigate.csproj @@ -1,23 +1,20 @@ - false - netcoreapp3.1 + true + net6.0;net8.0 true + disable - - - - + + + Always + - - - - diff --git a/Fortigate/FortigateResponse.cs b/Fortigate/FortigateResponse.cs deleted file mode 100644 index 7648d43..0000000 --- a/Fortigate/FortigateResponse.cs +++ /dev/null @@ -1,18 +0,0 @@ - - -namespace Keyfactor.Extensions.Orchestrator.GCP.Api -{ - public class FortigateResponse - { - "http_method":"GET", - "results":[] -"vdom":"root", - "path":"system", - "name":"available-certificates", - "action":"", - "status":"success", - "serial":"FGVM02TM21009640", - "version":"v7.0.0", - "build":66 - } -} \ No newline at end of file diff --git a/integration-manifest.json b/integration-manifest.json index 7a58675..6fb53eb 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -7,28 +7,15 @@ "link_github": false, "support_level": "community", "update_catalog": false, + "release_project": "Fortigate/Fortigate.csproj", + "release_dir": "Fortigate/bin/Release", "about": { "orchestrator": { "UOFramework": "10.1", "pam_support": true, - "win": { - "supportsCreateStore": false, - "supportsDiscovery": false, - "supportsManagementAdd": true, - "supportsManagementRemove": true, - "supportsReenrollment": false, - "supportsInventory": true - }, - "linux": { - "supportsCreateStore": false, - "supportsDiscovery": false, - "supportsManagementAdd": true, - "supportsManagementRemove": true, - "supportsReenrollment": false, - "supportsInventory": true - }, - "store_types": { - "Fortigate": { + "keyfactor_platform_version": "10.4", + "store_types": [ + { "Name": "Fortigate", "ShortName": "Fortigate", "Capability": "Fortigate", @@ -47,12 +34,17 @@ "PasswordOptions": { "Style": "Default", "EntrySupported": false, - "StoreRequired": true - }, - "Properties": [], - "EntryParameters": [] - } - } + "StoreRequired": true, + "StorePassword": { + "Description": "Enter the Fortigate API Token here", + "IsPAMEligible": true + }, + "Properties": [], + "EntryParameters": [], + "ClientMachineDescription": "The IP address or DNS of the Fortigate server", + "StorePathDescription": "This is not used in this integration, but is a required field in the UI. Just enter any value here" + } + ] } } } \ No newline at end of file From 97df3852e35a2274236918413a6471617935beb5 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Wed, 18 Dec 2024 13:34:52 +0000 Subject: [PATCH 3/6] ab#66269 --- .../workflows/keyfactor-starter-workflow.yml | 2 +- readme_source.md | 69 ------------------- 2 files changed, 1 insertion(+), 70 deletions(-) delete mode 100644 readme_source.md diff --git a/.github/workflows/keyfactor-starter-workflow.yml b/.github/workflows/keyfactor-starter-workflow.yml index a4649f2..61ea7a0 100644 --- a/.github/workflows/keyfactor-starter-workflow.yml +++ b/.github/workflows/keyfactor-starter-workflow.yml @@ -1,4 +1,4 @@ -name: Keyfactor Bootstrap Workflow +name: Keyfactor Bootstrap Workflow on: workflow_dispatch: diff --git a/readme_source.md b/readme_source.md deleted file mode 100644 index fcd07dc..0000000 --- a/readme_source.md +++ /dev/null @@ -1,69 +0,0 @@ -## Use Cases Supported and Limitations - -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) - -## Fortigate Version Supported - -The Fortigate Orchestrator Extension was tested using Fortigate, version 7.2.4 - -## Fortigate Orchestrator Extension Versioning - -The version number of a the Fortigate Orchestrator Extension can be verified by right clicking on the Fortigate.dll file in the Extensions/Fortigate installation folder, selecting Properties, and then clicking on the Details tab. - -## Fortigate Orchestrator Extension Installation - -1. Create the Fortigate certificate store type. This can be done either: a) using the Keyfactor Command UI to manually set up the certificate store type (please refer to the Keyfactor Command Reference Guide for more information on how to do this), or b) by using the Keyfactor Command API to automate the creation of the store type. Please see the provided CURL script [here](Certificate%20Store%20Type%20CURL%20Script/Fortigate.curl). A detailed description of how the Fortigate certificate store type should be configured can be found in the Fortigate Certificate Store Type section below. -2. Stop the Keyfactor Orchestrator Service on the server hosting the Keyfactor Orchestrator. -3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "extensions" folder. Underneath that, create a new folder. The name doesn't matter, but something descriptive like "Fortigate" would probably be best. -4. Download the latest version of the Fortigate Orchestrator from [GitHub](https://github.com/Keyfactor/fortigate-orchestrator). -5. Copy the contents of the download installation zip file to the folder created in step 1. -6. Start the Keyfactor Orchestrator Service on the server hosting the Keyfactor Orchestrator. - -## Fortigate Setup - -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. - -## Certificate Store Type Settings - -Below are the values you need to enter if you choose to manually create the Fortigate certificate store type in the Keyfactor Command UI (related to Step 1 of Fortigate Orchestrator Extension Installation above). - -*Basic Tab:* -- **Name** – Required. The display name you wish to use for the new certificate store type. Suggested value - Fortigate -- **ShortName** - Required. Suggested value - Fortigate. If you choose to use a different value, you will need to modify the manifest.json file accordingly. -- **Custom Capability** - Unchecked -- **Supported Job Types** - Inventory, Add, and Remove should all be checked. -- **Needs Server** - Unchecked -- **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. -- **Uses PoserShell** - Unchecked -- **Requires Store Password** - Checked. -- **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:* -None - -*Entry Parameters:* -None - -## Certificate Store Setup - -Please refer to the Keyfactor Command Reference Guide for information on creating certificate stores in Keyfactor Command. However, there are a few fields that are important to highlight here: -- Category - Select "Fortigate" or whatever ShortName you chose for the store type. -- Client Machine - The IP address or DNS for your Fortigate server. -- Store Path - This is not used in this integration, but is a required field in the UI. Just enter any value here. -- Password - Click the button here and enter the Fortigate API Token you previously set up (See Fortigate Setup earlier in this README). From 8ee251495d37c867759726ddffac7587d9e57346 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Wed, 18 Dec 2024 13:44:29 +0000 Subject: [PATCH 4/6] ab#66269 --- integration-manifest.json | 1 + 1 file changed, 1 insertion(+) diff --git a/integration-manifest.json b/integration-manifest.json index 6fb53eb..f23c986 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -44,6 +44,7 @@ "ClientMachineDescription": "The IP address or DNS of the Fortigate server", "StorePathDescription": "This is not used in this integration, but is a required field in the UI. Just enter any value here" } + } ] } } From b40acfbe1dc03ecfdf41256694c9f56af7bad8f2 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Wed, 18 Dec 2024 13:45:28 +0000 Subject: [PATCH 5/6] Update generated docs --- README.md | 337 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 235 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 1f824ba..f420e1f 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,298 @@ -# Fortigate +

+ Fortigate Universal Orchestrator Extension +

-This integration is used to inventory and manage certificates in Fortigate. +

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

-#### Integration status: Production - Ready for use in production environments. +

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

-## About the Keyfactor Universal Orchestrator Extension +## Overview -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 F5 Orchestrator supports three different types of certificates stores with the capabilities for each below: -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. +- 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) -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. +*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. -## Support for Fortigate +## Compatibility -Fortigate is open source and community supported, meaning that there is **no SLA** applicable for these tools. +This integration is compatible with Keyfactor Universal Orchestrator version 10.1 and later. -###### 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. +## Support +The Fortigate Universal Orchestrator extension is open source and community supported, meaning that there is **no SLA** applicable. + +> 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. +## Requirements & Prerequisites +Before installing the Fortigate 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. ---- +An administrator account must be set up in F5 to be used with this orchestrator extension. This F5 user id is what must be used as credentials when setting up a Keyfactor Command certificate store pointing to the F5 device intending to be managed. +## Create the Fortigate Certificate Store Type -## Keyfactor Version Supported +To use the Fortigate Universal Orchestrator extension, you **must** create the Fortigate Certificate Store Type. This only needs to happen _once_ per Keyfactor Command instance. -The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.1 -## Platform Specific Notes -The Keyfactor Universal Orchestrator may be installed on either Windows or Linux based platforms. The certificate operations supported by a capability may vary based what platform the capability is installed on. The table below indicates what capabilities are supported based on which platform the encompassing Universal Orchestrator is running. -| Operation | Win | Linux | -|-----|-----|------| -|Supports Management Add|✓ |✓ | -|Supports Management Remove|✓ |✓ | -|Supports Create Store| | | -|Supports Discovery| | | -|Supports Renrollment| | | -|Supports Inventory|✓ |✓ | +* **Create Fortigate using kfutil**: + ```shell + # Fortigate + kfutil store-types create Fortigate + ``` -## PAM Integration +* **Create Fortigate manually in the Command UI**: +
Create Fortigate manually in the Command UI -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. + Create a store type called `Fortigate` with the attributes in the tables below: -The secrets that this orchestrator extension supports for use with a PAM Provider are: + #### Basic Tab + | Attribute | Value | Description | + | --------- | ----- | ----- | + | Name | Fortigate | Display name for the store type (may be customized) | + | Short Name | Fortigate | Short display name for the store type | + | Capability | Fortigate | 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 | 🔲 Unchecked | 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 | ✅ Checked | 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. | -|Name|Description| -|----|-----------| -|StorePassword|The Fortigate API Access Token used to execute Fortigate API requests| - + The Basic tab should look like this: + + ![Fortigate Basic Tab](docsource/images/Fortigate-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: + + ![Fortigate Advanced Tab](docsource/images/Fortigate-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: + + ![Fortigate Custom Fields Tab](docsource/images/Fortigate-custom-fields-store-type-dialog.png) + + + +
+ +## Installation + +1. **Download the latest Fortigate Universal Orchestrator extension from GitHub.** + + Navigate to the [Fortigate Universal Orchestrator extension GitHub version page](https://github.com/Keyfactor/fortigate-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` | `fortigate-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`. + +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 Fortigate Universal Orchestrator extension inside the extensions directory.** + + Create a new directory called `fortigate-orchestrator`. + > The directory name does not need to match any names used elsewhere; it just has to be unique within the extensions directory. -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. +4. **Copy the contents of the downloaded and unzipped assemblies from __step 2__ to the `fortigate-orchestrator` directory.** -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. +5. **Restart the Universal Orchestrator service.** -### Example PAM Provider Setup + Refer to [Starting/Restarting the Universal Orchestrator service](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/StarttheService.htm). -To use a PAM Provider to resolve a field, in this example the __Server Password__ will be resolved by the `Hashicorp-Vault` provider, first install the PAM Provider extension from the [Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam) on the Universal Orchestrator. -Next, complete configuration of the PAM Provider on the UO by editing the `manifest.json` of the __PAM Provider__ (e.g. located at extensions/Hashicorp-Vault/manifest.json). The "initialization" parameters need to be entered here: +6. **(optional) PAM Integration** -~~~ json - "Keyfactor:PAMProviders:Hashicorp-Vault:InitializationInfo": { - "Host": "http://127.0.0.1:8200", - "Path": "v1/secret/data", - "Token": "xxxxxx" - } -~~~ + The Fortigate 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. -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. + 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). -### 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: +> 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). -~~~ json -{"Secret":"my-kv-secret","Key":"myServerPassword"} -~~~ -This text would be entered in as the value for the __Server Password__, instead of entering in the actual password. The Orchestrator will attempt to use the PAM Provider to retrieve the __Server Password__. If PAM should not be used, just directly enter in the value for the field. +## Defining Certificate Stores +* **Manually with the Command UI** ---- +
Create Certificate Stores manually in the UI + 1. **Navigate to the _Certificate Stores_ page in Keyfactor Command.** -## Use Cases Supported and Limitations + Log into Keyfactor Command, toggle the _Locations_ dropdown, and click _Certificate Stores_. -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 + 2. **Add a Certificate Store.** -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) + 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 "Fortigate" or the customized certificate store name from the previous step. | + | Container | Optional container to associate certificate store with. | + | Client Machine | | + | Store Path | | + | Orchestrator | Select an approved orchestrator capable of managing `Fortigate` certificates. Specifically, one with the `Fortigate` capability. | + | Store Password | Enter the Fortigate API Token here | -## Fortigate Version Supported + -The Fortigate Orchestrator Extension was tested using Fortigate, version 7.2.4 +
Attributes eligible for retrieval by a PAM Provider on the Universal Orchestrator -## Fortigate Orchestrator Extension Versioning + 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 | + | --------- | ----------- | + | Store Password | Enter the Fortigate API Token here | -The version number of a the Fortigate Orchestrator Extension can be verified by right clicking on the Fortigate.dll file in the Extensions/Fortigate installation folder, selecting Properties, and then clicking on the Details tab. + 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. -## Fortigate Orchestrator Extension Installation + > 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. +
+ -1. Create the Fortigate certificate store type. This can be done either: a) using the Keyfactor Command UI to manually set up the certificate store type (please refer to the Keyfactor Command Reference Guide for more information on how to do this), or b) by using the Keyfactor Command API to automate the creation of the store type. Please see the provided CURL script [here](Certificate%20Store%20Type%20CURL%20Script/Fortigate.curl). A detailed description of how the Fortigate certificate store type should be configured can be found in the Fortigate Certificate Store Type section below. -2. Stop the Keyfactor Orchestrator Service on the server hosting the Keyfactor Orchestrator. -3. In the Keyfactor Orchestrator installation folder (by convention usually C:\Program Files\Keyfactor\Keyfactor Orchestrator), find the "extensions" folder. Underneath that, create a new folder. The name doesn't matter, but something descriptive like "Fortigate" would probably be best. -4. Download the latest version of the Fortigate Orchestrator from [GitHub](https://github.com/Keyfactor/fortigate-orchestrator). -5. Copy the contents of the download installation zip file to the folder created in step 1. -6. Start the Keyfactor Orchestrator Service on the server hosting the Keyfactor Orchestrator. +
+ +* **Using kfutil** + +
Create Certificate Stores with kfutil + + 1. **Generate a CSV template for the Fortigate certificate store** + + ```shell + kfutil stores import generate-template --store-type-name Fortigate --outpath Fortigate.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 "Fortigate" or the customized certificate store name from the previous step. | + | Container | Optional container to associate certificate store with. | + | Client Machine | | + | Store Path | | + | Orchestrator | Select an approved orchestrator capable of managing `Fortigate` certificates. Specifically, one with the `Fortigate` capability. | + | Store Password | Enter the Fortigate API Token here | + + + +
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 | + | --------- | ----------- | + | Store Password | Enter the Fortigate API Token here | + + > 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 Fortigate --file Fortigate.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). + + +## Discovering Certificate Stores with the Discovery Job +For SSL Certificate (F5-SL-REST) and CA Bundle (F5-CA-REST) store types, discovery jobs can be scheduled to find F5 partitions that can be configured as Keyfactor Command certificate stores. + +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. +![](images/image14.png) + +- **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. -## Fortigate Setup +- **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. -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. +- **Directories to ignore/Extensions/File name patterns to match/Follow SymLinks/Include PKCS12 Files** - Not used. Leave blank. -## Certificate Store Type Settings +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. -Below are the values you need to enter if you choose to manually create the Fortigate certificate store type in the Keyfactor Command UI (related to Step 1 of Fortigate Orchestrator Extension Installation above). -*Basic Tab:* -- **Name** – Required. The display name you wish to use for the new certificate store type. Suggested value - Fortigate -- **ShortName** - Required. Suggested value - Fortigate. If you choose to use a different value, you will need to modify the manifest.json file accordingly. -- **Custom Capability** - Unchecked -- **Supported Job Types** - Inventory, Add, and Remove should all be checked. -- **Needs Server** - Unchecked -- **Blueprint Allowed** - Checked if you wish to make use of blueprinting. Please refer to the Keyfactor Command Reference Guide for more details on this feature. -- **Uses PoserShell** - Unchecked -- **Requires Store Password** - Checked. -- **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:* -None -*Entry Parameters:* -None +## License -## Certificate Store Setup +Apache License 2.0, see [LICENSE](LICENSE). -Please refer to the Keyfactor Command Reference Guide for information on creating certificate stores in Keyfactor Command. However, there are a few fields that are important to highlight here: -- Category - Select "Fortigate" or whatever ShortName you chose for the store type. -- Client Machine - The IP address or DNS for your Fortigate server. -- Store Path - This is not used in this integration, but is a required field in the UI. Just enter any value here. -- Password - Click the button here and enter the Fortigate API Token you previously set up (See Fortigate Setup earlier in this README). +## Related Integrations +See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator). \ No newline at end of file From 7199d0d060e45fdf1041bd0484d3bc191d546f21 Mon Sep 17 00:00:00 2001 From: Lee Fine Date: Wed, 18 Dec 2024 15:44:37 +0000 Subject: [PATCH 6/6] ab#66269 --- docsource/content.md | 52 ++++++++++---------------------------------- 1 file changed, 11 insertions(+), 41 deletions(-) diff --git a/docsource/content.md b/docsource/content.md index dc15197..d4342a4 100644 --- a/docsource/content.md +++ b/docsource/content.md @@ -1,49 +1,19 @@ ## Overview -The F5 Orchestrator supports three different types of certificates stores with the capabilities for each below: +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 -- 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 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 -An administrator account must be set up in F5 to be used with this orchestrator extension. This F5 user id is what must be used as credentials when setting up a Keyfactor Command certificate store pointing to the F5 device intending to be managed. - - -## Discovery - -For SSL Certificate (F5-SL-REST) and CA Bundle (F5-CA-REST) store types, discovery jobs can be scheduled to find F5 partitions that can be configured as Keyfactor Command certificate stores. - -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. -![](images/image14.png) - -- **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. +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. -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.