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.

Authorization header handling settings apply only when the Message VPN is in gateway mode.

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.

legacy specifies that an Authorization header other than Authorization: Basic should be attached to the message as a user property in the same way as other headers. An Authorization: Basic header will not be attached to the message as a user property, though it could be used for the broker's own basic client authentication.

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 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 When to Request a Client Certificate from a REST Client

By default, PubSub+ event brokers request client certificates from REST clients connecting via a TLS port if client certificate authentication is enabled in a given Message VPN. Because many popular web browsers handle the request for a client certificate poorly, this can result in clients running in web browsers being unable to connect over REST-based protocols. If you have clients connecting from a web browser and other clients in the same Message VPN that need to authenticate using client certificates, you may want to prevent the broker from requesting a client certificate from incoming REST clients.

To configure when the broker requests a client certificate from incoming REST clients connecting via a TLS port, 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)# authentication
solace(.../service/rest/incoming/authentication)# client-certificate
solace(...ing/authentication/client-certificate)# request-client-certificate {always | never | when-enabled-in-message-vpn}

Where:

always configures the broker to always request a client certificate, regardless of whether client certificate authentication is enabled in the Message VPN. For more information, see Enabling/Disabling Client Certificate Authentication For Clients .

never configures the broker to never request a client certificate, regardless of whether client certificate authentication is enabled in the Message VPN. This setting is useful if you don't want the broker to request a client certificate from your REST clients, but you still want to use client certificate authentication for other types of clients (such as bridges).

when-enabled-in-message-vpn configures the broker to request a client certificate only if client certificate authentication is enabled in the Message VPN. This is the default setting.

The no version of command, no request-client-certificate, resets the value to the default.

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:

Enabling Server Name Validation

You can enable or disable the TLS authentication mechanism to verify the requested hostname. If enabled, 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 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

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.