BizTalk Server: "appTicketTimeout": How to Set SSO Application Ticket Timeout From XML file

Article
1/17/2024

This article shows you how to use an undocumented element in the SSO Affiliate Application Definition XML File to set the ticket timeout for the application to a desired value. Without it, you must enter the value manually using the SSO Administration Console.

Enterprise Single Sign-On (SSO)

The SSO is a largely underestimated feature of BizTalk. It lets you remove the hassles with entering passwords at each deploy, or having to encrypt passwords in your binding files. You enter the password once, and then you and your DevOps team can forget about them. Also, it can be another team which is responsible for a password and your team shouldn't have a copy of it; in such a case, you let the other team walk up to your BizTalk SSO Console and let them enter the password there. Safe and sound.

If you want to read more about the SSO system, a good start is BizTalk Server: SSO Survival Guide, BizTalk: Creating SSO Affiliate Applications Using Powershell, and the official documentation at Programming Single Sign-On Overview of course.

Create an SSO Affiliate Application

You can create an SSO Affiliate Application manually by using the SSO Administration Console, or by creating an XML file and use the command-line tool ssomanage.exe. Here, we concentrate on the latter. If you are not familiar with managing SSO Affiliate Applications using ssomanage.exe, see the examples in your BizTalk installation (C:\Program Files (x86)\Microsoft BizTalk Server 2013\SDK\Samples\SSO\Manage\ and the documentation at Manage (BizTalk Server Sample).

How to Set The Application Ticket Timeout From XML file

There are many samples on the net describing how to use the ssomanage utility. Most of them build upon the sample shipped with BizTalk, and describe how you can set the application-specific ticket timeout using the SSO Administration Console.

All those sample files and descriptions lack one thing, and that is the Application-specific ticket timeout value. It is not specified in the XML Schema supplied with the SSO sample shipped with BizTalk (C:\Program Files (x86)\Microsoft BizTalk Server 2013\SDK\Samples\SSO\Manage\AffiliateApplication.xsd), and not included in any XML files present.

The Undocumented Element In The XML File

However, it is possible to set it programmatically, or from an element in the XML file.

Looking at the COM API for SSO, the API for creating an SSO Affiliate Application lacks this property (and several other properties). But there is one API method that documents this setting: The ISSOAdmin2 method UpdateApplication2: /en-us/biztalk/core/technical-reference/issoadmin2-updateapplication2-method.

Although using that official COM API with Powershell in addition to using XML files is possible, looking at the ssomanage.exe file using a text or hex viewer shows that there is something promising there: the text "appTicketTimeout" appears close to the other elements' names:

Adding The Element To The XML File

If you add an element named "appTicketTimeout" to the XML file (see example below) and run ssomanage.exe with argument -updateApps, you find that ssomanage.exe parses the element "appTicketTimeout" and uses it in the call to UpdateApplication (it seems as it's using the UpdateApplication2() method). Here's a sample SSO Affiliate Application file with the "appTicketTimeout" element added at line 11, last in the "application" element sequence:

01.<?xml version="1.0" ?>
02.<SSO>
03.  <application name="SSO-appTicketTimeout">
04.    <description>Demo Application for SSO-appTicketTimeout</description>
05.    <contact />
06.    <appUserAccount>YOURDOMAIN\BizTalk Application Users DEV</appUserAccount>
07.    <appAdminAccount>YOURDOMAIN\BizTalk Application Users DEV;YOURDOMAIN\BizTalk Server Administrators DEV;YOURDOMAIN\IntegrationTeam Admins DEV</appAdminAccount>
08.    <field ordinal="0" label="User ID" masked="no" />
09.    <field ordinal="1" label="Password" masked="yes" />
10.    <flags groupApp="yes" configStoreApp="no" allowTickets="yes" validateTickets="yes" allowLocalAccounts="no" timeoutTickets="yes" adminAccountSame="no" enableApp="yes" />
11.    <appTicketTimeout>480</appTicketTimeout>
12.  </application>
13.</SSO>

After you run ssomanage with -createApps option, the Application Ticket Timeout is still the system default:

ssomanage.exe -createApps SSO-appTicketTimeout_sso_affiliate_app.xml

But after you run ssomanage with -updateApps option, the Application Ticket Timeout is now set to the value from the XML file:

ssomanage.exe -updateApps SSO-appTicketTimeout_sso_affiliate_app.xml

You can verify this in the SSO Administration Console (right-click and choose Refresh first):

Conclusion

This concludes the missing piece in successfully administrating the SSO using scripting and XML files, as it was intended to be, without having to resort to manually edit the SSO Affiliate Application after a deployment.

Share via