Session Properties Required to Establish a Connection

When a Session is created, default values are assigned to its settings, but can be modified if required. How to modify the following settings are explained in this section.

• Authentication Scheme
• Client Name
• Host
• Local Host
• Message VPN

For a complete list of Session properties, valid parameters, and the default values, refer to the PubSub+ Messaging APIs documentation for the appropriate messaging API.

Related Samples

• For the JCSMP, Java RTO, C, and .NET APIs

For an example of how to define the required Session properties when using a basic authentication scheme, which is the default, refer to the DirectPubSub sample. Although other Messaging API samples make use of common code, the DirectPubSub sample explicitly includes the methods used to create Session properties and create a Session.

• For the JavaScript and Node.js APIs

Refer to the TopicSubscriber and TopicPublisher samples.

Authentication Scheme

When a host event broker initially accepts a connection from a client, that connection is in an unauthenticated state, and the event broker cannot process any requests from the client until the connection is authenticated.

The authentication scheme specifies the credentials that a client will use to authenticate its connection to the event broker. The authentication scheme can be one of the following:

• Basic authentication

The default client authentication scheme; it allows a client to authenticate with an event broker using a valid client username and password. For more information, see Basic Authentication.

• Client certificate authentication

A client authentication scheme that allows a client to prove its identity to the event broker through an X509v3 client certificate. This authentication scheme also requires the client to use a secure connection. For more information, see Client Certificate Authentication.

• Kerberos authentication

A client authentication scheme that uses Kerberos to authenticate a connecting client using a ticket that the client obtains through an approved Ticket Granting Service (TGS). For more information, see Kerberos Authentication.

• OAuth Authentication

  A client authentication scheme that allows a client application to use OAuth to authenticate its connection with event brokers. You can use either OAuth2 or OIDC tokens. For more information, see OAuth Authentication

All of these client authentication schemes require explicit input to successfully authenticate a client. For more information, see Defining Client Authentication Info.

The JavaScript and Node.js APIs don't support all authentication schemes. The JavaScript API supports only basic and OAuth authentication , and the Node.js API supports basic, client certificate, and OAuth authentication.

Client Name

When connecting a Session to an event broker, a unique client name is required to register that particular client with the event broker. If no client name is entered, the API automatically generates a unique client name. By default, this parameter is not specified.

The client name is also used to uniquely identify the sender in a message’s senderId field when the Session property to generate a sender ID is set.

The client name property is the same as the client property that can be displayed through the event broker CLI or SolAdmin.

When the Session property to generate a sender ID is set, the client name is included the message’s senderId field to uniquely identify the sender.

Host

The host event broker to connect or reconnect the Session to. An application can connect directly to a host event broker in one of the following ways:

• Connecting Directly to Host Event Brokers
• Connecting to Host Event Broker Through Proxies

Connecting Directly to Host Event Brokers

To connect to a session directly to an event broker use a host entry composed as follows:

[Protocol:]Host[:Port]

Where:

• Protocol is the protocol used for the transport channel. The valid values are:
• For the JCSMP, Java RTO, C, and.NET APIs the valid values are:
• tcp: or tcp://—Use a TCP channel for communications between the application and the event broker. If no protocol is set, TCP is used by default.
• tcps: or tcps://—Use a TLS/SSL channel over TCP for secure communications between the application and the event broker.
• ws: or ws://—Use a WebSockets transport for communication between the application and the event broker.
• wss: or wss://—Use a TLS/SSL channel over WebSockets for secure communication between the application and the event broker.
• In addition to the above for the Java RTO, C, and .NET APIs, and only for the JavaScript and Node.js APIs the valid values are:
• http: or http://—Use Hypertext Transfer Protocol (HTTP) for communication between the application and the event broker.
• https: or https://—Use a TLS/SSL channel over HTTP for secure communication between the application and the event broker.
• Host is one or more IP addresses or hostnames of event brokers to connect to.
• Up to 16 potential hosts to connect or reconnect to can be listed in a comma‑separated list. Listing more than one host allows a client to attempt to connect or reconnect to alternate hosts should the first event broker be unavailable. Connect or reconnect attempts are made to the hosts in the order in which they are presented in the list. The listed host event brokers may be in separate geographic locations.
• When event brokers are operating in high-availability (HA) redundant pairs, do not list both event brokers in the pair as hosts. The redundant pair use the same IP address for the connection, so they appear as one event broker to the messaging API.
• The connect and reconnect behavior of a client is controlled by the channel or Session properties used for its connection with the event broker. Its reconnect behavior is also affected by whether the client application is publishing Guaranteed messages. For more information, refer to Connect Retries Per Host.
• In a Windows environment, a fully qualified domain name (FQDN) should be used for the host parameter, and it must match the FQDN that the event broker uses for the Kerberos Service Principal Name (SPN).
• Port is the port number to use to establish the connection.
• A value is only required when the client needs to use a port other than the automatically‑assigned default port number. The default port number for TCP is 55555 when compression is not in use, or 55003 when compression is in use. The default port for TLS/SSL is 55443, and you use the same port if you use TLS with compression. The default port numbers for:
  • http/ws is 80 for appliances or 8008 for software event brokers
  • https/wss is 443 for appliances or 1443 for software event brokers

Examples:

The following examples show how to connect directly to an event broker. Unless it is otherwise specified, the default port 55555 is used.

• 192.168.160.28—Connect to IP address 192.168.160.28 over TCP.
• dev212— Connect to hostname dev212 over TCP.
• dev212.solacesystems.com—Connect to hostname dev212.solacesystems.com over TCP.
• tcp:192.168.160.28—Connect to IP address 192.168.160.28 over TCP.
• tcps:192.168.160.28—Connect to IP address 192.168.160.28 and port 55443 with TLS/SSL over TCP.
• tcp:192.168.160.28:65535—Connect to IP address 192.168.160.28 and port 65535 over TCP.

When a SPN is generated for the client, the following format is used: service_name/<customer-provided_host>@REALM. The service name portion is configured through the KRB service name session property (by default, it is solace), and the realm portion is determined by the KRB library’s configuration files. An example of a resulting service principle name is solace/dev212@SIMPLESPNEXAMPLE.COM.

When using multiple hosts, the host used for the current connection generates the SPN.

Connecting to Host Event Broker Through Proxies

Your applications can connect to the event broker through HTTP or SOCKS5 proxies.

• Connecting to Host Event Broker Through Proxies in the Java RTO, C, .NET, and JavaScript APIs

• Connecting to Host Event Broker Through Proxies in the JCSMP API

Connecting to Host Event Broker Through Proxies in the Java RTO, C, .NET, and JavaScript APIs

To connect to an event broker through an HTTP or SOCKS protocol version 5 proxy server the configured host setting must include those parameters required for a standard, direct connection to an event broker, but it must also include a proxy service string:

[Protocol:]Host[:Port][%ProxyService]

Where:

ProxyService—The proxy server that is used to connect to event broker. The proxy service string format is specified as:

[ProxyProtocol]://[username:password@]proxyHost[:proxyPort]

Where:

• ProxyProtocol—The protocol used to communication with the proxy server. The valid values are:
  • socks5—Connect to the server with the SOCKS Protocol Version 5, RFC 1928 (IETF Standards Track Document).
  • httpc—Connect to the server with the HTTP Connect Protocol, RFC 2817 (IETF Standards Track Document).
• username:password@—If authentication is required for the proxy server, the username and password may be specified before the proxy host.
• proxyHost—The IP address (or hostname) of the proxy server.
• proxyPort—The port to connect to for a connection. If the port number is not specified, the default is port 1080 for SOCKS5 and port 3128 default for HTTP Connect.

Examples:

The following examples show how to connect to an event broker through a proxy server.

• 192.168.160.28%socks5://192.168.1.1—connects to an event broker at 192.168.160.28 through a SOCKS5 proxy server at 192.168.1.1.
• 192.168.160.28%httpc://192.168.1.1—connects to an event broker at 192.168.160.28 through an HTTP-Connect proxy server at 192.168.1.1.
• tcps:solace.company.com%socks5://User:PassWord@proxy.company.com:13128—connect to an event broker at solace.company.com using SSL over TCP through a SOCKS5 proxy server at proxy.company.com, port 13128. Authenticate with the proxy server using username User and password PassWord.
• http://192.168.160.28:44444%httpc://proxy.company.com:11050—connect to the event broker at 192.168.160.28, port 44444, using HTTP. Connect through the proxy server at proxy.company.com, port 11050.

Connecting to Host Event Broker Through Proxies in the JCSMP API

You can establish a connection to an event broker within your private network via an HTTP or SOCKS5 proxy server, which avoids the need for individual firewall exceptions. The proxy configuration is set with system properties, that are usually set on the java command line or JVM. It is important to note that system properties set on a JVM instance apply to all java applications running on the same JVM.

java -Dsolace.proxy.host=proxy.example.com javaApp
or
java -Dsolace.proxy.host=192.168.1.100 javaApp

java -Dsolace.proxy.type=http javaApp
or
java -Dsolace.proxy.type=socks5 javaApp            

java -Dsolace.proxy.port=8080 javaApp 

java -Dsolace.proxy.username=my_proxy_username javaApp					

java -Dsolace.proxy.password=my_proxy_password javaApp					

The following code snippet sets all proxy server parameters:

java -Dsolace.proxy.type={http} -Dsolace.proxy.host={proxy.example.com} \
			-Dsolace.proxy.port={8080} -Dsolace.proxy.username={my_proxy_username} \
			-Dsolace.proxy.password={my_proxy_password} javaApp

Local Host

The hostname or IP address of the machine on which the application is running. This Session property may be required when the application is running on a multi‑homed machine.

On a multi-homed machine, a local hostname or IP address helps ensure that the API uses the correct network interface for communication with the event broker.

Message VPN

The name of the Message VPN on the host event broker to connect the client to.

Message VPNs are created on the event broker to provide isolation between groups of clients connecting to Solace PubSub+.

If a specific Message VPN is not provided, the Message VPN named default is used. The default Message VPN is always present on an event broker. Although a network administrator can change the configuration settings for default, it cannot be deleted.

Web Transport Protocol for Java RTO, C or .NET APIs

Client applications using the Java RTO, C or .NET APIs can use a web transport for a Session. Web transport is not available for the Java or JMS APIs.

The C session property SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL specifies a web transport protocol in the default web transport protocol downgrade list to use for the session connection. For more information, see Web Transport Protocols.

If an attempt to connect a session with a given transport protocol fails, the API automatically retries with a less-efficient transport protocol. For example, if HTTP_BINARY_STREAMING is selected, but a connection cannot be established, HTTP_BINARY is then attempted. The time in milliseconds between transport protocol connection attempts can be specified with the SOLCLIENT_SESSION_PROP_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS property. By default, the API uses the best available web transport protocol.

Solace recommends leaving SESSION_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS at its default value of 3000 and setting SESSION_RECONNECT_RETRY_WAIT_MS to 10000. These settings allow a client to attempt to connect to each protocol type in turn before a reconnect attempt occurs.

A client may instead specify a comma-separated list of transport protocols using the SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST property. If a connection attempt fails and a list is specified, the API will automatically retry the connection with the next protocol in the list.

To disable auto-negotiation of the transport protocol, a client may specify a single protocol to use for SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST.

Web Transport Protocol for JavaScript and Node.js APIs

For the JavaScript API, the solace.sessionProperties.webTransportProtocolList property defines the possible web transport protocols to use. For more information about the Web transport Protocols, refer to Web Transport Protocols.

Guaranteed messaging support requires the use of the WS_BINARY protocol. Guaranteed messaging is automatically disabled if any other protocol support is enabled.

The Node.js API supports only the WS_BINARY web transport protocol.

The JavaScript API with version 7 API behavior profile supports all transport protocols by default. In addition, the behavior profile enables the API to automatically retry a connection attempt with a less-efficient transport protocol if the initial attempt fails. For example, if WS_BINARY is selected, and a connection cannot be established, HTTP_BINARY_STREAMING is then attempted. The table below shows the transport protocol that each Web API supports. For more information about JavaScript and Node.js API behavior profiles, refer to Initializing and Monitoring APIs.

Guaranteed Messaging over WebSockets

The Java RTO, C, and .NET APIs allow users to perform guaranteed messaging over WebSockets.