HaloPSA

HaloPSA Guides

Documentation to assist with the setup and configuration of the HaloPSA platform

Guides > Azure Key Vault Integration

Azure Key Vault Integration

In this guide we will cover:

- Create tickets in Halo when keys, secrets, and certificates have new versions, nearing expiry, or have expired

- Store Passwords using Azure Key Vault (v2.196+)



The Azure Key Vault integration allows you to use Azure Key Vault in combination with Azure Event Grid to create tickets in Halo when keys, secrets, and certificates have new versions created, are nearing expiry, or have expired. To set this up you need to create an event subscription with a webhook endpoint for your key vault.


 From v2.196+ you can also use the the integration to store passwords for selected integrations with Halo.


Create tickets in Halo when keys, secrets, and certificates have new versions, nearing expiry, or have expired

Enabling the Runbook

Enable the Azure Key Vault integration in Configuration > Integrations > Azure Key vault, using the '+' icon. This should automatically add a custom integration and runbook.

Fig 1. Enable integration module


You need to go to the custom runbook "Azure Key Vault" and set a username and password for the authorisation.


Make sure you make a note of the username, password, and runbook URL, as these will need to be entered into the Azure configuration.


Fig 2. Runbook configuration


Configure Event Subscription

With the Halo application now registered, you can go to Azure Key Vault to configure your event subscription.

In Azure Key Vault, go to Events and add an event subscription.


Set a name and which event types you want. By default, the 3 types of alert will trigger for all 3 Key Vault objects, but this can be adjusted.

The endpoint type needs to be set to webhook and you then need to enter the runbook URL you copied form the Halo configuration as the webhook endpoint.


Fig 3. Creating an event subscription.


The filters and additional features are not required, but can optionally be configured to restrict or customise the alerts that get triggered.


Delivery Properties

A custom header needs to be set up to authorise the webhooks. 

Add a header with name "Authorization", type "static", and set it as secret.

The value will need to be Basic followed by the Base64 encoding of your chosen username and password


For Example:

If you set them as username and password respectively, you need to Base64 encode the following: username:password

Copy the result of this encoding, which for the above is dXNlcm5hbWU6cGFzc3dvcmQ=, and into the value field enter Basic followed by the encoding. So for this example, Basic dXNlcm5hbWU6cGFzc3dvcmQ=


Fig 4. Delivery properties.


All of the inputs for this are case-sensitive, so make sure to match them exactly.


You can then save the webhook. Now you're all set up in Azure.


Store Passwords using Azure Key Vault (v2.196+)

The Azure Key Vault integration can be used to store passwords for integrations with Halo. Selected on-premise integrations that Halo requires a password to access can have this password stored in Azure Key Vault, rather than in Halo, for enhanced security. When the Halo integrator requests access to the application it can retrieve the password from Azure Key Vault. 


If an integration is compatible with Azure Key Vault, you will be able to choose the password storage method for the integration when setting up the integration. To check if an integration supports Azure Key Vault for password storage check the relevant integration setup guide.


To setup Azure Key Vault for password storage, you first need to connect a vault to Halo, head to the Azure Key Vault integration module in Halo, and select 'Configure Key Vaults' > new. 

Fig 5. Configure Azure Key Vaults


From here enter a name for the Vault in Halo, then enter the unique URL of the vault you would like to connect to. 


Now the details of the vault have been entered you will need to connect you Halo integrator to the vault, there are multiple ways that the Halo Integrator can connect to a Key Vault.


1. Using a client ID and secret stored in the appsettings.json file

When using this method you will need to register a new application in Microsoft Entra and generate a client secret for the app. Once created, navigate to the Key Vault and create an access policy for your application with the "Get" Secret permission.


Then, add the following properties to the appsettings.json file for the Halo Integrator application

  • "AzureTenantId:" "ENTER TENANT ID HERE",
  • "AzureClientId:" "ENTER CLIENT ID HERE",
  • "AzureClientSecret:" "ENTER SECRET VALUE HERE"

Fig 6. Connect using a client ID and secret stored in the appsettings.json file


2. Using a system-assigned managed identity on an Azure resource

When using this method you will need to enable system-assigned managed identity on the Azure resource that is running the Halo Integrator. Once enabled, navigate to the Key Vault and create an access policy for the resource's managed identity with the "Get" Secret permission


Fig 7. Connect using a system-assigned managed identity on an Azure resource


3. Using a user-assigned managed identity that has been associated with an Azure resource

When using this method you will need to create a user-assigned managed identity and assign it to the resource running the Halo Integrator. Once enabled, navigate to the Key Vault and create an access policy for the managed identity with the "Get" Secret permission.


Then, enter the Managed Identity Client ID you created and enter it into the integration setup page in Halo. 


Fig 8. Connect using a user-assigned managed identity that has been associated with an Azure resource


Once you have configured a Key Vault, you can select it on the corresponding integration setup screen and specify the name of the secret to be retrieved. 


Fig 9. Choose password to be stored in Azure Key vault for integration


If configured and deployed correctly, the Halo Integrator will retrieve the password from Azure Key Vault to process the integration.


Popular Guides