PCoIP Connection Broker Protocol Overview¶

The PCoIP Connection Broker Protocol (hereafter referred to as the Broker Protocol) is a web application program interface (API) used by PCoIP clients to securely communicate with connection brokers that manage PCoIP sessions and resources. A PCoIP session provides access to a remote desktop or application.

This document provides an overview of the Broker Protocol, the devices and software commonly involved with Broker Protocol connections, and an example of a Broker Protocol session flow. This document is not a specification and should be only considered as an informal example.

The connection broker is a portion of the overall solution in the Teradici Cloud Access Software. From the PCoIP client’s perspective, the connection broker authenticates the user, provides a list of ‘entitled resources’ or inventory to the user for selection, and provides connection information to the selected resource. A minimal broker implementation would provide password authentication and inventory and connection information.

The remote resource, being either a remote desktop or remote application, is provided by a virtual or physical host where an appropriate PCoIP agent is installed, licensed, and running.

The Broker Protocol facilitates the following functionality:

• Authenticating a user to access remote resources.
• Querying which resources are available to a user.
• Provisioning the host resource.
• Selecting the host resource to establish a PCoIP session.
• Establishing a PCoIP session.
• Creating network security deployment topologies involving gateways and proxies.
• Creating distributed authentication deployment topologies.
• Providing high availability deployments.

Partner Requirements¶

A Teradici partner implementing the Broker Protocol will implement different aspects of the system depending on which PCoIP components the partner is using.

One case is where the partner is implementing a custom deployment and brokering system, but generally consuming the rest of the platform—such as connection managers, PCoIP agents and PCoIP clients—‘out of the box’. In this case, the partner is responsible for implementing Broker Protocol API from the ‘broker’ or ‘server’ perspective.

Other partners, such as gateway, authentication, or client partners, may need to implement both from the broker or server perspective, as well as from the client side.

User Authentication¶

The connection broker is responsible for specifying which authentication methods, if any, must be employed to authenticate a user before requesting a list of resources to which the user is entitled.

User authentication is used both for ensuring the user has access to the overall system, as well as providing, when possible, single-sign-on functionality such that a user only needs to enter credentials once to access the brokering system and the resource.

The user authentication methods discussed next are supported by the Broker Protocol. Brokers implement the methods as appropriate for their systems and usage scenarios. Of these methods, the password method is the only required method in the protocol. Other methods are optional.

• Password method: The user is authenticated using the operating system (for example, Windows) username, password, and domain name.
• Token authentication method: The token authentication method allows the client to reconnect to a previously disconnected PCoIP session using user credentials cached on the client machine. The user does not need to re-enter credentials.
• Disclaimer method: The user is prompted to accept a disclaimer statement as one of the authentication steps/methods. The connection broker provides the disclaimer text to be accepted by the user.
• Dialog method: In this case, the broker sends information to the client to enable the client to create a dialog box for user input. This method is suitable for a large number of cases, including multi-factor and challenge-response authentication methods.
• ID card method: The ID card is a physical identification card that has been issued to the user. The PCoIP client reads the ID card to obtain the card number stored in the card, and provides it to the connection broker to identify and/or authenticate the user.

In addition, the following authentication methods are available. These cases require more involved system changes and so cannot be implemented without direct interaction with Teradici:

• OAuth authentication method: The client uses the OAuth protocol to authenticate a user. User credentials are not passed to the client nor sent over the Broker Protocol. After authenticating a user, the client is granted an OAuth authorization code or access token which is passed over the Broker Protocol to access the resource.
• Kerberos authentication method: The client uses the Kerberos protocol to authenticate a user. After authenticating a user, the client is granted a Kerberos Ticket-Granting Ticket which is passed over the Broker Protocol to access the resource.

Optional Features¶

The protocol has other optional features, which may be implemented by partner products. These include:

• Updating a user’s password.
• Performing operations on resources such as operating system restart, sleep, resume, power off and on, and wake-on-LAN.
• Conveying resource state and health information to the user.
• Identifying client geographical location through IP address.
• Remapping IP spaces through network address translations (NATs) to support connections from outside the local network.
• Localizing output for languages other than US English. Teradici Zero Clients support a variety of locales. Consult the release notes for each zero client for an accurate list.