This integration allows the orchestrator to act as a client with access to an instance of the Azure Key Vault; allowing you to manage your certificates stored in the Azure Keyvault via Keyfactor.
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.
Azure Key Vault Orchestrator is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative.
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 Renrollment | ||
| Supports Inventory | ✓ | ✓ |
The high level steps required to configure the Azure Keyvault Orchestrator extension are:
Note that the certificate store type used by this Universal Orchestrator support for Azure Keyvault is not compatible with the certificate store type used by with Windows Orchestrator version for Azure Keyvault. If your Keyfactor instance has used the Windows Orchestrator for Azure Keyvault, a specific migration process is required. See Migrating from the Windows Orchestrator for Azure KeyVault section below.
If you were previously using the Azure Keyvault extension for the Windows Orchestrator, it is necessary to remove the Store Type definition as well as any Certificate stores that use the previous store type. This is because the store type parameters have changed in order to facilitate the Discovery and Create functionality.
If you have an existing AKV store type that was created for use with the Windows Orchestrator, you will need to follow the steps in one of the below sections in order to transfer the capability to the Universal Orchestrator.
⚠️ Before removing the certificate stores, view their configuration details and copy the values. Copying the values in the store parameters will save time when re-creating the stores.
Follow the below steps to remove the AKV capability from each active Windows Orchestrator that supports it:
If the Windows Orchestrator will still be used to manage some store types, we will remove only the Azure Keyvault functionality.
-
On the Windows Orchestrator host machine, run the Keyfactor Agent Configuration Wizard
-
Proceed through the steps to "Select Features"
-
Expand "Cert Stores" and un-check "Azure Keyvault"
-
Click "Apply Configuration"
-
Open the Keyfactor Platform and navigate to Orchestrators > Management
-
Confirm that "AKV" no longer appears under "Capabilities"
-
Navigate to Orchestrators > Management, select the orchestrator and click "DISAPPROVE" to disapprove it and cancel pending jobs.
-
Navigate to Locations > Certificate Stores
-
Select any stores with the Category "Azure Keyvault" and click "DELETE" to remove them from Keyfactor.
-
Navigate to the Administrative menu (gear icon) and then > Certificate Store Types
-
Select Azure Keyvault, click "DELETE" and confirm.
-
Navigate to Orchestrators > Management, select the orchestrator and click "APPROVE" to re-approve it for use.
-
Repeat these steps for any other Windows Orchestrators that support the AKV store type.
If the Windows Orchestrator is being completely replaced with the Universal Orchestrator, we can remove all associated stores and jobs.
- Navigate to Orchestrators > Management and select the Windows Orchestrator from the list.
- With the orchestrator selected, click the "RESET" button at the top of the list
- Make sure the orchestrator is still selected, and click "DISAPPROVE".
- Click "OK" to confirm that you will remove all jobs and certificate stores associated to this orchestrator.
- Navigate to the the Administrative (gear icon in the top right) and then Certificate Store Types
- Select "Azure Keyvault", click "DELETE" and confirm.
- Repeat these steps for any other Windows Orchestrators that support the AKV store type (if they can also be retired).
Note: Any Azure Keyvault certificate stores removed can be re-added once the Universal Orchestrator is configured with the AKV capability.
The Azure KeyVault orchestrator plugin supports several authentication options:
Steps for setting up each option are detailed below.
For the Orchestrator to be able to interact with the instance of Azure Keyvault, we will need to create an entity in Azure that will encapsulate the permissions we would like to grant it. In Azure, these intermediate entities are referred to as app registrations and they provision authority for external application access. To learn more about application and service principals, refer to this article.
To provision access to the Keyvault instance using a service principal identity, we will:
In order to complete these steps, you must have the Owner role for the Azure subscription, at least temporarily. This is required to create an App Registration in Azure Active Directory.
-
Log into your azure portal
-
Navigate to Azure active directory in the portal.
-
Select "App registrations" from the menu.
-
Click "+ New registration"
-
Give it a name such as "keyfactor-akv" and leave the first radio button selected
-
Once the entity has been created, you should be directed to the overview view.
-
From here, copy the Directory (tenant) ID.
-
Click on the underlined link above. You should see the managed application details that look similar to the below screen shot.
-
Copy the Application (client) ID
-
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.
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.
-
Navigate to the Azure portal and select a resource group that will contain the Keyvaults we would like to manage.
-
Select "Access control (IAM)" from the left menu.
-
Click "Add", then "Add Role Assignment" to create a new role assignment
-
Search and Select the "Key Vault Administrator" role.
-
Search and Select the principal we created.
-
Click "Review and Assign" and save the role assignment.
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:
-
Navigate to the Azure Portal and then to your instance of the Azure Keyvault
-
Go to "Access control (IAM)" in the navigation menu for the Key vault.
-
Click on "Add role assignment"
-
Find the Keyvault Administrator role in the list. Select it and click "Next"
-
On the next screen, click "Select members" and then search for the service principal we created above.
-
Select the service principal, click "select", and then "Next"
-
On the final screen, you should see something similar to the following:
-
Click "Review + assign" to finish assigning the role of Keyvault Administrator for this Key Vault to our service principal account.
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.
-
Navigate to the Azure Portal and then to your instance of the Azure Keyvault.
-
Go to "Access Policies" in the navigation menu for the Key vault.
-
Click "+ Add Access Policy"
-
In the first drop-down, you can select "Certificate Management". This will select all certificate management permissions.
-
Click "Select Principal" to open the search pane.
-
Find the Application Registration we created above, select it, and click "Select".
-
Leave "Authorized application" unselected.
-
Click "Add".
-
After you are redirected to the "Access policies" view, you should see the App Registration listed under "APPLICATION".
-
Click "Save" at the top of this view.
For authenticating to Azure via App Registration/Service Principal, we will need to generate an access token.
- Navigate to the App Registration we created earlier, in Azure Active Directory.
- Select "Certificates & Secrets" from the left menu.
- Click "+ New client secret"
- Give it a description such as "Keyfactor access"
- Select a valid expiration
- Click "Add".
- Copy the "Value" of the secret before navigating away.
Now we have our App registration created in Azure, and we have the following values
- TenantId
- ApplicationId
- ClientSecret
We will store these values securely in Keyfactor in subsequent steps.
Authentication has been somewhat simplified with the introduction of Azure Managed Identities. If the orchestrator is running on an Azure Virtual Machine, Managed identities allow an Azure administrator to assign a managed identity to the virtual machine that can then be used by this orchestrator extension for authentication without the need to issue or manage client secrets.
The two types of managed identities available in Azure are System assigned, and User assigned identities.
- System assigned managed identities are bound to the specific resource and not reassignable. They are bound to the resource and share the same lifecycle.
- User assigned managed identities exist as a standalone entity, independent of a resource, and can therefore be assigned to multiple Azure resources.
Read more about Azure Managed Identities here.
Detailed steps for creating a managed identity and assigning permissions can be found here.
Once the User Assigned managed identity has been created, you will need only to enter the Client Id into the Application Id field on the certificate store definition (the Client Secret can be left blank).
In order to use a System assigned managed identity, there is no need to enter the
Now we can navigate to the Keyfactor platform and create the store type for Azure Key Vault.
-
Navigate to your instance of Keyfactor and log in with a user that has Administrator privileges.
-
Click on the gear icon in the top left and navigate to "Certificate Store Types".
-
Click "Add" to open the Add Certificate Store dialog.
-
Name the new store type "Azure Keyvault" and give it the short name of "AKV".
-
The Azure Keyvault integration supports the following job types: Inventory, Add, Remove, Create and Discovery. Select from these the capabilities you would like to utilize.
-
If you are using a Service Principal or User assigned Managed Identity only Make sure that "Needs Server" is checked.
⚠️ if you are using a system assigned managed identity for authentication, you should leave this unchecked.
-
Navigate to the Advanced tab and set the following values:
- Store Path Type: Freeform
- Supports Custom Alias: Optional
- Private Key Handling: Optional
- PFX Password Style: Default
-
Navigate to the Custom Fields tab and add the following fields
Name Display Name Type Required VaultName Vault Name String true ResourceGroupName Resource Group Name String true SkuType2 SKU Type MultipleChoice false VaultRegion3 Vault Region MultipleChoice false TenantId Tenant Id String True
The process for installing an extension for the universal orchestrator differs from the process of installing an extension for the Windows orchestrator. Follow the below steps to register the Azure Keyvault integration with your instance of the universal orchestrator.
-
Stop the Universal Orchestrator service.
- Note: In Windows, this service is called "Keyfactor Orchestrator Service (Default)"
-
Create a folder in the "extensions" folder of the Universal Orchestrator installation folder named "AKV" (the name is not important)
- example: `C:\Program Files\Keyfactor\Keyfactor Orchestrator\AKV
-
Copy the build output (if you compiled from source) or the contents of the zip file (if you downloaded the pre-compiled binaries) into this folder.
-
Start the Universal Orchestrator Service
Now that we have the extension registered on the Orchestrator, we can navigate back to the Keyfactor platform and finish the setup. If there are existing Azure Key Vaults, complete the below steps to discover and add them. If there are no existing key vaults to integrate and you will be creating a new one via the Keyfactor Platform, you can skip to the next section.
-
Navigate to Orchestrators > Management in the platform.
-
Find the row corresponding to the orchestrator that we just installed the extension on.
-
If the store type has been created and the integration installed on the orchestrator, you should see the AKV capability in the list.
-
Approve the orchestrator if necessary.
-
Navigate to "Locations > Certificate Stores"
-
Click the "Discover" tab, and then the "Schedule" button.
-
You should see the form for creating the Discovery job.
⚠️ The steps for configuring discovery are different for each authentication type.
-
For System Assigned managed identity authentication this step can be skipped. No server credentials are necessary. The store type should have been set up without "needs server" checked, so the form field should not be present.
-
For User assigned managed identity:
Client Machineshould be set to the GUID of the tenant ID of the instance of Azure Keyvault.Usershould be set to the managed user ID.Passwordshould be set to the value "managed".
-
For Service principal authentication:
Client Machineshould be set to the GUID of the tenant ID of the instance of Azure Keyvault.Usershould be set to the service principal idPasswordshould be set to the client secret.
The first thing we'll need to do is store the server credentials that will be used by the extension. The combination of fields required to interact with the Azure Keyvault are:
- Tenant (or Directory) ID
- Application ID or user managed identity ID
- Client Secret (if using Service Principal Authentication)
If not using system managed identity authentication, the integration expects the above values to be included in the server credentials in the following way:
-
Client Machine:
<tenantId>(GUID) -
User:
<app id guid>(if service principal authentication)<managed user id>(if user managed identity authentication is used) -
Password:
<client secret>(if service principal authentication),managed(if user managed identity authentication is used)
Follow these steps to store the values:
-
Enter the Tenant Id in the Client Machine field.
-
Click "Change Credentials" to open up the Server Credentials form.
-
Click "UPDATE SERVER USERNAME" and Enter the appropriate values based on the authentication type.
-
Enter again to confirm, and click save.
-
Click "UPDATE SERVER PASSWORD" and update with the appropriate value (
<client secret>ormanaged) following the same steps as above. -
Select a time to run the discovery job.
⚠️ If you are using a system assigned managed identity, you will need to enter the Tenant Id value into the "Directories to Search" field.
- Leave the remaining fields blank and click "SAVE".
When the Discovery job runs successfully, it will list the existing Azure Keyvaults that are acessible by our service principal.
In this example, our job returned four Azure Keyvaults.
The store path of each vault is the Azure Resource Identifier, and contains the following information:
To add one of these results to Keyfactor as a certificate store:
-
Double-click the row that corresponds to the Azure Keyvault in the discovery results (you can also select the row and click "approve").
-
In the dialog window, enter the Vault Name and Resource Group Name from the store path value above.
-
Select a container to store the certificates for this cert store (optional)
-
Select any value for SKU Type and Vault Region. These values are not used for existing KeyVaults.
-
Click "SAVE".
You can also add a certificate store that corresponds to an Azure Keyvault individually without the need to run the discovery / approval workflow. The steps to do this are:
-
Navigate to "Locations > Certificate Stores"
-
Click "ADD"
-
Enter the values corresponding to the Azure Keyvault instance.
-
Category: Azure Keyvault
-
Container: optional
-
Client Machine: If applicable; Tenant Id.
- Note: These will only have to be entered once, even if adding multiple certificate stores.
- Follow the steps here to enter them.
-
Store Path: This is the Azure Resource Identifier for the Keyvault. Copied from Azure, or created a new Keyvault (see below).
-
VaultName: This is the name of the new or existing Azure Keyvault.
-
ResourceGroupName: The name of the Azure Resource Group that contains the Keyvault.
-
SKU Type: This field is only used when creating new vaults in Azure. Select any value, or leave blank.
-
Vault Region: This field is also only used when creating new vaults. Select any value.
If the vault already exists in azure: The store path can be found by navigating to the existing Keyvault resource in Azure and clicking "Properties" in the left menu.
If the Keyvault does not exist in Azure, and you would like to create it:
- Enter a value for the store path in the following format:
/subscriptions/{subscription id}/resourceGroups/{resource group for keyvault}/providers/Microsoft.KeyVault/vaults/{new name}
- For a non-existing Keyvault that you would like to create in Azure, make sure you have the "Create Certificate Store" box checked.
Footnotes
-
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 for vaults using Access Policy based permissions and here for Individual Key Vaults using Role-Based Access Control (RBAC). ↩
-
The SkuType determines the service tier when creating a new instance of Azure KeyVault via the platform. Valid values include "premium" and "standard". If either option should be available when creating a new KeyVault from the Command platform via creating a new certificate store, then the value to enter for the multiple choice options should be "standard,premium". If your organization requires that one or the other option should always be used, you can limit the options to a single value ("premium" or "standard"). If not selected, "standard" is used when creating a new KeyVault. ↩
-
The Vault Region field is only important when creating a new Azure KeyVault from the Command Platform. This is the region that the newly created vault will be created in. When creating the cert store type, you can limit the options to those that should be applicable to your organization. Refer to the Azure Documentation for a list of valid region names. If no value is selected, "eastus" is used by default. ↩