bug fix, doctool migration

.github/workflows/keyfactor-bootstrap-workflow.yml → .github/workflows/keyfactor-release-workflow.yml

@@ -1,4 +1,4 @@
-name: Keyfactor Bootstrap Workflow
+name: Keyfactor Release 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@v3.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 }}
+

AzureKeyVault.sln

@@ -7,10 +7,11 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AzureKeyVault", "AzureKeyVa
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{AB1BF579-FBD3-4F59-BBF2-7B973B9AD1DB}"
 	ProjectSection(SolutionItems) = preProject
+		docsource\akv.md = docsource\akv.md
 		CHANGELOG.md = CHANGELOG.md
+		docsource\content.md = docsource\content.md
 		create_sp_azure.md = create_sp_azure.md
 		integration-manifest.json = integration-manifest.json
-		readme_source.md = readme_source.md
 	EndProjectSection
 EndProject
 Global

AzureKeyVault/AzureKeyVault.csproj

@@ -1,15 +1,14 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-	<PropertyGroup>
-		<TargetFramework>netcoreapp3.1</TargetFramework>
+	<PropertyGroup>		
+		<TargetFrameworks>net6.0;net8.0</TargetFrameworks>
     <AssemblyName>Keyfactor.Extensions.Orchestrators.AKV</AssemblyName>
     <RootNamespace>Keyfactor.Extensions.Orchestrator.AzureKeyVault</RootNamespace>
 		<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
-	  <SignAssembly>false</SignAssembly>
 	  <Copyright />
 	  <PackageLicenseExpression>https://apache.org/licenses/LICENSE-2.0</PackageLicenseExpression>
-	  <PackageLicenseFile></PackageLicenseFile> 
-		<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
+	  <PackageLicenseFile></PackageLicenseFile>
+		<AppendTargetFrameworkToOutputPath>true</AppendTargetFrameworkToOutputPath>
 		<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
 	</PropertyGroup>
 

AzureKeyVault/Jobs/Management.cs

@@ -39,7 +39,7 @@ public JobResult ProcessJob(ManagementJobConfiguration config)
                 FailureMessage = "Invalid Management Operation"
             };
 
-            var tagsJSON = config.JobProperties["CertificateTags"].ToString();
+            var tagsJSON = config.JobProperties["CertificateTags"]?.ToString();
 
             switch (config.OperationType)
             {

CHANGELOG.md

@@ -1,9 +1,13 @@
+- 3.1.8
+  - Fixed bug where enrollment would fail if the CertificateTags field was not defined as an entry parameter	
+  - Convert to .net6/8 dual build
+  - Update README to use doctool
+
 - 3.1.7
   - Added support for Azure KeyVault Certificate Metadata via Entry Parameters
   - Fixed issue where an error would be returned during Inventory if 0 certificates were found
   - Converted to BouncyCastle crypto libraries
-  -	Convert to .net6/8 dual build
-  - Update README to use doctool  
+
 
 - 3.1.6
   - Preventing CertStore parameters from getting used if present but empty. 	

create_sp_azure.md

@@ -1,37 +1,43 @@
 1) Log into [your azure portal](https://portal.azure.com)
 
-1) Navigate to [Azure active directory](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) in the portal.
+1) Navigate
+   to [Azure active directory](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) in
+   the portal.
 
 1) Select "App registrations" from the menu.
 
 1) Click "+ New registration"
 
 1) Give it a name such as "keyfactor-akv" and leave the first radio button selected
 
-     ![App Registration Overview](/Images/app-registration.PNG)
+   ![App Registration Overview](/Images/app-registration.PNG)
 
 1) Once the entity has been created, you should be directed to the overview view.
 
-     ![App Registration Overview](/Images/managed-app-link.png)
+   ![App Registration Overview](/Images/managed-app-link.png)
 
 1) From here, copy the _Directory (tenant) ID_.
 
-1) Click on the underlined link above.  You should see the managed application details that look similar to the below screen shot.
+1) Click on the underlined link above. You should see the managed application details that look similar to the below
+   screen shot.
 
-     ![App registration object Id](/Images/objectId.png)
+   ![App registration object Id](/Images/objectId.png)
 
 1) Copy the _Application (client) ID_
 
-1) Now we have a App registration and values for  _Directory (tenant) ID_, _Application (client) ID_.  These will be used by the integration for authentication to Azure.
+1) Now we have a App registration and values for  _Directory (tenant) ID_, _Application (client) ID_. These will be used
+   by the integration for authentication to Azure.
 
-1) (Optional) If creating a multi-tenant service principal, the following AzureAD Powershell command must be run in each tenant:  
+1) (Optional) If creating a multi-tenant service principal, the following AzureAD Powershell command must be run in each
+   tenant:
    ``` Powershell
    New-AzADServicePrincipal -ApplicationId <Application ID>
    ```
 
 #### Assign Permissions
 
-In order to be able to discover and create new Azure Keyvault certificate stores, the app principal that we created must be provided with the "Keyvault Administrator" role at the _Resource Group_ level.[^1]
+In order to be able to discover and create new Azure Keyvault certificate stores, the app principal that we created must
+be provided with the "Keyvault Administrator" role at the _Resource Group_ level.[^1]
 _If there are multiple resource groups that will contain Key Vaults to be managed, you should repeat for each._
 
 Here are the steps for assigning this role.
@@ -40,76 +46,93 @@ Here are the steps for assigning this role.
 1) Select "Access control (IAM)" from the left menu.
 1) Click "Add", then "Add Role Assignment" to create a new role assignment
 
-     ![Resource Group Add Role](/Images/resource-group-add-role.PNG)
+   ![Resource Group Add Role](/Images/resource-group-add-role.PNG)
 1) Search and Select the "Key Vault Administrator" role.
 1) Search and Select the principal we created.
 
-     ![Select Principal](/Images/rg-role-select-principal.PNG)
+   ![Select Principal](/Images/rg-role-select-principal.PNG)
 1) Click "Review and Assign" and save the role assignment.
 
-[^1]: If discovery and create store functionality are not neeeded, it is also possible to manage individual certificate stores without the need to provide resource group level authority.  The steps to do assign permissions for an individual Azure Keyvault are described [here](#assign-permissions-for-an-individual-key-vault-via-access-policy) for vaults using Access Policy based permissions and [here](#assign-permissions-for-an-individual-key-vault-via-rbac) for Individual Key Vaults using Role-Based Access Control (RBAC).
+[^1]: If discovery and create store functionality are not neeeded, it is also possible to manage individual certificate
+stores without the need to provide resource group level authority. The steps to do assign permissions for an individual
+Azure Keyvault are described [here](#assign-permissions-for-an-individual-key-vault-via-access-policy) for vaults using
+Access Policy based permissions and [here](#assign-permissions-for-an-individual-key-vault-via-rbac) for Individual Key
+Vaults using Role-Based Access Control (RBAC).
 
 #### Assign Permissions for an Individual Key Vault via RBAC
 
-If you only need to manage a single instance of a Key Vault and do not require creation and discovery of new Key Vaults, you can provision access to the specific instance without needing to provide the service principal the "Keyvault Administrator" role at the resource group level.
+If you only need to manage a single instance of a Key Vault and do not require creation and discovery of new Key Vaults,
+you can provision access to the specific instance without needing to provide the service principal the "Keyvault
+Administrator" role at the resource group level.
 
-Follow the below steps in order to provide management access for our service principal to a specific instance of a Key Vault:
+Follow the below steps in order to provide management access for our service principal to a specific instance of a Key
+Vault:
 
 1) Navigate to the Azure Portal and then to your instance of the Azure Keyvault
 
 1) Go to "Access control (IAM)" in the navigation menu for the Key vault.
 
 1) Click on "Add role assignment"
 
-     ![Vault RBAC](/Images/vault-rbac.png)
+   ![Vault RBAC](/Images/vault-rbac.png)
 
-1) Find the Keyvault Administrator role in the list.  Select it and click "Next"
+1) Find the Keyvault Administrator role in the list. Select it and click "Next"
 
-    ![Vault RBAC KVAdmin](/Images/vault-rbac-kvadmin.png)
+   ![Vault RBAC KVAdmin](/Images/vault-rbac-kvadmin.png)
 
 1) On the next screen, click "Select members" and then search for the service principal we created above.
 
-    ![Vault RBAC principal](/Images/vault-rbac-principal.png)
+   ![Vault RBAC principal](/Images/vault-rbac-principal.png)
 
 1) Select the service principal, click "select", and then "Next"
 
 1) On the final screen, you should see something similar to the following:
 
-     ![Vault RBAC final](/Images/vault-rbac-final.png)
+   ![Vault RBAC final](/Images/vault-rbac-final.png)
 
-1) Click "Review + assign" to finish assigning the role of Keyvault Administrator for this Key Vault to our service principal account.
+1) Click "Review + assign" to finish assigning the role of Keyvault Administrator for this Key Vault to our service
+   principal account.
 
 #### Assign Permissions for an Individual Key Vault via Access Policy
 
-Access to an Azure Key Vault instance can be granted via Role Based Access Control (RBAC) or with class Azure Resource Access Policies.  The below steps are for provisioning access to a single instance of a Key Vault using Access Policies.  If you are using RBAC at the resource group level (necessary for discovery and creating new Key Vaults via Keyfactor) we recommend following RBAC (above).  Alternatively, you will need to assign explicit permissions to the service principal for any Key Vault that is using Access Policy for Access Control if the Key Vault should be managed with Keyfactor.
+Access to an Azure Key Vault instance can be granted via Role Based Access Control (RBAC) or with class Azure Resource
+Access Policies. The below steps are for provisioning access to a single instance of a Key Vault using Access Policies.
+If you are using RBAC at the resource group level (necessary for discovery and creating new Key Vaults via Keyfactor) we
+recommend following RBAC (above). Alternatively, you will need to assign explicit permissions to the service principal
+for any Key Vault that is using Access Policy for Access Control if the Key Vault should be managed with Keyfactor.
 
-Following the below steps will provide our service principal with the ability to manage keys in an existing vault, without providing it the elevated permissions required for discovering existing vaults or creating new ones.  If you've completed the steps in the previous section for the resource group that contains the Key Vault(s) you would like to manage and the Key Vault(s) are using RBAC, the below steps are not necessary.
+Following the below steps will provide our service principal with the ability to manage keys in an existing vault,
+without providing it the elevated permissions required for discovering existing vaults or creating new ones. If you've
+completed the steps in the previous section for the resource group that contains the Key Vault(s) you would like to
+manage and the Key Vault(s) are using RBAC, the below steps are not necessary.
 
 1) Navigate to the Azure Portal and then to your instance of the Azure Keyvault.
 
 1) Go to "Access Policies" in the navigation menu for the Key vault.
 
 1) Click "+ Add Access Policy"
 
-1) In the first drop-down, you can select "Certificate Management".  This will select all certificate management permissions.
+1) In the first drop-down, you can select "Certificate Management". This will select all certificate management
+   permissions.
 
-     ![Permission List](/Images/cert-mgmt-perm-list.PNG)
+   ![Permission List](/Images/cert-mgmt-perm-list.PNG)
 
 1) Click "Select Principal" to open the search pane.
 
 1) Find the Application Registration we created above, select it, and click "Select".
 
-     ![Select Principal](/Images/select-principal.PNG)
+   ![Select Principal](/Images/select-principal.PNG)
 
 1) Leave "Authorized application" unselected.
 
 1) Click "Add".
 
-1) After you are redirected to the "Access policies" view, you should see the App Registration listed under "APPLICATION".
+1) After you are redirected to the "Access policies" view, you should see the App Registration listed under "
+   APPLICATION".
 
 1) Click "Save" at the top of this view.
 
-     ![Select Principal](/Images/save-access-policy.PNG)
+   ![Select Principal](/Images/save-access-policy.PNG)
 
 #### Generate an Access Token
 

docsource/akv.md

@@ -0,0 +1,24 @@
+## Overview
+
+The Azure Keyvault Certificate Store Type is designed to integrate with Microsoft Azure Key Vault, enabling users to
+manage and automate the lifecycle of cryptographic certificates stored in Azure Key Vault through Keyfactor Command.
+This Certificate Store Type represents the connection and configuration necessary to interact with specific instances of
+Azure Key Vault, allowing for operations such as inventory, addition, removal, and discovery of certificates and
+certificate stores.
+
+This integration leverages Azure's robust security infrastructure, utilizing OAuth-based authentication methods
+including Service Principals, User Assigned Managed Identities, and System Assigned Managed Identities. This ensures
+that only authorized entities can manage the certificates stored within the Key Vault.
+
+While this Certificate Store Type provides a powerful means of managing certificates, there are some important caveats
+to consider. For example, if your instance of Azure Key Vault utilizes private or custom endpoints, or is hosted outside
+of the Azure Public cloud (e.g., Government, China, Germany instances), certain functions like discovery job
+functionality may not be supported. Additionally, the configuration of access control through Azure's Role Based Access
+Control (RBAC) or classic Access Policies must be meticulously managed to ensure sufficient permissions for the
+orchestrator to perform its tasks.
+
+The integration does not require a specific SDK, as it interacts with Azure services directly through their APIs.
+However, ensuring that the orchestrator has network access to Azure endpoints is crucial for smooth operation. Being
+mindful of these caveats and limitations will help ensure successful deployment and use of the Azure Keyvault
+Certificate Store Type within your organization’s security framework.
+