Azure Key Vault Orchestrator

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.

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

About the Keyfactor Universal Orchestrator Extension

This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” — collections of certificates and roots of trust that are found within and used by various applications.

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.

Support for Azure Key Vault Orchestrator

Azure Key Vault Orchestrator is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com

To report a problem or suggest a new feature, use the Issues tab. If you want to contribute actual bug fixes or proposed enhancements, use the Pull requests tab.

---

---

Keyfactor Version Supported

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 Reenrollment
Supports Inventory	✓	✓

PAM Integration

This orchestrator extension has the ability to connect to a variety of supported PAM providers to allow for the retrieval of various client hosted secrets right from the orchestrator server itself. This eliminates the need to set up the PAM integration on Keyfactor Command which may be in an environment that the client does not want to have access to their PAM provider.

The secrets that this orchestrator extension supports for use with a PAM Provider are:

Name	Description
Server Username	The application (service principal) ID that will be used to authenticate to Azure
Server Password	The client secret that will be used to authenticate into Azure

It is not necessary to use a PAM Provider for all of the secrets available above. If a PAM Provider should not be used, simply enter in the actual value to be used, as normal.

If a PAM Provider will be used for one of the fields above, start by referencing the Keyfactor Integration Catalog. The GitHub repo for the PAM Provider to be used contains important information such as the format of the json needed. What follows is an example but does not reflect the json values for all PAM Providers as they have different "instance" and "initialization" parameter names and values.

General PAM Provider Configuration

Example PAM Provider Setup

To use a PAM Provider to resolve a field, in this example the Server Password will be resolved by the Hashicorp-Vault provider, first install the PAM Provider extension from the Keyfactor Integration Catalog on the Universal Orchestrator.

Next, complete configuration of the PAM Provider on the UO by editing the manifest.json of the PAM Provider (e.g. located at extensions/Hashicorp-Vault/manifest.json). The "initialization" parameters need to be entered here:

  "Keyfactor:PAMProviders:Hashicorp-Vault:InitializationInfo": {
    "Host": "http://127.0.0.1:8200",
    "Path": "v1/secret/data",
    "Token": "xxxxxx"
  }

After these values are entered, the Orchestrator needs to be restarted to pick up the configuration. Now the PAM Provider can be used on other Orchestrator Extensions.

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 for the specific format of the json object.

To have the Server Password field resolved by the Hashicorp-Vault provider, the corresponding json object from the Hashicorp-Vault extension needs to be copied and filed in with the correct information:

{"Secret":"my-kv-secret","Key":"myServerPassword"}

This text would be entered in as the value for the Server Password, instead of entering in the actual password. The Orchestrator will attempt to use the PAM Provider to retrieve the Server Password. If PAM should not be used, just directly enter in the value for the field.

---

Setup and Configuration

The high level steps required to configure the Azure Keyvault Orchestrator extension are:

1. Migrating from the Windows Orchestrator for Azure KeyVault

2. Configure the Azure Keyvault for client access

3. Create the Store Type in Keyfactor

4. Install the Extension on the Orchestrator

5. Create the Certificate Store

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.

Migrating from the Windows Orchestrator for Azure KeyVault

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 should still manage other cert store types

If the Windows Orchestrator will still be used to manage some store types, we will remove only the Azure Keyvault functionality.

1. On the Windows Orchestrator host machine, run the Keyfactor Agent Configuration Wizard

2. Proceed through the steps to "Select Features"

3. Expand "Cert Stores" and un-check "Azure Keyvault"

4. Click "Apply Configuration"

5. Open the Keyfactor Platform and navigate to Orchestrators > Management

6. Confirm that "AKV" no longer appears under "Capabilities"

7. Navigate to Orchestrators > Management, select the orchestrator and click "DISAPPROVE" to disapprove it and cancel pending jobs.

8. Navigate to Locations > Certificate Stores

9. Select any stores with the Category "Azure Keyvault" and click "DELETE" to remove them from Keyfactor.

10. Navigate to the Administrative menu (gear icon) and then > Certificate Store Types

11. Select Azure Keyvault, click "DELETE" and confirm.

12. Navigate to Orchestrators > Management, select the orchestrator and click "APPROVE" to re-approve it for use.

13. Repeat these steps for any other Windows Orchestrators that support the AKV store type.

If the Windows Orchestrator can be retired completely

If the Windows Orchestrator is being completely replaced with the Universal Orchestrator, we can remove all associated stores and jobs.

1. Navigate to Orchestrators > Management and select the Windows Orchestrator from the list.
2. With the orchestrator selected, click the "RESET" button at the top of the list
3. Make sure the orchestrator is still selected, and click "DISAPPROVE".
4. Click "OK" to confirm that you will remove all jobs and certificate stores associated to this orchestrator.
5. Navigate to the the Administrative (gear icon in the top right) and then Certificate Store Types
6. Select "Azure Keyvault", click "DELETE" and confirm.
7. 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.

Migrating from version 1.x or version 2.x of the Azure Keyvault Orchestrator Extension

It is not necessary to re-create all of the certificate stores when migrating from a previous version of this extension, though it is important to note that Azure KeyVaults found during a Discovery job will return with latest store path format: {subscription id}:{resource group name}:{new vault name}.

---

Configure the Azure Keyvault for client access

In order for this orchestrator extension to be able to interact with your instances of Azure Keyvault, it will need to authenticate with a identity that has sufficient permissions to perform the jobs. Microsoft Azure implements both Role Based Access Control (RBAC) and the classic Access Policy method. RBAC is the preferred method, as it allows the assignment of granular level, inheretable access control on both the contents of the KeyVaults, as well as higher-level management operations. For more information and a comparison of the two access control strategies, refer to this article.

RBAC vs Access Policies

Azure KeyVaults originally utilized access policies for permissions and since then, Microsoft has begun recommending Role Based Access Control (RBAC) as the preferred method of authorization.
As of this version, new KeyVaults created via this integration are created with Access Policy authorization. This will change to RBAC in the next release. The access control type the KeyVault implements can be changed in the KeyVault configuration within the Azure Portal. New KeyVaults created via Keyfactor by way of this integration will be accessible for subsequent actions regardless of the access control type.

Configure Role Based Access Control (RBAC)

In order to illustrate the minimum permissions that the authenticating entity (service principal or managed identity) requires, we have created 3 seperate custom role definitions that you can use as a reference when creating an RBAC role definition in your Azure environment.

The reason for 3 definitions is that certain orchestrator jobs, such as Create (new KeyVault) or Discovery require more elevated permissions at a different scope than the basic certificate operations (Inventory, Add, Remove) performed within a specific KeyVault.

If you know that you will utilize all of the capabilities of this integration; the last custom role definition contains all necessary permissions for performing all of the Jobs (Discovery, Create KeyVault, Inventory/Add/Remove certificates).

Built-in vs. custom roles

⚠️ The custom role definitions below are designed to contain the absolute minimum permissions required. They are not intended to be used verbatim without consulting your organization's security team and/or Azure Administrator. Keyfactor does not provide consulting on internal security practices.

It is possible to use the built-in roles provided by Microsoft for these operations. The built-in roles may contain more permissions than necessary. Whether to create custom role definitions or use an existing or pre-built role will depend on your organization's securuity requirements.
For each job type performed by this orchestrator, we've included the minimally sufficient built-in role name(s) along with our custom role definitions that limit permissions to the specific actions and scopes necessary.

Create Vault permissions

In order to allow for the ability to create new Azure KeyVaults from within command, here is a role that defines the necessary permissions to do so. If you will never be creating new Azure KeyVaults from within Command, then it is unnecessary to provide the authenticating entity with these permissions.

⚠️ When creating a new KeyVault, we grant the creating entity the built-in "Key Vault Certificates Officer" role in order to be able to perform subsequent actions on the contents of the KeyVault. click here to see the list of permissions included in the Key Vault Certificates Officer built-in role.

• built-in roles (both are required):

  • "Key Vault Contributor"
  • "Key Vault Access Administrator"

• lowest level scope required - a resource group that will contain the new KeyVault.

• condition:

"((!(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})) OR (@Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals{a4417e6f-fecd-4de8-b567-7b0420556985})) AND ((!(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})) OR (@Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals{a4417e6f-fecd-4de8-b567-7b0420556985}))"

the above condition limits the ability to assign roles to a single role only (Key Vault Certificates Officer). This is more restrictive than the condition on the built-in role of Key Vault Access Administrator.

• custom role definition:

{
    "properties": {
        "roleName": "KeyfactorVaultCreator",
        "description": "This role contains all of the necessary permissions to perform Inventory, Add and Remove operations on certificates on All KeyVaults within a Resource Group.  It also contains sufficient permissions to create a new KeyVault within the resource group.",
        "assignableScopes": [
          "/subscriptions/{subscriptionId1}", // allow to be applied to a specific subscription
          "/subscriptions/{subscriptionId2}", // and another.. etc.
          "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}", // allow to be scoped to a specific resource group
          "/subscriptions/{subscriptionId2}/resourcegroups/{resourceGroupName2}", // and another.. 
          "/providers/Microsoft.Management/managementGroups/{groupId1}" // allow to be applied for all subscriptions under management group           
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.KeyVault/vaults/*",
                    "Microsoft.Authorization/*/read",                                        
                    "Microsoft.KeyVault/register/action",                    
                    "Microsoft.KeyVault/checkNameAvailability/read",
                    "Microsoft.KeyVault/vaults/accessPolicies/*",
                    "Microsoft.Resources/deployments/*",
                    "Microsoft.KeyVault/locations/*/read",
                    "Microsoft.Resources/subscriptions/resourceGroups/read",
                    "Microsoft.Management/managementGroups/read",
                    "Microsoft.Resources/subscriptions/read",
                    "Microsoft.Authorization/roleAssignments/*",                     
                    "Microsoft.KeyVault/operations/read"                    
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": [],
                "conditionVersion": "2.0",
                "condition": "((!(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})) OR (@Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals{a4417e6f-fecd-4de8-b567-7b0420556985})) AND ((!(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})) OR (@Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals{a4417e6f-fecd-4de8-b567-7b0420556985}))"
            }
        ]
    }
}

Discover Vaults Permissions

If you would like this integration to search across your subscriptions to discover instances of existing Azure KeyVaults, this role definition contains the necessary permissions for this. If you are working with a smaller number of KeyVaults and/or do not plan on utilizing a Discovery job to retrieve all KeyVaults across your subscriptions, the permissions defined in this role are not necessary.

• built-in role: "Key Vault Reader"
• lowest level scope - a resource group
• custom role definition:

{
    "properties": {
        "roleName": "KeyfactorVaultDiscovery",
        "description": "This role contains all of the necessary permissions to search for KeyVaults across a subscription",
        "assignableScopes": [
          "/subscriptions/{subscriptionId1}", // allow to be applied to a specific subscription
          "/subscriptions/{subscriptionId2}", // and another.. etc.
          "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}", // allow to be scoped to a specific resource group
          "/subscriptions/{subscriptionId2}/resourcegroups/{resourceGroupName2}", // and another.. 
          "/providers/Microsoft.Management/managementGroups/{groupId1}" // allow to be applied for all resources under management group           
        ],
        "permissions": [
            {
              "actions": [
                "Microsoft.Authorization/*/read",
                "Microsoft.Resources/subscriptions/resourceGroups/read",
                "Microsoft.KeyVault/checkNameAvailability/read",
                "Microsoft.KeyVault/locations/*/read",
                "Microsoft.KeyVault/vaults/read",
                "Microsoft.KeyVault/operations/read"
               ],
               "notActions": [],
               "dataActions": [        
               ],
               "notDataActions": [],  
             }
          ]
    }
}

Inventory, Add, and Remove Certificate Permissions

This set of permissions is the minimum required to support the basic operations of performing an Inventory and Add/Removal of certificates.

• built-in role: "Key Vault Certificates Officer"
• lowest level scope - an individual keyvault
• custom role definition:

{
    "properties": {
        "roleName": "KeyfactorManageCerts",
        "description": "This role contains all of the necessary permissions to perform Inventory, Add and Remove operations on certificates on All KeyVaults within the scope.",
        "assignableScopes": [
          "/providers/Microsoft.Management/managementGroups/{groupId1}", // allow scope for all subscriptions under management group
          "/subscriptions/{subscriptionId}", // allow to scoped to a specific subscription
          "/subscriptions/{subscriptionId2}", // and another.. etc.
          "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}", // allow to be scoped to a specific resource group
          "/subscriptions/{subscriptionId2}/resourcegroups/{resourceGroupName2}", // and another..               
          "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/vaults/{vaultName}", // allow scope to a specific vault
          "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroupName2}/providers/Microsoft.KeyVault/vaults/{vaultName2}", // .. and another
        ],
         "permissions": [
           {
             "actions": [
               "Microsoft.Authorization/*/read",
               "Microsoft.Resources/deployments/*",
               "Microsoft.Resources/subscriptions/resourceGroups/read",
               "Microsoft.KeyVault/checkNameAvailability/read",
               "Microsoft.KeyVault/locations/*/read",
               "Microsoft.KeyVault/vaults/*/read",
               "Microsoft.KeyVault/operations/read",               
             ],
             "notActions": [],
             "dataActions": [
               "Microsoft.KeyVault/vaults/certificates/*",
               "Microsoft.KeyVault/vaults/certificatecas/*",
               "Microsoft.KeyVault/vaults/keys/*",
               "Microsoft.KeyVault/vaults/secrets/readMetadata/action"
             ],
             "notDataActions": []
           }
    ],
  }
}

Combined permissions for all operations (Create, Discovery, Inventory, Add and Remove certificates)

This section defines a single custom role that contains the necessary permissions to perform all operations allowed by this integration. The minimum scope allowable is an individual resource group. If this custom role is associated with the authenticating identity, it will be able to discover existing KeyVaults, Create new ones, and perform inventory as well as adding and removing certificates within the KeyVault.

• minimally sufficient built-in roles (all are required):
  • "Key Vault Certificates Officer"
  • "Key Vault Contributor"
  • "Key Vault Access Administrator"
• lowest level scope - an individual resource group
• custom role definition:

{
    "properties": {
        "roleName": "KeyfactorKeyVaultOperations",
        "description": "This role contains all of the necessary permissions to perform Discovery, Create, Inventory, Add and Remove operations on certificates on All KeyVaults within The scope.",
        "assignableScopes": [
          "/subscriptions/{subscriptionId1}", // allow to be applied to a specific subscription
          "/subscriptions/{subscriptionId2}", // and another.. etc.
          "/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}", // allow to be scoped to a specific resource group
          "/subscriptions/{subscriptionId2}/resourcegroups/{resourceGroupName2}", // and another.. 
          "/providers/Microsoft.Management/managementGroups/{groupId1}" // allow to be applied for all subscriptions under management group           
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.KeyVault/vaults/*",
                    "Microsoft.Authorization/*/read",                                        
                    "Microsoft.KeyVault/register/action",                    
                    "Microsoft.KeyVault/checkNameAvailability/read",
                    "Microsoft.KeyVault/vaults/accessPolicies/*",
                    "Microsoft.Resources/deployments/*",
                    "Microsoft.Resources/subscriptions/resourceGroups/read",
                    "Microsoft.Management/managementGroups/read",
                    "Microsoft.Resources/subscriptions/read",
                    "Microsoft.Authorization/roleAssignments/*",                     
                    "Microsoft.KeyVault/operations/read"                                
                    "Microsoft.KeyVault/locations/*/read",
                    "Microsoft.KeyVault/vaults/*/read",
                ],
                "notActions": [],
                "dataActions": [
                   "Microsoft.KeyVault/vaults/certificates/*",
                   "Microsoft.KeyVault/vaults/certificatecas/*",
                   "Microsoft.KeyVault/vaults/keys/*",
                   "Microsoft.KeyVault/vaults/secrets/*"
             ],
                "notDataActions": [],
                "conditionVersion": "2.0",
                "condition": "((!(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})) OR (@Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals{a4417e6f-fecd-4de8-b567-7b0420556985})) AND ((!(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})) OR (@Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals{a4417e6f-fecd-4de8-b567-7b0420556985}))"
            }
        ]
    }
}

⚠️ You still may decide to split the capabilities into seperate roles in order to apply each of them to the lowest level scope required. We have tried to provide you with an absolute minimum set of required permissions necessary to perform each operation. Refer to your organization's security policies and/or consult with your information security team in order to determine which role combinations would be most appropriate for your needs.

Endpoint Access / Firewall

At a minimum, the orchestrator needs access to the following URLs:

• The instance of Keyfactor Command
• 'login.microsoftonline.com' (or the endpoint corresponding to the Azure Global Cloud instance (Government, China, Germany).
  • this is only technically necessary if they are using Service Principal authentication.
• 'management.azure.com' for all management operations (Create, Add, Remove) as well as Discovery.
  • This is necessary for authenticating the ARM client used to perform these operations.

Any firewall applied to the orchestrator host will need to be configured to allow access to these endpoints in order for this integration to make the necessary API requests.

⚠️ Discovery jobs are not supported for KeyVaults located outside of the Azure Public cloud or Keyvaults accessed via a private url endpoint.
All other job types implemented by this integration are supported for alternate Azure clouds and private endpoints.

Authentication options

The Azure KeyVault orchestrator plugin supports several authentication options:

• Service Principal
• User Assigned Managed Identities
• System Assigned Managed Identities

Steps for setting up each option are detailed below.

Authentication via Service Principal

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:

1. Create a Service Principal in Azure Active Directory

2. Assign it sufficient permissions for Keyvault operations

3. Generate an Access Token for Authenticating

4. Store the server credentials in Keyfactor

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.

Create A Service Principal

Note: In order to manage key vaults in multiple Azure tenants using a single service principal, the supported account types option selected should be: Accounts in any organizational directory (Any Azure AD directory - Multitenant). Also, the app registration must be registered in a single tenant, but a service principal must be created in each tenant tied to the app registration. For more info review the Microsoft documentation.

For detailed instructions on how to create a service principal in Azure, see here.

Once we have our App registration created in Azure, record the following values

• TenantId
• ApplicationId
• ClientSecret

We will store these values securely in Keyfactor in subsequent steps.

Authentication via User Assigned Managed Identity

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).

Authentication via System Assigned Managed Identity

In order to use a _System_ assigned managed identity, there is no need to enter the server credentials. If no server credentials are provided, the extension assumes authentication is via system assigned managed identity.

Create the Store Type in Keyfactor

Now we can navigate to the Keyfactor platform and create the store type for Azure Key Vault.

1. Navigate to your instance of Keyfactor and log in with a user that has Administrator privileges.

2. Click on the gear icon in the top left and navigate to "Certificate Store Types".

   

3. Click "Add" to open the Add Certificate Store dialog.

4. Name the new store type "Azure Keyvault" and give it the short name of "AKV".

5. 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.

⚠️ The store type definition needs to include the necessary fields to support Create functionality (SkuType and VaultRegion). Be sure to read through the Custom Fields instructions below and set them up with the required fields if Creating new Azure Keyvaults from Keyfactor Command is desired.

1. 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.

1. 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

   

2. Navigate to the Custom Fields tab and add the custom fields for the store type.

⚠️ If you are using the Global Public cloud (*.vault.azure.net) and creating new Azure Keyvaults from Keyfactor Command functionality is not necessary for your workflow, this section can be skipped entirely.

• The below two fields are necessary if working with Keyvaults in Azure Cloud instances that are not the standard global public one (*.vault.azure.net) If your vault instance(s) have the base url of .vault.azure.net then the next two fields can be omitted from the store type definition and the default global public cloud will be assumed.
• • The "Azure Cloud" field refers to

Name	Display Name	Type	Required
AzureCloud1	Azure Cloud	MultipleChoice	false
PrivateEndpoint2	Private Endpoint	String	false

• The following fields are only necessary in order to support creating new Azure Keyvaults from the Keyfactor Command platform. If this functionality is not needed, there is no need to set up these fields.

Name	Display Name	Type	Required
TenantId	Tenant Id	String	false
SkuType3	SKU Type	MultipleChoice	false
VaultRegion4	Vault Region	MultipleChoice	false

Install the Extension on the Orchestrator

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.

1. Stop the Universal Orchestrator service.

   1. Note: In Windows, this service is called "Keyfactor Orchestrator Service (Default)"

2. Create a folder in the "extensions" folder of the Universal Orchestrator installation folder named "AKV" (the name is not important)

   1. example: `C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions_AKV_

3. 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.

4. Start the Universal Orchestrator Service

Discover Certificate Stores

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.

1. Navigate to Orchestrators > Management in the platform.

   

2. Find the row corresponding to the orchestrator that we just installed the extension on.

3. If the store type has been created and the integration installed on the orchestrator, you should see the AKV capability in the list.

   

4. Approve the orchestrator if necessary.

Create the discovery job

1. Navigate to "Locations > Certificate Stores"

   

2. Click the "Discover" tab, and then the "Schedule" button.

   

3. You should see the form for creating the Discovery job.

   

Store the Server Credentials in Keyfactor

⚠️ 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 Machine should be set to the GUID of the tenant ID of the instance of Azure Keyvault.
  • User should be set to the Client ID of the managed identity.
  • Password should be set to the value "managed".

• For Service principal authentication:

  • Client Machine should be set to the GUID of the tenant ID of the instance of Azure Keyvault. Note: If using a multi-tenant app registration, use the tenant ID of the Azure tenant where the key vault lives.
  • User should be set to the service principal id
  • Password should 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:

1. Enter the Tenant Id in the Client Machine field.

   

2. Click "Change Credentials" to open up the Server Credentials form.

   

3. Click "UPDATE SERVER USERNAME" and Enter the appropriate values based on the authentication type.

   

4. Enter again to confirm, and click save.

5. Click "UPDATE SERVER PASSWORD" and update with the appropriate value (<client secret> or managed) following the same steps as above.

6. Select a time to run the discovery job.

7. Enter commma seperated list of tenant ID's in the "Directories to search" field.'

⚠️ If nothing is entered here, the default Tenant ID included with the credentials will be used. For system managed identities, it is necessary to include the Tenant ID(s) in this field.

1. Leave the remaining fields blank and click "SAVE".

Approve the Certificate Store

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 these Azure Keyvaults.

The store path of each vault is the <subscription id>:<resource group name>:<vault name>:

To add one of these results to Keyfactor as a certificate store:

1. Double-click the row that corresponds to the Azure Keyvault in the discovery results (you can also select the row and click "SAVE").

2. In the dialog window, enter values for any of the optional fields you have set up for your store type.

3. Select a container to store the certificates for this cert store (optional)

4. Select any value for SKU Type and Vault Region. These values are not used for existing KeyVaults.

5. Click "SAVE".

Add a new or existing Azure Keyvault certificate store

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:

1. Navigate to "Locations > Certificate Stores"

2. Click "ADD"

   

3. 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 Subscription ID, Resource Group name, and Vault name in the following format: {subscription id}:{resource group name}:{new vault name}

• SKU Type: This field is only used when creating new vaults in Azure. If present, select any value, or leave blank.

• Vault Region: This field is also only used when creating new vaults. If present, 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.

• Use these values to create the store path

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: {subscription id}:{resource group name}:{new vault name}

• For a non-existing Keyvault that you would like to create in Azure, make sure you have the "Create Certificate Store" box checked.

⚠️ The identity you are using for authentication will need to have sufficient Azure permissions to be able to create new Keyvaults.

---

License

Apache

When creating cert store type manually, that store property names and entry parameter names are case sensitive

Footnotes

1. The Azure Cloud field, if necessary, should contain one of the following values: "china, germany, government". This is the Azure Cloud instance your organization uses. If using the standard "public" cloud, this field can be left blank or omitted entirely from the store type definition. ↩

2. The Private Endpoint field should be used if you if have a custom url assigned to your keyvault resources and they are not accessible via the standard endpoint associated with the Azure Cloud instance (*.vault.azure.net, *.vault.azure.cn, etc.). This field should contain the base url for your vault instance(s), excluding the vault name. ↩

3. 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. ↩

4. 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. ↩