BizTalk: Creating SSO Affiliate Applications Using PowerShell

Article
1/17/2024

Problem Scenario

When BizTalk wants to connect to some systems and requires the credentials to connect to them, SSO becomes the default choice where the credentials can be stored securely. In order to store the credentials as key-value pairs in the SSO database and Affiliate Application needs to be created which will map the user running the Biztalk process with the userID and the password associated with it. So when a BizTalk piece of code which implements the process of fetching data from the SSO, it becomes necessary to create the SSO affiliate applications in the SSO store before the BizTalk application is deployed on the environment. It is okay to create the affiliate applications on one environment. If the number of Environments as well as the number of applications to be created is large, it can be a cumbersome task to do the same thing.

Solution

PowerShell script can be used to consume the BizTalk out of the box SSOManage.exe to create the SSO affiliate applications. Following article addresses this problem by creating a PowerShell script which when invoked on different environments will create the SSO affiliate applications for that BizTalk environment. The PowerShell script will do following jobs

Create an SSO affiliate application and enable it.
Create the user mapping to map the BizTalk service user with the user credentials (required for the connection to an external system).
Set Credentials for the User Mapping.
Enable the User Mapping.

The SSOManage.exe requires being fed with an XML file each time it is invoked to create affiliate application or create User Mapping.
Below are the sample XML Files used to create the affiliate application and the User Mapping respectively.

<SSO>
    <application name="SSOAffiliateTestApp">
        <description>Test Application</description>
        <contact/>
        <appUserAccount>Domain\BizTalkUser</appUserAccount>
        <appAdminAccount>Domain\SSOAffiliateADminGroupName</appAdminAccount>
        <field ordinal="0" label="User ID" masked="no" />
        <field ordinal="1" label="Password" masked="yes" synchronized="yes"/>
        <flags windowsInitiatedSSO="yes" hostInitiatedSSO="yes" validatePassword="no" enableApp="yes" />
    </application>
</SSO>

Code Block 1: XML Structure To create SSO Affiliate Application

<SSO>
    <mapping>
        <windowsDomain>Domain</windowsDomain>
        <windowsUserId>BizTalkUser</windowsUserId>
        <externalApplication>SSOAffiliateTestApp</externalApplication>
        <externalUserId>userName</externalUserId>
    </mapping>
</SSO>

Code Block 2: XML Structure To create User Mapping Inside an Affiliate Application

The PowerShell script itself uses a configuration file to determine the environment where the affiliate application is to be created and the Biztalk AD user for which the Affiliate application is to be created. A sample of the configuration file is as below.

<Configuration>
  <Environment>
    <name>dev</name>
  <userName>Domain\Biztalk User</userName>
  </Environment>
  <AffiliateApplications>
    <AffiliateApplication>
      <name>SSOAffiliateTestApp</name>
    </AffiliateApplication>
    <AffiliateApplication>
      <name>SSOAffiliateTestApp1</name>
    </AffiliateApplication>
  </AffiliateApplications>
</Configuration>

Code Block3: Sample Configuration File

Now when the PowerShell Script is created, the Configuration File, the Affiliate Application Definition file, and the User Mapping File can be created for various environments at the same time.
The PowerShell Script which creates the SSO Affiliate Applications with its UserMapping is as follows:

Function CreateSSOAffiliateApplications
{
    param
     (
        #$ConfigFilePath is used to point to the path where the configuration file which determines the environment where the apps            are to be created
         $ConfigFilePath,
        #$SSoUtilityPath is used to point to the location where the SSOManage Utility is stored.
         $SSoUtilityPath,
    )

 
    if(Test-path $ConfigFilePath) 
     {
        [xml]$Config= get-content ("$ConfigFilePath \ConfigurationFile.xml")
 
        write-Host "Started"
 
 
        $Environment= $Config.Configuration.Environment.Name
        write-Host $Environment
        #Reads all the afiliate applications that are present in the configuration file
        $AffiliateApplications= $Config.Configuration.AffiliateApplications.AffiliateApplication
 
        #sets up the cmd command for the ssomanage utility
        $cmd= "$SSoUtilityPath\ssomanage.exe"
 
        #createapp argument for the ssomanage command.
        $createapp= '-createapps'
        #createmapping argument for the ssomanage command
        $createmapping= '-createmappings'
        #enablemapping argument for the ssomanage command
        $enableMapping = '-enablemapping'
        #setcredentials argument for the ssomanage command
        $setCredentials = '-setcredentials'
 
        #user against which the pointings are created in the SSO affiliate Application
        $user = $Config.Configuration.Environment.userName
        write-Host $user
 
 
        foreach($affiliateApp in  $AffiliateApplications)
         {
           Write- Host $affiliateApp.Name
           $appName= $affiliateApp.Name
 
           # Following variables point to the location of the xmls containing the Affiliate application structure
           # and the user mapping xml structure. The Locations vary in nature depending upon the environment configured in the                  configuration xml file.
           $AffiliateAppXml = "$ConfigFilePath\SSOConfigFiles\ $appName"+"_AffiliateApplication.xml"
           $UserMappingXml = "$ConfigFilePath\SSOConfigFiles\ $appName" + "_UserMappings.xml"
           write- Host $AffiliateAppXml
           write- host $UserMappingXml
 
           #Following commands are used to CreateAffiliate App, CreateMapping, Setting Mapping Credentials and Enabling the                        mapping respectively.
           #NOTE: The user of this script will be prompted to enter and then confirm the password in the cmd dialog screen when                    the script is executed.
 
           & $cmd $createapp $AffiliateAppXml
           & $cmd $createmapping $UserMappingXml
           & $cmd $setCredentials $user $appName
           & $cmd $enableMapping $user $appName
  
        } 
 
    } 
    else
     {
        write-host "Invalid File Path Specified"
    } 
 
}

Code Block4: PowerShell Script To Create the SSO Affiliate Applications and UserMappings

Setting Up The Script

In order to run the script on multiple environments, Administrators need to create the necessary File Structure before execution. Follow the below Steps to create the Necessary Structure

Create a Folder Named CreateAffiliateApplications
Inside CreateAffiliateApplications folder create the ConfigurationFile.xml as shown in Code Block 3
Inside CreateAffiliateApplications create following Folders: SSOConfigFiles
Create Affiliate Application Definition file as per Code Block 1 and naming convention: <ApplicationName>_AffiliateApplication.xml . e.g. TestSSOApp_AffiliateApplication.xml
Create the User Mapping Definition file as per Code Block 2 and naming convention: <applicationName>_UserMappings.xml e.g. TestSSOApp_UserMappings.xml
Change the details in the files as per the environment.
Save the PowerShell script with name: CreateAffiliateApplicationsAndUserMappings.ps1
Create the Batch File as shown below to execute the PowerShell Script.

@echo off
 
Powershell.exe "<Path>\CreateAffiliateApplications \CreateAffiliateApplicationsAndUserMappings.ps1" CreateSSOAffiliateApplications - ConfigFilePath '<Path>\CreateAffiliateApplications' - SSoUtilityPath '<path Where the SSO is installed'
 
pause

9. Running the Batch File will execute the PowerShell Script and create the necessary SSO Affiliate Applications and User Mappings inside the SSO Affiliate Applications.

Share via

BizTalk: Creating SSO Affiliate Applications Using PowerShell

Problem Scenario

Solution

Setting Up The Script

See Also

Additional resources