HL7 Soup

Using the Azure Key Vault to store Global Variables is a great way to provide passwords and connection strings in your workflows securely, stored in a secure place.

Here we describe how to set up your Key Vault to allow Integration Host simple access to the secrets via Managed identities using Service Principal security. Perhaps better described as – Tell the Vault to trust the App Service or VM running Integration Host.

I’ll assume that you already have a VM Hosted in Azure or are running the Integration Host App Service (available in the Azure Marketplace) and have already created an Azure Key Vault.

We’ll add a database connection string into vault secrets for this tutorial, then use this in Integration Host for both Message Logs and Database Readers.

Create you secret

1. From the Azure Key Vault, Secrets, Click Generate/Import

2. Create your secret with a suitable name. The name you use here will need to be the same name used in Integration Host Global Variables later.

Grant Integration Host permission to read the certificate

1. First, we need to get the Principal ID of your VM or App Service running Integration Host. Navigate to this in the Portal, and select the Identity tab.

Ensure that the Status is “On”, and copy the Object (principal) ID to the clipboard.

2. Head back to the Vault, and navigate to Access Policies

3. Click Add Access Policy

4. You don’t need to use a template, just set Secret Permission to “Get”. Note if you are following this to access a certificate, you’ll need “Get” and “List” on Secrets as well as “Get” on Certificates

5. Select Principal by clicking the “None Selected” link. The Principal dialog will open. Paste in the Principal ID you copied earlier. Your VM or App Service will be listed. Select it, and then click Select down the bottom.

6. Click “Add”.

7. Then click “Save” up the top. Don’t miss this step! I have wasted enough time myself that it’s worth stressing this step.

Configure Integration Host

1. In the Vault, navigate to the Overview tab, and copy the Vault URI to your clipboard.

2. Open the Integration Host Client application, and click the HL7 Soup Icon on the top left to open the settings

3. Navigate to the Global Variables tab, and paste the Vault URI into the Azure Vault URL textbox.

4. Click Add to create a new Global Variable. Set the variable name to exactly match the secret name you created earlier in the Vault. Set the Storage Location to AzureVault.

5. Click OK to create the global variable and connection. Note: You must click OK to create the global variable before using it on another settings tab.

Using the Global Variable

Your newly created global variable is now available throughout the Integration Host system. Any textbox that accepts global variables will provide a right-click menu option for insertion.

For instance, you can use your connection string global variable in the Message Logs settings as the connection string for the database.

The global variable is wrapped in a ${} for identification and is replaced with the secret value when processed. Notably, the variable can be mixed with fixed text or even multiple global variables. This allows, for instance, only storing the database password in the Vault while the rest of the connection string is available for editing.

E.G. Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=${myPassword};

Workflows provide an even richer environment for using global variables. Variables can be inserted from the right-click menu or the Variables Binding Source.

Updating Vault Values

Integration Host or workflows cannot update values stored in the Vault, including setting the global variable in transformers.

The only way to alter the values in the Vault is to add a new version of the secret. Do this in the Portal by selecting your secret and clicking the “Add New Version” link. You can then update the value. Click “Create”, and then also click “Save”!

Suppose your Global Variable is configured to cache the value. You will need to either restart the Integration Host service or turn off the cache until the value is updated.

Security Administrators

Important Note: Having the ability to insert passwords into a message body is essential for certain message types, e.g. web services. However, this means that inserting the password into the outbound data of the message is also possible. While the values in the Vault are not stored on the file system, we strongly suggest you restrict and lock all access to the file system and Integration Host UI to trusted users.

Download HL7 Soup and Integration Host from our downloads page.

Return to Tutorials Directory