Managing REST Service

REST service can be configured on a per-Message VPN level for incoming and outgoing connections.

Configuring Incoming Connections

You can perform the following configuration tasks for incoming REST client connections to the given Message VPN:

Configuring Authorization Header Handling

On PubSub+ event brokers, the REST service receives incoming REST requests, converts them to SMF messages (including copying headers into user properties), and places those messages on the message bus. By default, Authorization headers are not copied into the user properties, however, depending on your deployment, you may want to change this behavior.

To configure how the event broker handles Authorization headers for incoming REST requests, enter the following commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# authorization-header-handling {drop | forward | legacy}

Where:

dropspecifies that the event broker should not attach the Authorization header to the message as a user property. This option is the most secure and is also the default value.

forward specifies that the event broker should forward the Authorization header, attaching it to the message as a user property in the same way as other headers, allowing downstream consumers of the message (including REST Delivery Points) to see the credentials.

legacyspecifies that if the Authorization header was used for authentication to the event broker, the broker should not attach it to the message. If the Authorization header was not used for authentication to the broker, the broker should attach it to the message as a user property in the same way as other headers.

If you select either drop or forward, previously cached Authorization headers on incoming REST requests on the same TCP connection are not used to authenticate incoming REST requests. The REST service responds in the same way as if the request missing the Authorization header was the first one on that connection.

The no version of this command, no authorization-header-handling, returns the value to the default setting (drop).

Because the forward and legacy options can affect security and performance, they should only be used in specific deployment scenarios. We recommend that you contact Solace Support before enabling either of these settings.

Setting the Max Incoming Connections

To set the maximum number of incoming REST clients that can simultaneously connect to the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# max-connections <value>

Where:

<value> is the maximum number of simultaneous incoming REST client connections to the given Message VPN that will be permitted. The valid range is from 0 to the maximum total number of REST clients that can be supported by the type of Solace PubSub+ event broker that the clients connect to.

The no version of this command, no max-connections, resets the value to the maximum limit supported by the event broker.

:  This parameter can be set to a value that is higher than the maximum number of simultaneous connections permitted by the event broker, but the connection limit for the event broker will be still be enforced.

Setting Listen Ports

You must configure a TCP port number for REST clients to use when connecting to the given Message VPN. Separate ports can be configured for plain text REST clients and SSL REST clients.

To set a listen port for REST connections, enter the following CONFIG command:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# listen-port <port> [ssl]

Where:

<port> is the port number from 1 to 65535. This port must not be used for any other service.

[ssl] specifies that the port is for TLS/SSL encrypted connections.

The no version of this command, no listen-port, resets the listen port to an unconfigured state.

The listen port can only be configured while the service using the port is shutdown. If the service is currently running, an error will occur.

Enabling REST Plain Text Service

To enable plain-text REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# no plain-text shutdown

:  Before enabling plain-text service, you must configure the TCP port to be used (refer to Setting Listen Ports).

To disable plain-text REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# plain-text shutdown

Enabling REST SSL Service

To enable SSL REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# no ssl shutdown

:  Before enabling SSL service, you must configure the TCP port to be used (Setting Listen Ports).

To disable SSL REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# ssl shutdown

Configuring Outgoing Connections

You can perform the following configuration tasks for outgoing REST client consumer connections from the given Message VPN:

Setting the Max Outgoing Connections

To set the maximum number of simultaneous REST consumer connections that the given Message VPN can establish, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# outgoing
solace(...ure/message-vpn/service/rest/outgoing)# max-connections <value>

Where:

<value> is the maximum number of REST consumer connections that the current Message VPN can establish. The valid range is from 0 to the maximum total number of REST consumers that can be supported by the type of event broker that the clients connect to.

The no version of this command, no max-connections, resets this parameter to the default value of 6000.

Configuring SSL Cert Validation Settings for Outgoing Connections

For outgoing REST connections that use TLS/SSL encryption, you can perform the following configuration tasks:

Enforcing the Use of Trusted Common Names

In release 9.7.0 and later, the enforce-trusted-common-name command has been deprecated and replaced with the validate-server-name command. For more information about the validate-server-name command, refer to Enabling Sever Name Validation.

A REST consumer may specify a list of trusted common names that it expects to be returned in the server certificate from the remote REST consumer. If you want REST consumers to only operate if a list of trusted common names has been configured, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# enforce-trusted-common-name

The no version of this command, no enforce-trusted-common-name, instructs the event broker not to enforce the use of trusted common names.

When validate-server-name is enabled, the enforce-trusted-common-name parameter is ignored.

Setting the Maximum Certificate Chain Depth

The max-certificate-chain-depth parameter determines the maximum permitted depth for the certificate chain. The depth of a certificate chain is defined as the number of signing CA certificates that are present in the certificate chain back to a trusted self-signed root CA certificate.

To set the max certificate chain depth, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# max-certificate-chain-depth <max-depth>

Where:

<max-depth> is the maximum permitted depth of the certificate chain.

The no version of this command, no max-certificate-chain-depth, resets this parameter to the default value of 3.

Enabling Validation of Certificate Dates

To enable the validation of "not before" and "not after" dates in the server certificate, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# validate-certificate-date

This parameter is enabled by default.

To disable the validation of the "not before" and "not after" dates in the server certificate, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# no validate-certificate-date

If this parameter is disabled, a certificate will be accepted even if it is not valid according to the "not before" or "not after" dates present in the certificate.

Enabling Sever Name Validation

You can enable or disable the TLS authentication mechanism to verify the requested hostname. If enabled, the Server Name Indication (SNI) extension is sent on outgoing TLS connections and the server name used for that connection is verified against the server names in the Subject Alternative Name (SAN) extension in the certificate returned from the remote server.

To enable the validation of server names, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# validate-server-name

This parameter is disabled for existing VPNs on brokers that have been upgraded from versions prior to 9.6; otherwise it is enabled by default.

To disable server name validation, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# no validate-server-name

When validate-server-name is enabled, the enforce-trusted-common-name parameter is ignored (the broker behaves as if enforce-trusted-common-name is false regardless of its actual value).