Background
One of the fundamental parts to BizTalk for both configuration and integration applications is Enterprise Single Sign On, or as we will continue to reference as SSO from now on.
SSO outside the bounds of BizTalk is an available service that is used to store and transmit encrypted user credentials. However, due to the nature of the service it is fairly generic, this has meant that many middleware applications and custom adapters have been designed to leverage SSO to securely store and transmit secure settings.
The SSO System holds any secure values in logical entities called Affiliate Applications. Affiliate Applications represent a system or sub-system, back-end system, or line of business application.
Looking back at BizTalk, each deployed application (Line of business application) is setup in SSO as an Affiliate Application. BizTalk uses the Affiliate Application to store internal configurations such as secure adapter data and configuration.
This post is written in mind for a BizTalk project that makes use of the
BizTalk Deployment Framework (BTDF). I would highly recommend making use of BTDF as it will assist you in conducting repeatable deployments without manual configuration and setup between environments.
BTDF when added to your BizTalk project will include a SettingsFileGenerator.xml. This file will enable you to configure environment settings that are used to tokenise your PortBindings configuration and more. Another key aspect to this file, is that you can include settings that are utilised by your integrations at run-time such as database connection strings. When you deploy your application(s) to BizTalk, the selected environment settings are deployed to the Affiliate Application in SSO. These settings are encrypted at rest, and are available from anywhere within the BizTalk group.
Problem Space
SSO is brilliant for securely storing my settings, but how would I securely get those settings there?
One of the big problems with the BizTalk Deployment Framework SettingsFileGenerator.xml is that it stores your integration environment setting values in plain text, to add to the issue, this file is usually checked into source control.
Now you might think that you would be able to tokenise the settings values and then replace them at a CI/CD level. Agreed this is one step further into secure storage and removal of these values in source control. However, this file will still then contain your secure setting values in plain text as part of a CI/CD artefact, and this file will exist on the BizTalk App box that the deployment has occurred on. So you are still no further secured.
Solution | Secure Deployment
When your BizTalk Application msi is extracted as part of a deployment (extracted onto the App Box Programs x86), the msi will have included some framework deployment tools. One of these tools is the SSOSettingsEditor.exe. This editor will allow you to specify the Affiliate Application name, of which it will then display all the currently deployed settings and values in SSO for that application. This editor will also allow you to edit such values.
Handily, this editor is backed by a DLL that has also been made available in the same folder SSOSettingsFileReader.dll. This means we can use this DLL as part of our CI/CD pipeline as a post deployment step to update values in SSO. So how do we do this?
Firstly, we will require our handy SettingsFileGenerator.xml, we still want our setting being loaded into SSO for us to update later, but don’t require the value to be the real one. It can be a dummy value, and so we don’t mind it being in plain text.
Secondly, we can use PowerShell and the SSOSettingsFileReader.dll as a Post Deployment Step. The DLL contains a set of static classes and methods of which we can make effective use of. For this use case, we will require [SSOSettingsFileManager.SSOSettingsManager]::WriteSetting. The WriteSetting method takes three parameters:
- The Affiliate Application Name | this will be the name of your project as seen in your
.btdfproj - The Setting Name | this is the name of the setting that you wish to replace it’s value.
- The New Setting Value | this is the value you wish to replace the default with.
After you have run this command, you can verify the changes have been made with the SSOSettingsEditor.exe as mentioned above.
Solution | Reading from SSO in your Integration
Let’s assume that you have an integration that will require a setting value from SSO such as a database connection string. To access this setting we can make use of the same DLL as mentioned above. There is another static class and method that will read a value from SSO:
[SSOSettingsFileManager.SSOSettingsFileReader]::ReadString
This method takes two parameters:
- The Affiliate Application Name | this will be the name of your project as seen in your
.btdfproj - The Setting Name | this is the name of the setting that you wish to retrieve.
To make such as call, you will need to:
- Add the DLL as a reference to you BizTalk Project.
- Include the DLL as a component, this is done in your
.btdfproj - Add the call to your integration as either:
- A variable in your orchestration.
- A Scripting Functoid calling the external assembly in a Map.
Conclusion
Provided both solutions, you can now specify your own secure integration settings values where these values are only stored as secure variables in your CI/CD and passed into SSO, and then read these values into your integrations straight from SSO. These secret values no longer need to live in plain text.