Managing REST Delivery Points

A REST delivery point (RDP) is a provisioned object on a Message VPN that facilitates message delivery to REST consumers. An RDP is associated with a client profile on the Message VPN that provides it with some configuration parameters. The RDP can be bound to message queues to deliver messages from those queues to REST consumers. The RDP maintains a list of REST consumers, which are identified by their remote connection information.

You can perform the following configuration tasks for RDPs:

Configuring REST Delivery Points

  • To create an RDP for the given Message VPN, enter the following CONFIG commands: 
    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# rest
    solace(configure/message-vpn/rest)# create rest-delivery-point <name>
  • To edit the properties of an existing RDP, enter the following CONFIG commands: 
    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# rest
    solace(configure/message-vpn/rest)# rest-delivery-point <name>

Where:

  • <name> is the name of the RDP. RDP names can be up to 100 characters and must be unique within the given Message VPN.

The no version of this command, no rest-delivery-point, deletes the specified RDP and all of its associated configuration.

Entering the rest-delivery-point REST VPN CONFIG command moves the CLI to an RDP configuration mode from which you can perform the following tasks:

For detailed information about RDP limits, see the SolacePubSub_<version>_limits_and_alerts spreadsheet under the relevant broker version folder on the Solace Products website. To access the Solace Products website, use your username and password provided from Solace or your SSO Login. If you have issues accessing the website, contact Solace.

Associating Client Profiles with REST Delivery Points

When an RDP is associated with an existing client profile, the RDP inherits that client profile’s TCP parameters and queue properties (max-depth and min-msg-burst). The TCP parameters inherited from the client profile will be used for all REST consumers on the delivery point.

You cannot enable an RDP unless allow-guaranteed-message-receive is enabled on the associated client profile.

To associate a client profile with the given RDP, enter the following CONFIG command:

solace(.../message-vpn/rest/rest-delivery-point)# client-profile <name>

Where:

  • <name> is the name of a client profile that already exists in the local Message VPN. By default, if no client profile is associated with an RDP, it will use the client profile named default for the current Message VPN.

The no version of this command, no client-profile, removes the client profile association from the RDP and assigns the default client profile for the current Message VPN.

Managing REST Delivery Point Queue Bindings

An RDP must be bound to one or more durable queues to attract messages from the queues and deliver them to REST consumers.

  • To bind the given RDP to a queue, enter the following CONFIG command: 
    solace(.../message-vpn/rest/rest-delivery-point)# create queue-binding <queue-name>
  • To edit the properties of an existing queue binding, enter the following CONFIG command: 
    solace(.../message-vpn/rest/rest-delivery-point)# queue-binding <queue‑name>

Where:

  • <queue-name> is the name of a queue in the given Message VPN to bind to the current RDP. Queue names can contain up to 200 characters (the only invalid characters are '<>*?&;).

The no version of this command, no queue-binding, deletes the specified queue binding for the current RDP. However, it does not delete the queue.

  • You can specify a binding to a queue that does not exist, but before the RDP can be brought into service, the referenced queue must be created. That is, a queue must exist with the same name as the queue binding in the same Message VPN as the RDP. The RDP must also have permission to consume messages from the queue—to achieve this, the queue’s owner must be set to #rdp/<rdp-name> or the queue’s permissions for non-owner clients must be set to at least consume level access. For more information on configuring queues, refer to Configuring Queues.
  • The maximum number of queue bindings that can be created is the same as the maximum number of queues supported by an event broker.

The queue-binding REST VPN CONFIG command moves the CLI to the REST delivery point queue binding level:

solace(...est/rest-delivery-point/queue-binding)#

From this level, you can configure a POST request target for the given queue binding.

Configuring POST Request Targets

The POST request target that is associated with a queue binding is used in HTTP POST requests that are sent to REST consumers and identifies the target resource for message delivery on the remote REST consumer. Message delivery from a queue to a REST consumer cannot occur until a POST request target has been configured for the queue binding. For more information about request targets, see RFC 7230 §5.3.

To configure a POST request target for a queue binding, enter the following CONFIG command:

solace(...est/rest-delivery-point/queue-binding)# post-request-target <post-request-target>

Where:

  • <post-request-target> is a string containing the POST request target to associate with the current queue binding.

The no version of this command, no post-request-target, removes the POST request target from the current queue binding.

If the Message VPN containing the RDP is configured to act as a Microgateway, the POST request target is ignored.

Configuring the Type of Evaluation to Perform on POST Request Targets

When forwarding messages to external systems via an RDP, it is often useful to have access to the message topic and other metadata on that external system. For example, you may want to use RDPs to send messages into storage services such as Azure Storage, Amazon S3, or Google Cloud Storage. This requires sending each message to a unique target, preferably with that uniqueness coming from the message topic, metadata, or the current time. To enable this, you can include substitution expressions in the POST request target and configure the event broker to evaluate these expressions. For more information about substitution expressions, refer to Substitution Expressions Overview.

To configure the type of evaluation to perform on the request target, enter the following CONFIG commands:

solace(...est/rest-delivery-point/queue-binding)# post-request-target <post-request-target>
solace(...int/queue-binding/post-request-target)# request-target-evaluation {none | substitution-expressions}

Where:

  • <post-request-target> is a string containing the POST request target to associate with the current queue binding.

  • none configures the event broker to not evaluate substitution expressions on the request target. This is the default.

  • substitution-expressions configures the event broker to evaluate substitution expressions on the request target.

The no version of this command, no request-target-evaluation, resets the value to the default.

Configuring Request Headers

When forwarding messages to external systems via an RDP, it is often useful to have access to the message topic and other metadata on that external system. By configuring request headers for a queue binding, you can put metadata (such as SAP Object IDs for ASAPIO) into request headers. In addition, you can configure the event broker to send specific headers that are required for cloud services such as Azure Storage and AWS EventBridge.

To create a request header for a queue binding, enter the following CONFIG command:

solace(...est/rest-delivery-point/queue-binding)# create request-header <header-name>

To configure the value for the request header, enter the following CONFIG command:

solace(...ry-point/queue-binding/request-header)# header-value <header-value>

Where:

  • <header-name> is a string containing the name of an HTTP request header to associate with the current queue binding. Header names must comply with the token production in RFC 7230 §3.2.6. The following headers are not allowed: Authorization, Connection, Content-Length, Expect, Transfer-Encoding and Upgrade. Request header names can contain up to 50 characters.

  • <header-value> is a string containing a substitution expression for the value of the HTTP request header. The default value is an empty string. Request header values can contain up to 2000 characters. For more information about substitution expressions, refer to Substitution Expressions Overview.

Headers specified on the queue binding replace all headers of the same name (case-insensitive) from SMF user properties or generated from other metadata. These headers also take precedence over the headers described in HTTP Header Authentication.

For example, to configure the queue binding to send two additional headers required by a particular cloud service, you can enter the following commands:

solace(...est/rest-delivery-point/queue-binding)# create request-header X-ORDER-ID
solace(...ry-point/queue-binding/request-header)# header-value ${topic(-1)}
solace(...ry-point/queue-binding/request-header)# exit
solace(...est/rest-delivery-point/queue-binding)# create request-header x-api-version
solace(...ry-point/queue-binding/request-header)# header-value 2021-02-03

In this case, for a message with the topic orders/hw/update/v2/can/C-1234/P-E7Y1/O-6789, the following headers would be added to the request: X-ORDER-ID: O-6789 and x-api-version: 2021-02-03.

For detailed information about request header limits, see the SolacePubSub_<version>_limits_and_alerts spreadsheet under the relevant broker version folder on the Solace Products website. To access the Solace Products website, use your username and password provided from Solace or your SSO Login. If you have issues accessing the website, contact Solace.

Configuring Protected Request Headers

When the value of a request header is sensitive, a protected request header should be used instead. Like regular request headers, each protected request header consists of a header name and a header value. Once set, protected request header values are masked from viewing on management interfaces and in logs, similar to passwords.

Protected and regular request headers share a common limit on the total number of request headers that can be configured, and it is not possible to create a protected request header and a regular request header with the same name.

Protected request headers do not support substitution expressions (for more information about substitution expressions, refer to Substitution Expressions Overview).

To create a protected request header for a queue binding, enter the following CONFIG command:

solace(...est/rest-delivery-point/queue-binding)# create protected-request-header <header-name>

To configure the value for the protected request header, enter the following CONFIG command:

solace(...ueue-binding/protected-request-header)# header-value <header-value>

Where:

  • <header-name> and <header-value> have the same meaning as for regular request headers.

For example, to configure the queue binding to send an API key header required by a particular cloud service, you can enter the following commands:

solace(...est/rest-delivery-point/queue-binding)# create protected-request-header X-API-KEY
solace(...ueue-binding/protected-request-header)# header-value 0aa99f00-b752-4bb9-b549-c168ad250e76
solace(...ueue-binding/protected-request-header)# exit

In this case, the following header would be added to the request: X-API-KEY: 0aa99f00-b752-4bb9-b549-c168ad250e76.

Replacing the Authority Value in Outbound URIs

When a Message VPN is configured to act as a Microgateway, the event broker propagates HTTP requests in absolute form and retrieves the request-target's authority from the REST consumer's remote host and port configuration. You can optionally disable this functionality, and configure the event broker to use the authority configured in the original request.

To configure the event broker to use the authority value in the original request, enter the following CONFIG commands: 

solace(...est/rest-delivery-point/queue-binding)# gateway
solace(...-delivery-point/queue-binding/gateway)# no replace-target-authority

To configure the event broker to replace the authority with the value configured for the REST consumer, enter the following CONFIG commands:

solace(...est/rest-delivery-point/queue-binding)# gateway
solace(...-delivery-point/queue-binding/gateway)# replace-target-authority
Replacing the authority value in outbound URIs is available only when the corresponding Message VPN is configured to act as a Microgateway.

Configuring REST Consumers

A REST consumer is a virtual representation of a client or endpoint. An RDP maintains a list of REST consumers that messages can be delivered to.

  • To create REST consumer within the current RDP, enter the following CONFIG command: 
    solace(.../message-vpn/rest/rest-delivery-point)# create rest-consumer <name>
  • To edit an existing REST consumer, enter the following CONFIG command: 
    solace(.../message-vpn/rest/rest-delivery-point)# rest-consumer <name>

Where:

  • <name> is the name of the specified REST consumer. The REST consumer name can contain up to 32 characters.

The no version of this command, no rest-consumer <name>, deletes the specified REST consumer and all of its configuration.

Entering the rest-consumer REST VPN CONFIG command moves the CLI to a configuration mode for REST consumers, from which you can perform the following tasks:

For detailed information about REST consumer limits, see the SolacePubSub_<version>_limits_and_alerts spreadsheet under the relevant broker version folder on the Solace Products website. To access the Solace Products website, use your username and password provided from Solace or your SSO Login. If you have issues accessing the website, contact Solace.

Configuring Remote Connection Info for REST Consumers

To configure remote connection information for the given REST consumer, enter the following REST VPN CONFIG command:

solace(...est/rest-delivery-point/rest-consumer)# remote

The CLI enters the Message VPN remote REST consumer level, from which you can configure the following remote connection properties for the current REST consumer:

Remote connection parameters for a REST consumer can only be configured while the REST consumer is shut down.

Host

To configure or reset either the IP address or DNS Name that the event broker will connect to so that it can deliver messages for the given REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# host <dest-ip-addr-or-host>

Where:

  • <dest-ip-addr-or-host> is the IP address or DNS name to which the event broker will connect to deliver messages for the current REST consumer, and it can contain up to 253 characters.

In addition to an IPv4 address or DNS name, you can specify an IPv6 address if the event broker's message backbone is configured with an IPv6 global unicast or unique local address. For more information, refer to Configuring Appliance IP Interfaces, or IP Interface Configuration for Software Event Brokers .

If you specify a DNS name and both an IPv4 and IPv6 address are returned during the lookup, the event broker chooses the IP address based on the priority specified by the configured DNS server(s). See DNS Name Lookup for more information.

The no version of this command, no host, resets the host setting to its default value (empty). If a REST consumer is enabled but has no host value configured, it will be in an operational Down state until a valid host value is set.

The host value can only be configured while the REST consumer is shutdown.

Port

To configure a port to be used with the host of the current REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# port <port>

Where:

  • <port> is the desired port number. Acceptable values are numerals from 1 to 65535.

The no version of this command, no port, resets the port value to a default value. Default values are 8080 for plain-text connections and 8443 for SSL connections.

Proxy

Depending on your deployment, you may require that communication between REST consumers and endpoint servers (such as external websites) goes through a forward proxy. This is often the case if your event broker sits behind a firewall and egress traffic needs to connect to a proxy server to go outside the firewall.

To configure a forward proxy for the current REST consumer, enter the following command:

solace(...t-delivery-point/rest-consumer/remote)# proxy <proxy-name>

Where:

<proxy-name> is the name of a forward proxy configured on the Message VPN. For more information, see Configuring a Forward Proxy. The proxy configured for a REST Consumer and the proxy settings on individual REST Consumer authentication methods are independent. In other words, this proxy setting doesn't affect REST Consumer authentication proxy settings and vice-versa.

The no version of this command, no proxy, removes any configured proxy.

SSL

To enable or disable SSL connections for the current REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# ssl

The no version of this command, no ssl, disables SSL connections for the current REST consumer.

HTTP Method

By default, PubSub+ event brokers use the POST HTTP method when delivering messages to remote endpoints. You can instead specify that outgoing messages should use the PUT method. Changing the HTTP method allows you to connect the event broker to endpoints that do not support the POST method (for example, certain cloud native data lake products).

To configure the HTTP method used for the outgoing connection, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# http-method {post | put}

Where:

  • post specifies to use the POST HTTP method when delivering messages to the remote endpoint.

  • put specifies to use the PUT HTTP method when delivering messages to the remote endpoint.

  • The no version of this command, no http-method, returns the setting to the default value (POST).

If the corresponding Message VPN is in gateway mode, the specified HTTP method is ignored since the incoming method (GET, PUT, POST, DELETE, PATCH, HEAD, OPTIONS) is passed through the broker. For more information about the REST VPN mode, see Configuring the REST Message VPN Mode.

Outgoing Connection Count

To set the total number of concurrent TCP connections initiated by the event broker that are open to the given REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# outgoing-connection-count <count>

Where:

  • <count> is the total number of outgoing connections (and thus HTTP POST operations) to this REST consumer that the appliance may initiate. Valid values are between 1 and 50 (inclusive).

The no version of this command, no outgoing-connection-count, resets the outgoing connection count parameter to the default value of 3.

Maximum POST Wait Time

There is a maximum amount of time that the event broker will wait for a response from the REST consumer.

If an operation has been outstanding for more than the configured maximum wait time, the TCP connection is reset. If the request is for a non-persistent message, the message is discarded. If the request is for a persistent message, message delivery is re-attempted through another available outgoing connection for the RDP, up to the max delivery count on the queue. If the max delivery count is exceeded, and the message is eligible for the Dead Message Queue (DMQ), then the message is moved to the DMQ, otherwise it is discarded.

To set the max wait time, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# max‑post-wait-time <seconds>

Where:

  • <seconds> is the amount of time in seconds to wait for a response from an outstanding operation. The valid range is from 1 to 300.

The no version of this command, no max-post-wait-time, resets the maximum wait time parameter to the default value of 30.

Retry

To configure the retry delay (that is, the amount of time that should pass before a connection attempt is retried) enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# retry delay <seconds>

Where:

  • <seconds> is the amount of time (in seconds) that must pass before a connection attempt is retried. The valid range is from 1 to 300.

The no version of this command, no delay, resets the retry delay to the default value of 3.

If the Message VPN containing the RDP is configured to act as a Microgateway, the retry delay is ignored.

Configuring a Specific IP Interface for REST Consumers

By default, an event broker automatically chooses the IP interface through which outgoing connections from a REST consumer are made.

However, if your environment requires a fixed IP interface, it is also possible to configure a specific interface for the REST consumer. When a specific IP interface is configured, the source IP address specified in all outgoing packets will be the same for all connections associated with the REST consumer. A fixed IP interface may be required, for example, if a firewall is used between a client application and the event broker. In this case, the firewall must be configured to permit the event broker’s source IP address through, so an automatically-selected IP interface can be problematic.

If a local IP interface for a REST consumer is configured, that configuration will be propagated if the Config-Sync and/or Replication facilities are used. Therefore, you must either ensure that the specified interface is available on all Message VPNs that will be synchronized and/or replicated, or you should use the default behavior where the event brokers automatically select an IP interface.

To configure a specific local IP interface to use for all outgoing connections associated with the given REST consumer, enter the following CONFIG command:

solace(...est/rest-delivery-point/rest-consumer)# local
solace(...st-delivery-point/rest-consumer/local)# interface <phys-intf>

Where:

  • <phys-intf> is an ASCII string specifying the physical Ethernet interface port or LAG of the local appliance to use for all outgoing connections associated with the given REST consumer. Valid values are eth<port> (for example, eth1); chassis/lag1; <cartridge>/<slot>/<port> (for example, 1/1/8); <cartridge>/<slot>/lag<N> (for example, 1/1/lag1). Only a single LAG numbered 1 is supported.

The no version of this command, no interface, removes any configured local IP interface and resumes the default behavior where the event broker automatically chooses the IP interface through which the REST consumer is reachable.

A local IP interface for a REST consumer may be changed while the consumer is operationally up, but the new IP interface will only be used for new consumer connections—existing consumer connections will be unaffected.

Configuring REST Consumer Authentication Schemes

To configure an authentication scheme that the given REST consumer will use to establish a connection to the REST host, enter the following CONFIG command:

solace(...ry-point/rest-consumer/authentication)# auth-scheme {none | http-basic | client-certificate | http-header | oauth-client | oauth-jwt | transparent | aws}

Where:

  • none specifies to login with no authentication. For more information, see None.

  • http-basic specifies to login with a username and optional password. For more information, see HTTP Basic Authentication.

  • client-certificate specifies to login with a client TLS certificate. For more information, see Client Certificate Authentication.

  • http-header specifies to login with a specified HTTP header. For more information, see HTTP Header Authentication.

  • oauth-client specifies to login with OAuth 2.0 client credentials. For more information, see OAuth Client Authentication.

  • oauth-jwt specifies to login with an OAuth JWT profile. For more information, see OAuth JWT Authentication.

  • transparent specifies to login using the Authorization header from the message properties, if present. For more information, see Transparent Authentication.

  • aws specifies to login with AWS Signature Version 4 authentication (AWS4-HMAC-SHA256). For more information, see AWS Authentication.

The no version of the auth-scheme command, no auth-scheme, resets the authentication scheme setting to its default value of none.

None

If no authentication scheme for a REST consumer is configured, the REST consumer will not use an authentication scheme. This may be useful for anonymous connections or when a REST consumer does not require authentication.

HTTP Basic Authentication

Using the HTTP basic authentication scheme, REST consumers can authenticate with a username and password combination carried over HTTP. Credentials can either be transmitted using plain-text or encrypted with SSL.

To configure settings for an http-basic authentication scheme, enter the following CONFIG commands:

solace(...ry-point/rest-consumer/authentication)# http‑basic
solace(...st-consumer/authentication/http-basic)# username <name> [password <password>]

Where:

  • <name> is the client username to use for authentication with the REST host.

  • <password> is the optional password to be used with the specified username.

The no version of the username command, no username, removes any configured REST consumer authentication username and associated password.

Client Certificate Authentication

When using client certificate authentication, a REST consumer provides a certificate file to validate its identity. Client certificate authentication is only available to connections that use TLS/SSL.

To configure settings for a client certificate authentication scheme, enter the following CONFIG commands:

solace(...ry-point/rest-consumer/authentication)# client-certificate
solace(...mer/authentication/client-certificate)# certificate-file <filename>

Where:

  • <filename> is the filename of the certificate file. The certificate file must be located in the certs folder of the event broker. Once a certificate is configured, a copy of it is saved internally. The file in the certs directory is no longer required.

The no version of this command, no certificate-file, removes the certificate association for the current REST consumer.

  • The REST consumer certificate file can be changed at any time, but if the REST consumer is connected using client certificate authentication, changing the certificate will cause an interruption in service.
  • If no certificate is specified for a REST consumer using a client certificate authentication scheme, then the server certificate of the event broker is used instead.

HTTP Header Authentication

When using HTTP header authentication, a REST consumer uses a specified HTTP header to login to the REST host.

If the corresponding Message VPN is in gateway mode, the specified HTTP header will override all headers of the same name passed through with the message, resulting in a single header of that name on the outgoing request. For more information about the REST VPN mode, see Configuring the REST Message VPN Mode.

To configure the name of the authentication header, enter the following commands:

solace(...ry-point/rest-consumer/authentication)# http-header
solace(...t-consumer/authentication/http-header)# name <name>

To configure the value of the authentication header, enter the following commands:

solace(...ry-point/rest-consumer/authentication)# http-header
solace(...t-consumer/authentication/http-header)# value <http-header-value>

Where:

  • <name> is the authentication header name (of up to 50 characters) that the REST Consumer uses to login to the REST host. Authentication header names must be validated as per RFC 7230, which specifies that the header name must be a valid token. If the authentication header name is not configured, no header is sent.

  • <http-header-value> is the authentication header value (of up to 2100 characters) that the REST Consumer uses to login to the REST host. The value of the authentication header must consist of visible ASCII characters or ASCII whitespace, in other words ASCII values 9 and 32 to 126. If the authentication header value is not configured, the named header is sent with an empty value.

For an example, see how HTTP Header Authentication is used to Connecting to Azure Event Hubs or Azure Service Bus Using REST.

OAuth Client Authentication

When using OAuth client authentication, a REST consumer obtains access tokens from an authorization server using the Client Credentials Grant flow (RFC 6749 §4.4), also known as two-legged OAuth. In this flow, a simple HTTP request with basic authentication is sent to the authorization server to get an access token. The REST consumer can then use the returned access token to make authenticated requests to the REST host until it expires (tokens are usually valid for an hour). When the token is near expiry, the REST consumer will automatically request another.

There are no redirects or refresh tokens using this method, however, before configuring OAuth client authentication you must obtain primary credentials for the REST consumer (a client ID and client secret) that it will use with HTTP basic authentication to the authorization server when requesting an access token. In most cases, this is accomplished by creating a special account called a service account in the OAuth identity provider.

To enable OAuth client authentication, you must configure the client ID, client secret, and token endpoint that the REST consumer will use to request access tokens. Optionally, you can also configure the scope, default expiry time for tokens, and specify that the token requests go through a forward proxy.

To configure these settings, enter the following commands:

solace(...ry-point/rest-consumer/authentication)# oauth-client
solace(...-consumer/authentication/oauth-client)# client-id <client-id>
solace(...-consumer/authentication/oauth-client)# client-secret <client-secret>
solace(...-consumer/authentication/oauth-client)# token-endpoint <token-endpoint>
solace(...-consumer/authentication/oauth-client)# scope <scope>
solace(...-consumer/authentication/oauth-client)# token-expiry-default <value>
solace(...-consumer/authentication/oauth-client)# proxy <proxy-name>

Where:

  • client-id <client-id> is the OAuth client ID the REST consumer uses to login to the authorization server when requesting access tokens. The OAuth client ID may contain up to 200 characters.

  • client-secret <client-secret> is the OAuth client secret the REST consumer uses to login to the authorization server when requesting access tokens. The OAuth client secret may contain up to 200 characters.

  • token-endpoint <token-endpoint> is the OAuth token endpoint URL that the REST consumer uses to request a token for login to the REST host. The OAuth token endpoint may contain up to 2048 characters. In addition, the token endpoint parameter must use TLS, that is, it must start with https:// (case insensitive).

  • (Optional) scope <scope> is the OAuth scope. The OAuth scope may contain up to 200 characters.

  • (Optional) token-expiry-default <value> is the default expiry time for tokens, in seconds. The valid range is from 60 to 86400, the default is 900. This value is used only when the token endpoint does not return an expiry time.

  • (Optional) proxy <proxy-name> is the name of a forward proxy configured on the Message VPN. For more information, see Configuring a Forward Proxy. The specified proxy must be available on the management network. In addition, be aware that the proxy configured for a REST Consumer (see Proxy) and the proxy settings on individual REST Consumer authentication methods are independent. In other words, the REST Consumer proxy setting doesn't affect REST Consumer authentication proxy settings and vice-versa.

OAuth client authentication settings can only be configured while the REST consumer is shutdown.

For example, to configure the REST consumer to send a request to the https://login.microsoftonline.com/solace.com/oauth2/v2.0/token token endpoint using the client id of 3d69f5d8-77c9-4f25-9d22-aad25c737aa0 with the client secret of vkYDeFI[gUml-tX=7=5ybBGP22fF/@5O and specifying a scope of https://eventhubs.azure.net/.default, enter the following commands:

solace(...ry-point/rest-consumer/authentication)# oauth-client
solace(...-consumer/authentication/oauth-client)# client-id 3d69f5d8-77c9-4f25-9d22-aad25c737aa0
solace(...-consumer/authentication/oauth-client)# client-secret vkYDeFI[gUml-tX=7=5ybBGP22fF/@5O
solace(...-consumer/authentication/oauth-client)# token-endpoint https://login.microsoftonline.com/solace.com/oauth2/v2.0/token
solace(...-consumer/authentication/oauth-client)# scope https://eventhubs.azure.net/.default

The resulting request to the authorization server would then look like this:

POST /solace.com/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Authorization: Basic M2Q2OWY1ZDgtNzdjOS00ZjI1LTlkMjItYWFkMjVjNzM3YWEwOnZrWURlRklbZ1VtbC10WD03PTV5YkJHUDIyZkYvQDVP
Content-Length: 80
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=https%3A%2F%2Feventhubs.azure.net%2F.default

OAuth JWT Authentication

When using OAuth JWT authentication, instead of authenticating to the token endpoint with HTTP basic authentication using a client ID and client secret (as with OAuth client authentication), the REST consumer creates an appropriate signed JWT with a secret key, and then requests a token from the token endpoint using the JWT. The REST consumer can then use the returned access token (or ID token if that is returned) to make authenticated requests to the REST host until it expires (tokens are usually valid for an hour). When the token is near expiry, the REST consumer will automatically request another. For more information, see RFC 7523.

There are no redirects or refresh tokens using this method, however, before configuring OAuth JWT authentication you must obtain a secret key for the REST consumer that it will use to create the signed JWT. In most cases, you can obtain a secret key by creating a special account called a service account in the OAuth identity provider.

To enable OAuth JWT authentication, configure a JWT secret key, token endpoint, and any optional additional claims that the REST consumer will use to request access tokens. You can also configure the default expiry time for tokens. In addition, you can optionally specify that the token requests go through a forward proxy.

To configure these settings, enter the following commands:

solace(...ry-point/rest-consumer/authentication)# oauth-jwt
solace(...est-consumer/authentication/oauth-jwt)# secret-key <value>
solace(...est-consumer/authentication/oauth-jwt)# token-endpoint <value>
solace(...est-consumer/authentication/oauth-jwt)# create claim <name> <value>
solace(...est-consumer/authentication/oauth-jwt)# token-expiry-default <value>
solace(...est-consumer/authentication/oauth-jwt)# proxy <proxy-name>

Where:

  • secret key <value> is a PEM-encoded PKCS #8 private key that is used to sign the JWT for the OAuth token request. The secret key must be a multiline base64 encoded private key with embedded line feeds and be quoted in the form "-----BEGIN PRIVATE KEY-----\n<base64 data>\n-----END PRIVATE KEY-----\n".The secret key may contain up to 4096 characters.

  • token-endpoint <value> is the OAuth token endpoint URL that the REST consumer uses to request a token for login to the REST host. The OAuth token endpoint may contain up to 2048 characters. In addition, the token endpoint parameter must use TLS, that is, it must start with https:// (case insensitive).

  • claim <name> is the name of the additional claim. The claim name may contain up to 100 characters, however it cannot be exp, iat, or jti. These claims, referring to expires, issued-at-time, and jwt-ID are already included by default. You can configure up to 4 additional claims per RDP. The total number of claims you can configure for the event broker as a whole depends on the broker's scale: for a 100-connection software event broker, you can configure up to 80 claims; for any other scale (including the appliance), you can configure a maximum of 800 total claims.

  • claim <value> is the value of the additional claim. The claim value must be valid JSON and may contain up to 200 characters. If you want to enter a string for the claim value, you must use the following format \"myClaimValue\" (see the example below).

  • token-expiry-default <value> is the default expiry time for tokens, in seconds. The valid range is from 60 to 86400, the default is 900. This value is used only when the token endpoint does not return an expiry time.

  • (Optional) proxy <proxy-name> is the name of a forward proxy configured on the Message VPN. For more information, see Configuring a Forward Proxy. The specified proxy must be available on the management network. In addition, be aware that the proxy configured for a REST Consumer (see Proxy) and the proxy settings on individual REST Consumer authentication methods are independent. In other words, the REST Consumer proxy setting doesn't affect REST Consumer authentication proxy settings and vice-versa.

OAuth JWT authentication settings can only be configured while the REST consumer is shutdown.

For example, to configure the REST consumer to send a request to the https://oauth2.googleapis.com/token token endpoint, specifying claims of iss=111400995554822290197, sub=111400995554822290197, scope=https://www.googleapis.com/auth/pubsub, and aud=https://oauth2.googleapis.com/token enter the following commands:

solace(...ry-point/rest-consumer/authentication)# oauth-jwt
solace(...est-consumer/authentication/oauth-jwt)# secret-key "-----BEGIN PRIVATE KEY-----\n<base64 data>\n-----END PRIVATE KEY-----\n"
solace(...est-consumer/authentication/oauth-jwt)# token-endpoint https://oauth2.googleapis.com/token
solace(...est-consumer/authentication/oauth-jwt)# create claim scope "\"https://www.googleapis.com/auth/pubsub\""
solace(...est-consumer/authentication/oauth-jwt)# create claim iss "\"111400995554822290197\""
solace(...est-consumer/authentication/oauth-jwt)# create claim sub "\"111400995554822290197\""
solace(...est-consumer/authentication/oauth-jwt)# create claim aud "\"https://oauth2.googleapis.com/token\""

The resulting request to the authorization server would then look like this:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Authorization: Basic ...

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=...

Transparent Authentication

When using transparent authentication, a REST consumer uses the Authorization header from the message properties to login to the REST host. In other words, the REST consumer passes along existing Authorization header metadata instead of discarding it.

If the message is coming from a REST producer, the REST service must be configured to forward the Authorization header. For more information, refer to Configuring Authorization Header Handling .

Transparent authentication should only be used in specific deployment scenarios. We recommend that you contact Solace before enabling this authentication scheme.

AWS Authentication

When using AWS authentication, a REST consumer uses AWS Signature Version 4 authentication (AWS4-HMAC-SHA256) to login to the REST host. You can use this authentication mechanism to enable RDPs to communicate with most AWS services.

To enable AWS authentication, you must configure the AWS access key ID, secret access key, region, and service that the REST consumer will use to login to the host.

The AWS access key ID and secret access key are the API credentials for the AWS user.

To configure these settings, enter the following commands:

solace(...ry-point/rest-consumer/authentication)# aws
solace(...oint/rest-consumer/authentication/aws)# access-key-id <access-key-id>
solace(...oint/rest-consumer/authentication/aws)# secret-access-key <secret-access-key>
solace(...oint/rest-consumer/authentication/aws)# region <region>
solace(...oint/rest-consumer/authentication/aws)# service <service>

Where:

  • <access-key-id> is the AWS access key ID.

  • <secret-access-key> is the AWS secret access key.

  • <region> is the AWS region, such as us-east-1, ca-central-1, or ap-southeast-1.

  • <service> is the service to be invoked, such as s3.

For example, to configure the REST consumer to login to the AWS Simple Storage Service (s3) in the us-east-1 region using AKIAIOSFODNN7EXAMPLE AWS as the access key ID and wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY as the secret access key, enter the following commands:

solace(...ry-point/rest-consumer/authentication)# aws
solace(...oint/rest-consumer/authentication/aws)# access-key-id AKIAIOSFODNN7EXAMPLE
solace(...oint/rest-consumer/authentication/aws)# secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
solace(...oint/rest-consumer/authentication/aws)# region us-east-1
solace(...oint/rest-consumer/authentication/aws)# service s3

Configuring REST Consumer TLS/SSL Parameters

To configure TLS/SSL parameters for the current REST consumer, enter the following CONFIG command:

solace(...est/rest-delivery-point/rest-consumer)# ssl

The CLI enters the REST consumer SSL configuration level, from which you may configure the following parameters:

Cipher Suite

You can configure the list of cipher suites that are used to encrypt connections from the event broker to a host. By default, all cipher suites are included in the list, ordered from most to least secure.

To use the default list of cipher suites, enter the following CONFIG command:

solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite default

To modify the cipher suite list, do the following:

  • To empty the cipher suite list, enter the following REST VPN CONFIG command: 
    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite empty
  • To add a cipher suite to the list, enter the following REST VPN CONFIG command: 
    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite name <suite-name>
  • To add a cipher suite at a specific point in the list, use the following REST VPN CONFIG command: 
    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite name <suite-name> [before|after <existing‑suite‑name>]

Where:

  • <suite-name> is a string identifying the cipher suite to be added to the list. If no ‘before’ or ‘after’ keyword is specified, the cipher suite is added at the end of the list.

  • before specifies that the cipher suite should be added before the cipher suite indicated by <existing-suite-name>.

  • after specifies that the cipher suite should be added after the cipher suite indicated by <existing-suite-name>.

  • <existing-suite-name> is the name of a cipher suite that is already on the list. The cipher suite being entered will be positioned before or after the existing suite name, depending on whether the before or after keyword was specified.

The no version of this command, cipher-suite name <suite-name>, removes the specified cipher suite from the configured list.

The cipher suite list can only be configured while the REST consumer is shutdown.

Enabling Server Name Validation

You can enable or disable the TLS authentication mechanism to verify the name used to connect to the remote server. 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 broker.

Server name validation is enabled by default and should remain enabled in all production scenarios.

To enable server name validation, enter the following command:

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

To disable server name validation:

solace(...est/ssl/server-certificate-validation)# no validate-server-name

For information on configuring CA certificates, refer to Configuring Certificate Authorities.

Enabling REST Consumers

  • To enable the given REST consumer, enter the following CONFIG command: 
    solace(...est/rest-delivery-point/rest-consumer)# no shutdown
  • To disable the given REST consumer, enter the following CONFIG command: 
    solace(...est/rest-delivery-point/rest-consumer)# shutdown

    When a REST consumer is disabled, no connections can be initiated and no messages can be delivered to it.

Enabling REST Delivery Points

  • To enable the given RDP, enter the following CONFIG command: 
    solace(.../message-vpn/rest/rest-delivery-point)# no shutdown
  • To disable the given RDP, enter the following CONFIG command: 
    solace(.../message-vpn/rest/rest-delivery-point)# shutdown

    When disabled, no connections will be initiated and the RDP will not deliver messages to any of the contained REST consumers.