Solace PubSub+ Event Broker Interactions

The following sections contain details of how the Solace REST messaging feature interacts with the Solace PubSub+ event broker.

Solace PubSub+ Event Broker Message VPN Selection

Each Message VPN is configured with its own set of TCP ports to support REST clients. Therefore, Message VPNs are selected by connecting to the correct TCP port configured on the event broker.

The table below summarizes how REST clients can select Message VPNs and be authenticated.

Message VPN Selection through REST Protocol

PRTCL	Transport	Auth Scheme	Message VPN	Username
REST	HTTP & HTTPS	Basic	TCP port (either plain-text or SSL port)	HTTP Header: Authorization
		None	TCP port (either plain-text or SSL port)	Not provided.
		OAuth	TCP port (either plain-text or SSL port)	Extracted from the token provided to the event broker. Refer to OAuth Authentication for further details.
	HTTPS	Client Certificate	TCP port (SSL port)	Common Name Frequency: once, on connect The Common Name in the Client Certificate Subject field holds the Username.

Client Authentication

The REST protocol supports basic, SSL, and OAuth authentication for clients.

Basic Client Authentication

For HTTP basic authentication, the HTTP client provides an "Authorization" HTTP header whose value is a “username:password” pair is encoded into a single base64 string, which spans the “:”. If no password is required, then the “username” is encoded into a base64 string without the “:”.

Sequential HTTP POST requests to the event broker using the same persistent HTTP/1.1 connection may each provide their own "Authorization" header. If a subsequent HTTP POST request has no "Authorization" header, or if the "Authorization" header value matches that of the preceding "Authorization" header, then the event broker does not re-authenticate the REST producer client.

If an HTTP POST request has a different "Authorization" header value from the preceding "Authorization" header, then the HTTP connection is re-authenticated according to the new "Authorization" header. This may result in the HTTP connection being attributed to a different event broker client session. (It may be necessary for the event broker to re-authenticate client connections if the HTTP connections are coming through an HTTP proxy or switch that is multiplexing from some number of connections from the actual HTTP client to a smaller number of HTTP connections to the event broker.) Refer to Solace PubSub+ Event Broker Message VPN Selection for further details.

If the first HTTP POST request of a new connection contains no "Authorization" header, then the event broker will authenticate with the client username named default.

A username can contain up to 189 alphanumeric characters (not case-sensitive). The “_” and “-” characters are also permitted, but the ? and * characters are not allowed. The maximum length for a password is 128 bytes; there are no character restrictions imposed by REST messaging.

SSL – Client Certificate

After an HTTPS connection is established, the Solace Message VPN for the connection is already determined based on the TCP port.

When a Client Certificate authentication scheme with SSL transport is used, by default, the username is taken from the Common Name of the certificate. Alternatively, you can configure a Message VPN to use a different source for the client username (refer to Configuring Client Username Sources). In either case, an HTTP Authorization Header should not be provided, because only one authentication scheme should be used. If an HTTP Authorization Header is provided, it is ignored.

OAuth Authentication

Refer to OAuth Authentication for further details.

Solace Client Name

An HTTP client may optionally provide a "Solace-Client-Name" HTTP header specifying the client name in each HTTP POST request. This name uniquely identifies a Solace client session; if the same Solace client name is already in use with an existing Solace client session, then the event broker will log out one of the client sessions contending for the name. On subsequent HTTP POST requests on the same persistent HTTP/1.1 connection, if the HTTP client does not support a "Solace-Client-Name", the event broker treats the client names as being unchanged.

The HTTP client may provide a different "Solace-Client-Name" on subsequent HTTP POST requests. This will change the client name for the event broker's client sessions without re-authenticating the client. However, the proviso that the Solace client name must be unique remains true on client name changes: if an HTTP client changes the "Solace-Client-Name" to a client name already in use, then the event broker will log out one of the client sessions contending for that name.

If an HTTP client does not provide a "Solace-Client-name" HTTP header in the first HTTP POST request on an HTTP connection, the event broker will generate a unique client name for that HTTP connection during authentication.

In all HTTP responses, the event broker will send the "Solace-Client-Name" HTTP header containing the client name associated with the client session.

Solace PubSub+ Event Broker Client Sessions

The event broker considers a sequence of HTTP POST requests received on the same persistent HTTP/1.1 connection, with the same (implicit or explicit) authentication and client name parameters, to belong to the same client session for the purposes of client statistics and event logging.

An HTTP client may provide "Authorization" and "Solace-Client-Name" HTTP headers on any HTTP POST request.

Interactions with Solace Messaging APIs

Solace APIs – Accessing HTTP Content Type and Content Encoding

As explained in Section HTTP Content Entity Headers and Message Payload Types, the HTTP “Content-Type” and “Content-Encoding” headers are preserved in the resulting Solace message. These fields are also accessible by Solace Enterprise APIs. This means uses of the following APIs can set and retrieve these fields from a Solace message.

Solace JMS messaging API
Solace JCSMP messaging API
Solace Java RTO messaging API
Solace C messaging API
Solace .NET messaging API

The Solace JMS messaging API is a standardized API and therefore has a unique way of accessing these Solace message fields. This is shown in its own section below. The other Solace APIs have a common way of accessing these fields so the Solace JCSMP messaging API is used as an example but this is equally applicable to the other APIs.

HTTP Content Type and Content Encoding Access Using JMS

In the Solace JMS messaging API, the HTTP headers Content Type and Content-Encoding are accessed as follows:

MessageConsumer consumer = session.createConsumer(queue);
Message msg = consumer.receive();
String httpContentType = msg.getStringProperty(
           SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_TYPE);
String httpContentEncoding = msg.getStringProperty(
SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_ENCODING);
Setting the properties when sending a message would follow a similar pattern as show here:
Message msg = session. createTextMessage();
msg.setStringProperty(
           SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_TYPE,
“application/json”);
msg.setStringProperty(
SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_ENCODING,
“gzip”);

HTTP Content Type and Content Encoding Access Using Other Solace APIs

This section applies to the following Solace APIs:

Solace JCSMP Messaging API
Solace Java RTO Messaging API
Solace C Messaging API
Solace .NET Messaging API

In these APIs, the HTTP headers Content Type and Content-Encoding are accessed as regular message properties as is done with other message properties such as delivery mode. The example uses the .NET API for illustration:

public static void HandleMessageEvent(Object source,
MessageEventArgs args)
{
    IMessage message = args.Message;
 
    // Process the message
    Console.WriteLine(“HTTP Content Type”);
    Console.WriteLine(message.HTTPContentType);
    Console.WriteLine(“HTTP Content Encoding”);
    Console.WriteLine(message.HTTPContentEncoding);
 
    message.Dispose();
}

Setting the properties when sending a message would follow a similar pattern as show here:

IMessage message = ContextFactory.Instance.CreateMessage();
message.HTTPContentType = “application/json”;
message.HTTPContentEncoding = “gzip”;

JMS Interactions – Text Messages

The Solace JMS implementation is flexible and allows for several encoding formats for text messages. Specifically, the JMS message property “Text Messages are XML” controls whether published text messages can have an XML payload. By default, this field is set to false so that it is disabled. A disabled state is recommended for JMS clients to inter-operate with REST clients. Therefore, you should disable this property in the Solace JNDI configuration. For information on how to set this property, refer to XML Payload.

Provide feedback