Enterprise single sign-on (SSO) is an integral part of BizTalk. BizTalk relies on Enterprise Single Sign-On for the following purposes 

  • to act as a secure configuration store for adapters, port transport data etc.
  • to enable single sign-on by mapping windows credentials to and from external system credentials, including password synchronisation.

Key concepts

Enterprise SSO System

The enterprise SSO system consists of

  • The SSO database:
    This database stores credentials and configuration, encrypted using a secret key.


  • The master secret SSO server.
    This is the only SSO server that has a persisted copy of the secret key used to encrypt/decrypt data in the SSO database. This SSO server generates a master secret key, during initial configuration and whenever an SSO admin requests a key change, and distributes it to the other SSO servers in the system. Accordingly, this server is known as the name master secret server.


  • SSO server
    All SSO services, including the SSO service on the master secret server, can map user accounts between windows and backend systems through SSO tickets.  
    They also perform password synchronization to sync passwords across systems.

Affiliate Application

Affiliate applications represent a logical system such as a host, back-end system, or line of business application to which you can connect to or just store configuration related to the system.
There are two types of affiliate application .

  • SSO application
    This type of application is a typical use case for SSO, to provide single sign-on by mapping credentials between systems. The SSO service maps user credentials from one system to the other through SSO Tickets.


  • Config store application
    This type of application is used to store any configuration in the form of key value pairs. BizTalk uses this type of application to store adapter, port transport data configuration etc, which means that BizTalk cannot function if the SSO service isn’t available. This is why SSO is so critical to BizTalk even if you are not using any single sign-on features.

SSO Tickets

In order to transfer a user's security context across process and machine boundaries,  the SSO service issues an SSO ticket when a BizTalk host requests one.  The SSO ticket contains the user name of the end user, timestamp with the the ticket contents are encrypted.   In order to provide single sign-on,  the SSO service needs to map the user account / group from the source system to a destination system configured at the send port and retrieve the corresponding userid /passwords to connect the destination system.  This process of retrieving the destination system credentials by the SSO service is called redeeming an SSO ticket.

How BizTalk and Enterprise SSO work together

  1. The SSO Service is installed on every computer that is part of the BizTalk hosts group.
  2. The master secret SSO stores the only persisted copy of the secret key used to encrypt the values in the SSO database. The persisted secret key, stored in the windows registry, is also encrypted using the credentials used to run the master secret SSO service via a key protection algorithm such as windows data protection API (DPAPI). This means that if you change the account used to run the SSO service or change the SSO master secret server,  SSO service will no longer be able to decrypt the secret key unless you restore a backup of the secret key. This is why it is really important to take a backup of the secret key.
  3. Every other SSO server periodically queries the master secret server for the latest secret key and also holds an in-memory cache of the key. This allows the SSO service to operate even when the master secret SSO service is not available as long the cached version of the key is valid. However it will not be able to make changes to the SSO application if the master secret server is down. Also note that this is an in-memory cache, so if you restart the SSO service during the time the master secret server is down it will not have a copy of the secret key and it will fail.
  4. The BizTalk administrator console also relies on SSO service to display and update port transport data. You can view the transport configuration as long as one of the SSO servers are available (provided the SSO service has cached copy of the secret key), but can only update configuration when the master secret SSO server is available.


BizTalk and SSO Tickets

Now, if you want to use Enterprise SSO to actually provide Single Sign-On instead of acting just as a secure config store for BizTalk, you have to know how the SSO tickets work.  The figure below shows how the various components within BizTalk work to issue and redeem SSO tickets.

  1. First, you must enable the option to issue SSO tickets on a SSO server, using SSOManage.exe, without which you cannot use single sign-on features.
  2. For BizTalk to request SSO tickets, the application connecting to BizTalk MUST be authenticated as the host needs to impersonate as that user. For instance, if your BizTalk http receive uses anonymous authentication no requests for SSO tickets will be made as there is no user to "impersonate". The alternative option is to write custom code, either as a pipeline component , orchestration etc to request for SSO tickets (via ISSOTicket interface) and write the ticket into the message context property.
  3. When BizTalk obtains the SSO ticket, the ticket is written into the message context property "SSOTicket", namespace
  4. Finally the issue of a trusted host. If the BizTalk host configured in the handler is not trusted, when a message is persisted the message box overwrites the OriginatorSID message context property with the BizTalk service account id.  When an SSO ticket needs to be redeemed ( aka retrieve corresponding backend credentials) the SSO Service cross checks the username in the encrypted ticket and the "sender" (BizTalk passes the OrginatorSID as the sender) and if they do not match, the  ticket cannot be redeemed.  

The table below shows some of the key properties of an affiliate application

Property Description
Application name Name of the Affiliate Application.
Description Brief description
Contact information The main contact for this application
Application Users Account The Windows group that contains the user accounts of end users who will be using this Affiliate Application
Affiliate Administrators Account The Windows group that contains the Administrator accounts that will manage this Affiliate Application.
Application enabled (Yes/No flag) The status of this Affiliate Application ( enabled / disabled)
Configuration Store application (Yes/No flag) Determines whether this Affiliate Application is a Configuration Store type application (Yes) or an SSO type application.
Group Application (Yes/No flag) Set to yes if this application supports mappings between one Windows group to another system user account. By default, an SSO type application is an ”Individual”, which means you can only map between user accounts and not from groups to user accounts.
Host Group application (Yes/No flag) This is the reverse of the group application, and indicates if you can map from a Host system (e.g. mainframe) group to a windows credential
Host Initiated SSO (Yes/No flag) Enable this if it is a Host Initiated SSO type application, which is used to map Host System (e.g. mainframe) credentials to windows credentials
Windows Initiated SSO (Yes/No flag) Enable this if it is a Windows Initiated SSO type application. This flag is enabled to map from windows credentials to another system.

The table below shows the security groups used by SSO

SSO Group Accounts Single Sign-On Application Type Configuration Store Application Type
SSO Administrators Manage the SSO system.

All SSO Services need to run as under the SSO Administrator account.
SSO system level administrator operations.
SSO Affiliate Administrators Create Affiliate Applications. Create Affiliate Applications.
Application Administrators
Create, delete, and manage mappings and setting credentials for the specific affiliate application
Can read and write configuration data for the specific affiliate application
Application Users Members of this account are end users that can access the back-end application with the appropriate back-end accounts.

You create SSO credential mappings for members of this group for a specific Affiliate Application.
Can read configuration data.
The BizTalk Server Runtime Service account needs to be a member of the appropriate Application User account to retrieve this configuration data.


Tools to manage SSO

  1. SSO Administration Microsoft Management Console (MMC) provides the following functions:
    • View SSO global configuration. If you need to change the global config, you need the SSO manage tool.
    • Manage master secret key including key back up, restoration and new key generation
    • Manage SSO type affiliate applications, but not config store type applications.
    • Manage password synchronisation
  2. SSO Application config store MMC
    • This  is used to manage config store type applications only. This  is not installed as part of the standard SSO install, but must be downloaded from Microsoft downloads.
  3. SSOManage.exe & SSOConfig.exe
    • These are command line tools to manage and view SSO type affiliate applications, manage the secret key, update SSO global configuration such as enabling tickets, ticket timeouts.

See Also

  1. Enterprise SSO whitepaper
  2. BizTalk Server 2010: Enterprise SSO Survival Guide
  3. SSO support for receive adapters