The Citrix XML server explained and demystified

The Citrix XML server is a component of Citrix XenApp and XenDesktop that’s used to enumerates available resources  and provide secure tickets for users that  to use the  WebInterface or CloudGateway.

In this article I’ll explain what the services the XML service provide, how it does it job and all you need to know about it.

Introduction

The Citrix XML service is a Windows service that is part of the Citrix XenApp and XenDesktop product. It is used to provide XML data requests sent by Citrix components. It is introduced with MetaFrame 1.8 SP2, since MetaFrame XP is is a standard feature.  Up to XenApp 6.0 each XenApp server could be a XML broker. Since XenApp 6.5, where the controller-worker architecture is introduced, only a server with the controller role can be a XML broker. A server with the controller role is responsible for farm management.

The Citrix XML service is most commonly used to provide users access to their applications and desktops via a web portal, leveraging the services of WebInterface, CloudGateway (Storefront) or Access Gateway. It is also used when users connect via the TCP/IP+HTTP protocol.

It is recommended to have multiple servers with the Citrix XML server, as close as possible to the servers Zone Data Collectors (XenApp) and Desktop Delivery Controller (XenDesktop).

Windows Service

The windows service is identified by the name CtxHttp, which reveals it leverages this protocol for network transportation. Basically the Citrix XML service has a built-in (simplified) webserver to transfer XML documents.

The service is launched with the predefined local Network Service account, which allows it to communicate over the network.

XML? XML stands for Extensible Markup Language, it is a markup language for documents containing structured information (wikipedia).

Files

The Citrix XML service consists of a number of files to provide its services. The files are , by default, stored in %ProgramFiles%\Citrix\System32 on a 32-bit operating system and %ProgramFiles(x86)%\Citrix\System32 on a 64-bit operating system.

Communication

By default the Citrix XML service listens on TCP port: 80. Although this is the default port, Citrix recommends using port 8080.

IIS integration

If Microsoft Internet Information Services (IIS) is installed the Citrix XML Service is integrated by default. Otherwise the Citrix XML service defaults to standalone mode. If during the installation the an IIS server (or the IIS server role) is detected, the files specified above folder are copied from %ProgramFiles(x86)%\Citrix\system32\ to %SystemRoot%\inetpub\scripts. Letting the Citrix XML server integrate with IIS effectively (sharing ports) disables the use of the Windows Service and creates a Web Service in IIS.

You can test the IIS integration by opening the the following url in your browser https://hostname/Scripts/ctxsta.dll. If the integration is configured correctly you should get the following response:

HTTP Error 405.0 – method not supported
The page you are looking for cannot be displayed because an invalid method (HTTP verb) is being used.
 
Module IsapiModule
Notification ExecuteRequestHandler
Handler ISAPI-dll
Error Code 0×00000000

It is not recommend to integrate the Citrix XML Server in IIS and use the share port 80 with IIS (Configuring the Citrix XML Service Port and Trust – Citrix eDocs – Beware of Hosting Web Interface on XenApp Servers – Nicholas Dille)

Changing the Citrix XML Service port number

If a different process requires the same ports you will receive the message “Citrix XML port selected is in use by another application or service”. If necessary you can change the port of the Citrix XML server. The Citrix XML Service and Microsoft IIS can share a port (default = 80), you should only specify a different port if you don’t want to share ports.

To find out what other process is using the same port you can run the following command: netstat –ano –p tcp (or netstat –ban –tcp if you have Windows 7 / 2008) and locate the process ID (PID) that listens on the same port.

In XenApp 6.0 or later changing the XML port can be done with a server policy: XML Service\XML service port. However, this can only be done if you selected a custom port during installation instead of Share with IIS.

The port number can also be changed with the ctxxmlss command-line utility.  This can be done by unloading the Citrix XML Service with /u, changing the port with /r<port number> and restarting the XML service.

ctxxmlss /u
ctxxmlss /r8080

An alternative method is by changing the port in the registry (and restart the Citrix XML service after changing).

Key: HKLM\SYSTEM\CurrentControlSet\Services\CtxHttp
Value: TcpPort
Type: DWORD (32-bit)

The value is listed in hex, you need to change the view to decimal.

Citrix XML Service Trust

The security level of the Citrix XML service can be lowered by allowing the Citrix XML Service to trust all requests. The trust setting is only for Smooth Roaming when users authenticate using pass-through or smart-card authentication with WebInterface or online plug-in.

To avoid security risks, only enable the Citrix XML service to trust requests it receives when you’re confident that only trusted services communicate with the Citrix XML Service. This can be achieved by using firewalls or using IPSec. By default the trust is disabled.

In XenApp 5.0and Presentation Server 4.x enabling the XML trust can be done via the Citrix Access Management Console (AMC) in the the server settings: XML Service

In XenApp 6.0 or later enabling the XML trust can be done with a server policy: XML Service\Trust XML requests.

Services provided

When a user starts his browser and connects to the URL of the web portal (WebInterface or Citrix Access Gateway), authenticates and launches an application (or desktop) a number of transactions take place between the WI/CAG and the XML Service.

In a basic environment where the users connects to a published resource via a Citrix Access Gateway, the following transactions takes places.

1. The provides his credentials to the webserver (WI or CAG)
2. The webserver reads the credentials and authenticates the user (based on the settings of the web site)
3. The webserver sends the credentials to one (or more) Citrix XML servers for each farm to validate the credentials (RequestValidateCredentials) and to get a list of available resources (RequestAppData)
4. The Secure Ticket Authorithy (STA), part of the Citrix XML server, returns a secure ticket
5. The XML broker, part of the Citrix XML server, queries the IMA service (XenApp) or Desktop Delivery Controller (XenDesktop) for resources available for the user
6. The XML service returns an XML file containing the secure ticket (ResponseValidateCredentials) and available resources (ResponseAppData)
7. The web server generates a web page containing all the resources the user can access (or the shortcuts are placed on the desktop / start menu by the PN agent)
8. The user clicks on a resource
9. The webserver requests the XML server (from the farm / site where the resource belongs to) for the system to connect to (RequestAddress)
10. The STA server queries the IMA service (XenApp) or Desktop Delivery Controller (XenDesktop) for the system that can provide the resource
11. The STA returns the system that can provide the resource to the CAG (ResponseAddress)
12. The webserver sends a default.ica file containing information about the resource, STA server (as configured in the secure access settings in the WebInterface) secure ticket and connection properties (more information about the ICA file can be found here).
13. The Citrix client (for instance the Receiver) makes a connection to the CAG
14. The CAG requests the STA server (stored in the ICA file) if the secure ticket is valid and to which system to connect
15. The STA server validates the secure ticket (from memory)
16. The CAG server accepts the connection and the connection is started.

Nicholas Dille wrote an excellent article called ‘Talking to the XML Service’. If you want to dive deeper in the messages being sent by the Citrix XML Service, you should read it.

So, basically the XML service has two functions:

• Communicating with the XenApp farm / XenDesktop zones; the XML broker
• Generating and validating secure ticket to authorize users, the Secure Ticket Authority (STA)

1. The XML broker

Introduction

The Web Interface and the XML Broker are complementary services. The Web Interface provides users with access to applications. The XML Broker determines which resources (like applications, desktops, etc.) appear in the Web Interface, based on the user’s permissions.

The XML broker is used by the Web Interface to enumerate published resources from the a XenApp farm or XenDesktop site. This server also communicates directly with a Zone Data Collector (XenApp) or Desktop Delivery Controller (XenDesktop) to determine the system to route a user to when an application is launched through the Web Interface.

Troubleshooting

If you need to troubleshoot the communication between the Citrix XML service and the IMA farm (XenApp) or Desktop Delivery Controller I would recommend you to read the following articles of Nicholas Dille:

• Talking to the XML Service
• Debugging Using XmlServiceExplorer Part 1, Part 2 and Part 3

2. The Secure Ticket Authority (STA)

Introduction

The Secure Ticket Authority (STA) is introduced with the Citrix Secure Gateway 1.0 (released around 2001). Before the release of Presentation Server 4.0 (released in 2004) the STA was a separately installed component that required Microsoft IIS to host the service. With Presentation Server 4.0 (and all future releases) it is part of the Citrix XML service. In this article I’m assuming your using PS4.0 or later and therefore the STA server is integrated in the XML server.

The STA generates and validates secure tickets that authorize users to traverse a Secure Gateway or Access Gateway to a XenApp/XenDesktop farm. In a CSG deployment the gateway server does not perform authentication of incoming request. Instead the gateway defers authentication to an STA server to guarantee that each server is authenticated. If users have valid STA tickets, the gateway assumes that the passed the authentication checks and should be permitted access.

Note the difference between those authentication and authorization. Authentication is a process where credentials (or a token, etc.) are verified against an directory service (like Active Directory) or a RADIUS server to verify the user is who it claims to be. An authorization process is verifying if the user is allowed to access / use a resource

The Secure Ticket Authority (STA) is accessed via /Scripts/CtxSta.dll.

Authentication

On the WebInterface you specify where the authentication takes place. This is the component that validates the credentials, token, etc. of the user to verify the user is who he says it is. It will then request a secure ticket from one STA for each farm (as specified in the Web Sites / Services Sites). The ticket and its corresponding data remains in memory at the STA for a configurable number of seconds (100 by default). The ticket can only be used once, so they are deleted after use.

The STA ticket is stored in the Address property of the launch.ica that is provided by the WebInterface. For more information about the content of ICA file please read the article The Citrix ICA file explained and demystified.

Whenever a secure session is initiated (the user launches an application or desktop) the traversed components (like CAG, CSG or MSAM) only has to validate the ticket at the STA. If the STA confirms the ticket is valid, access is granted.  This is why it is important that all components (WebInterface, Storefront, Netscaler, Access Gateway, Secure Gateway, etc.) point to the same STA servers.

Identification

Each Secure Ticket Authority is identified by an unique identifier  that consists of a sequence of 0 – 16 characters representing the STA. This unique identifier is used in the ICA file (in the Address property) to direct the traversed components (like NetScaler, CAG, CSG, etc.) to the STA that issued the secure ticket. In version 1.x this string defaults to STA01, STA02 and so on. Since STA 2.x the STA ID is a hash of the server name (STAB57127594AE9 in the example screenshots above).

If there is a mismatch or a duplicate identifier, the wrong STA is requested to validate the secure ticket (who hasn’t issued the ticket , and therefore stored in memory) resulting in an authentication failure.

Versions

In time the STA is developed to support more features, as a result multiple versions of the STA exist. All versions of Web Interface (WI), Secure Gateway (CSG), MetaFrame Secure Access Manager (MSAM) and Access Gateway (CAG) are compatible with all versions of STA, but not all features are available.

On a high level the following features are added

• 1.0: Initial release
• 1.1: No material functional differences
• 2.0 (released with CSG 2.0 / MSAM 2.0): Session details in Secure Gateway Management console (N/A is shown)
• 2.2 (released with MSAM 2.2): Advanced Gateway Client features
• 4.0 (released with CSG 3.0 / PS 4.0) : Session reliability through the gateway + XML service integration

More information about STA compatibility with other Citrix products can be read in CTX108302.

Ticket content

Both request and response are carried out as an XML request/response document (hence why the integrated the STA in the XML service). The encoding format is a string of the form

;STA_VERSION;STA_ID;TICKET

• STA_VERSION: A numeric field that identifies the STA version . 10 stands for 1.0/1.1, 20 for 2.0, etc.
• STA_ID: The identifier of the STA (for example STAB57127594AE9)
• TICKET: a randomly-generated sequence of 32 uppercase alphabetic or numeric characters.

For example: ;10;STAB57127594AE9;770E4AE99C332CA3757361DD716A0CF2

Troubleshooting

If you need to troubleshoot an issue with the STA I would recommend to enable logging first. Logging can be enabled in the CtxSta.config file which can be found in %ProgramFiles%\Citrix\System32 on a 32-bit operating system and %ProgramFiles(x86)%\Citrix\System32 on a 64-bit operating system. In this file you need to set LogLevel=3 and restart the Citrix XML service. By default the logfiles are stored in ..\Logs.

In the CtxSta.config you can also verify and change the unique identifier (UID) of the STA and change other settings.

Protocol Driver Error

A common error is the ‘protocol driver error’ when you connect to a published resource via a Citrix Access Gateway (CAG).  This error can be caused by a missing (or misconfigured) STA server in the Access Gateway.

Each secure ticket authority (STA) server that is specified in the secure access settings of the WebInterface, needs to be configured in the CAG as well. If the STA is missing in the CAG it might not validate the secure ticket.

This is because the ICA file contains the identifier of the STA server (in the Address field) and that needs to be validated by the CAG. If the identifier of the STA is not specified in the CAG, it doesn’t know what server issued the ticket and therefore can’t verify it.

Comments

Have a question or suggestion? Let me know in the comments.