跳到主要内容

管理REST交付点

REST 交付点（RDP）是消息 VPN 上的一个配置对象，用于促进消息向 REST 消费者的传递。RDP 与消息 VPN 上的客户端配置文件相关联，该配置文件为其提供一些配置参数。RDP 可以绑定到消息队列，以便将这些队列中的消息传递给 REST 消费者。RDP 维护一个 REST 消费者列表，这些消费者通过其远程连接信息进行标识。

您可以为 RDP 执行以下配置任务：

  • 配置 REST 交付点
  • 将客户端配置文件与 REST 交付点关联
  • 管理 REST 交付点队列绑定
  • 配置 REST 消费者
  • 启用 REST 交付点

配置REST交付点​

  • 要为给定的消息 VPN 创建 RDP，请输入以下 CONFIG 命令：

    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# rest
    solace(configure/message-vpn/rest)# create rest-delivery-point <name>

  • 要编辑现有 RDP 的属性，请输入以下 CONFIG 命令：

    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# rest
    solace(configure/message-vpn/rest)# rest-delivery-point <name>

    其中：

    • <name> 是 RDP 的名称。RDP 名称最多可为 100 个字符，并且必须在给定的消息 VPN 内是唯一的。

    此命令的 no 版本 no rest-delivery-point 将删除指定的 RDP 及其所有相关配置。

    输入 rest-delivery-point REST VPN CONFIG 命令后，CLI 将进入 RDP 配置模式，您可以执行以下任务：

    • 将客户端配置文件与 REST 交付点关联
    • 管理 REST 交付点队列绑定
    • 配置 REST 消费者
    • 启用 REST 交付点

    有关 RDP 限制的详细信息，请参阅 Solace 产品网站上相关代理版本文件夹中的 _SolacePubSub_<version>_limits_and_alerts_ 电子表格。要访问 Solace 产品网站，请使用 Solace 提供的用户名和密码或您的 SSO 登录。如果您在访问网站时遇到问题，请联系 Solace。

将客户端配置文件与REST交付点关联​

当 RDP 与现有客户端配置文件关联时，RDP 继承该客户端配置文件的 TCP 参数和队列属性（max-depth 和 min-msg-burst）。从客户端配置文件继承的 TCP 参数将用于交付点上的所有 REST 消费者。

除非在关联的客户端配置文件上启用了 allow-guaranteed-message-receive，否则不能启用 RDP。

要将客户端配置文件与给定的 RDP 关联，请输入以下 CONFIG 命令：

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

其中：

  • <name> 是本地消息 VPN 中已存在的客户端配置文件的名称。默认情况下，如果没有客户端配置文件与 RDP 关联，则将使用当前消息 VPN 的名为 default 的客户端配置文件。

此命令的 no 版本 no client-profile 将从 RDP 中移除客户端配置文件关联，并为当前消息 VPN 分配 default 客户端配置文件。

管理REST交付点队列绑定​

RDP 必须绑定到一个或多个持久队列，以便从队列中吸引消息并将其传递给 REST 消费者。

  • 要将给定的 RDP 绑定到队列，请输入以下 CONFIG 命令：

    solace(.../message-vpn/rest/rest-delivery-point)# create queue-binding <queue-name>

  • 要编辑现有队列绑定的属性，请输入以下 CONFIG 命令：

    solace(.../message-vpn/rest/rest-delivery-point)# queue-binding <queue‑name>

    其中：

    • <queue-name> 是要绑定到当前 RDP 的给定消息 VPN 中的队列名称。队列名称最多可包含 200 个字符（唯一无效的字符是 '<>*?&;'）。

    此命令的 no 版本 no queue-binding 将删除当前 RDP 的指定队列绑定。然而，它不会删除队列。

    • 您可以指定绑定到不存在的队列，但在 RDP 可以投入使用之前，必须创建引用的队列。也就是说，在与 RDP 相同的消息 VPN 中必须存在与队列绑定同名的队列。RDP 还必须有权限从队列中消费消息——要实现这一点，队列的所有者必须设置为 #rdp/<rdp-name>，或者队列对非所有者客户端的权限必须至少设置为消费级别访问权限。有关配置队列的更多信息，请参阅配置队列。
    • 可以创建的队列绑定的最大数量与事件代理支持的队列的最大数量相同。

queue-binding REST VPN CONFIG 命令将 CLI 移动到 REST 交付点队列绑定级别：

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

从这个级别，您可以为给定的队列绑定配置 POST 请求目标。

配置POST请求目标​

与队列绑定关联的 POST 请求目标用于发送到 REST 消费者的 HTTP POST 请求中，并标识远程 REST 消费者上消息传递的目标资源。在为队列绑定配置 POST 请求目标之前，无法从队列向 REST 消费者传递消息。有关请求目标的更多信息，请参阅 RFC 7230 §5.3。

要为队列绑定配置 POST 请求目标，请输入以下 CONFIG 命令：

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

其中：

  • <post-request-target> 是一个字符串，包含要与当前队列绑定关联的 POST 请求目标。

此命令的 no 版本 no post-request-target 将从当前队列绑定中移除 POST 请求目标。

如果包含 RDP 的消息 VPN 被配置为作为 Microgateway 运行，则 POST 请求目标将被忽略。

配置对POST请求目标执行的评估类型​

通过 RDP 将消息转发到外部系统时，通常需要访问该外部系统上的消息主题和其他元数据。例如，您可能希望使用 RDP 将消息发送到存储服务，如 Azure Storage、Amazon S3 或 Google Cloud Storage。这需要将每条消息发送到一个独特的目标，最好是从消息主题、元数据或当前时间获得这种独特性。为此，您可以在 POST 请求目标中包含替换表达式，并配置事件代理以评估这些表达式。有关替换表达式的更多信息，请参阅替换表达式概述。

要配置对请求目标执行的评估类型，请输入以下 CONFIG 命令：

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}

其中：

  • <post-request-target> 是一个字符串，包含要与当前队列绑定关联的 POST 请求目标。
  • none 配置事件代理不对请求目标上的替换表达式进行评估。这是默认设置。
  • substitution-expressions 配置事件代理对请求目标上的替换表达式进行评估。

此命令的 no 版本 no request-target-evaluation 将值重置为默认值。

配置请求头​

通过 RDP 将消息转发到外部系统时，通常需要访问该外部系统上的消息主题和其他元数据。通过为队列绑定配置请求头，您可以将元数据（例如 ASAPIO 的 SAP 对象 ID）放入请求头中。此外，您可以配置事件代理以发送云服务（如 Azure Storage 和 AWS EventBridge）所需的特定头。

要为队列绑定创建请求头，请输入以下 CONFIG 命令：

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

要为请求头配置值，请输入以下 CONFIG 命令：

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

其中：

  • <header-name> 是一个字符串，包含要与当前队列绑定关联的 HTTP 请求头的名称。头名称必须符合 RFC 7230 §3.2.6 中的标记生产。以下头不允许：Authorization、Connection、Content-Length、Expect、Transfer-Encoding 和 Upgrade。请求头名称最多可包含 50 个字符。
  • <header-value> 是一个字符串，包含 HTTP 请求头值的替换表达式。默认值为空字符串。请求头值最多可包含 2000个字符。有关替换表达式的更多信息，请参阅替换表达式概述。

在队列绑定上指定的头将替换所有同名的头（不区分大小写），这些头是从 SMF 用户属性或从其他元数据生成的。这些头还优先于 HTTP 头身份验证中描述的头。

例如，要配置队列绑定以发送特定云服务所需的两个额外头，您可以输入以下命令：

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

在这种情况下，对于主题为 orders/hw/update/v2/can/C-1234/P-E7Y1/O-6789 的消息，请求中将添加以下头：X-ORDER-ID: O-6789 和 x-api-version: 2021-02-03。

有关请求头限制的详细信息，请参阅 Solace 产品网站上相关代理版本文件夹中的 SolacePubSub<version>limits_and_alerts 电子表格。要访问 Solace 产品网站，请使用 Solace 提供的用户名和密码或您的 SSO 登录。如果您在访问网站时遇到问题，请联系 Solace。

当请求头的值是敏感的时，应使用受保护的请求头而不是普通请求头。与普通请求头一样，每个受保护的请求头由头名称和头值组成。一旦设置，受保护的请求头值将被屏蔽，无法在管理界面和日志中查看，类似于密码。

受保护的请求头和普通请求头共享一个共同的限制，即可以配置的请求头总数，并且不可能创建具有相同名称的受保护请求头和普通请求头。

受保护的请求头不支持替换表达式（有关替换表达式的更多信息，请参阅替换表达式概述）。

要为队列绑定创建受保护的请求头，请输入以下 CONFIG 命令：

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

要为受保护的请求头配置值，请输入以下 CONFIG 命令：

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

其中：

  • <header-name> 和 <header-value> 与普通请求头具有相同的含义。

例如，要配置队列绑定以发送特定云服务所需的 API 密钥头，您可以输入以下命令：

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

在这种情况下，请求中将添加以下头：X-API-KEY: 0aa99f00-b752-4bb9-b549-c168ad250e76。

替换出站统一资源标识符（URIs）中的权限值​

当消息 VPN 被配置为作为 Microgateway 运行时，事件代理将以绝对形式传播 HTTP 请求，并从 REST 消费者的远程主机和端口配置中检索请求目标的权威。您可以选择禁用此功能，并配置事件代理使用原始请求中配置的权威。

要配置事件代理使用原始请求中的权威值，请输入以下 CONFIG 命令：

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

要配置事件代理将权威替换为为 REST 消费者配置的值，请输入以下 CONFIG 命令：

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

仅当相应的消息 VPN 被配置为作为 Microgateway 运行时，才能替换出站 URI 中的权威值。

配置REST消费者​

REST 消费者是客户端或端点的虚拟表示。RDP 维护一个 REST 消费者列表，消息可以传递到这些消费者。

  • 要在当前 RDP 中创建 REST 消费者，请输入以下 CONFIG 命令：

    solace(.../message-vpn/rest/rest-delivery-point)# create rest-consumer <name>

  • 要编辑现有 REST 消费者，请输入以下 CONFIG 命令：

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

    其中：

    • <name> 是指定的 REST 消费者的名称。REST 消费者名称最多可包含 32 个字符。

    此命令的 no 版本 no rest-consumer <name> 将删除指定的 REST 消费者及其所有配置。

    输入 rest-consumer REST VPN CONFIG 命令后，CLI 将进入 REST 消费者配置模式，您可以执行以下任务：

    • 为 REST 消费者配置远程连接信息
    • 为 REST 消费者配置特定 IP 接口
    • 配置 REST 消费者身份验证方案
    • 配置 REST 消费者 TLS/SSL 参数
    • 启用 REST 消费者

    有关 REST 消费者限制的详细信息，请参阅 Solace 产品网站上相关代理版本文件夹中的 SolacePubSub<version>limits_and_alerts 电子表格。要访问 Solace 产品网站，请使用 Solace 提供的用户名和密码或您的 SSO 登录。如果您在访问网站时遇到问题，请联系 Solace。

为REST消费者配置远程连接信息​

要为给定的 REST 消费者配置远程连接信息，请输入以下 REST VPN CONFIG 命令：

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

CLI 进入消息 VPN 远程 REST 消费者级别，您可以为当前 REST 消费者配置以下远程连接属性：

  • 主机
  • 端口
  • 代理
  • SSL
  • HTTP 方法
  • 出站连接数
  • 最大 POST 等待时间
  • 重试

REST 消费者的远程连接参数只能在 REST 消费者关闭时进行配置。

主机​

要配置或重置事件代理将连接到的 IP 地址或 DNS 名称，以便它可以为给定的 REST 消费者传递消息，请输入以下 CONFIG 命令：

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

其中：

  • <dest-ip-addr-or-host> 是事件代理将连接到的 IP 地址或 DNS 名称，以便为当前 REST 消费者传递消息，它可以包含多达 253 个字符。

除了 IPv4 地址或 DNS 名称外，如果事件代理的消息骨干配置了 IPv6 全局单播或唯一本地地址，您还可以指定 IPv6 地址。有关更多信息，请参阅配置设备 IP 接口或软件事件代理的 IP 接口配置。

如果您指定 DNS 名称，并且在查找过程中返回了 IPv4 和 IPv6 地址，则事件代理将根据配置的 DNS 服务器指定的优先级选择 IP 地址。有关更多信息，请参阅 DNS 名称查找。

此命令的 no 版本 no host 将主机设置重置为其默认值（空）。如果 REST 消费者已启用但没有配置主机值，则它将处于操作 Down 状态，直到设置了有效的主机值。

主机值只能在 REST 消费者关闭时配置。

端口​

要配置与当前 REST 消费者的主机一起使用的端口，请输入以下 CONFIG 命令：

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

其中：

  • <port> 是所需的端口号。可接受的值是从 1 到 65535 的数字。

此命令的 no 版本 no port 将端口值重置为默认值。默认值为明文连接的 8080 和 SSL 连接的 8443。

代理​

根据您的部署情况，您可能需要 REST 消费者与终端服务器（如外部网站）之间的通信通过正向代理进行。如果您的事件代理位于防火墙之后，且出站流量需要连接到代理服务器以穿越防火墙，则通常会出现这种情况。

要为当前 REST 消费者配置正向代理，请输入以下命令：

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

其中：

  • <proxy-name> 是在消息 VPN 上配置的正向代理的名称。有关更多信息，请参阅配置正向代理。为 REST 消费者配置的代理和各个 REST 消费者身份验证方法上的代理设置是独立的。换句话说，此代理设置不影响 REST 消费者身份验证代理设置，反之亦然。

此命令的 no 版本 no proxy 将移除任何已配置的代理。

SSL​

要启用或禁用当前 REST 消费者的 SSL 连接，请输入以下 CONFIG 命令：

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

此命令的 no 版本 no ssl 将禁用当前 REST 消费者的 SSL 连接。

HTTP 方法​

默认情况下，PubSub+ 事件代理在向远程端点传递消息时使用 POST HTTP 方法。您可以改为指定传出消息应使用 PUT 方法。更改 HTTP 方法允许您将事件代理连接到不支持 POST 方法的端点（例如，某些云原生数据湖产品）。

要配置传出连接使用的 HTTP 方法，请输入以下 CONFIG 命令：

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

其中：

  • post 指定在向远程端点传递消息时使用 POST HTTP 方法。
  • put 指定在向远程端点传递消息时使用 PUT HTTP 方法。
  • 此命令的 no 版本 no http-method 将设置重置为默认值（POST）。

如果相应的消息 VPN 处于网关模式，则指定的 HTTP 方法将被忽略，因为传入的方法（GET、PUT、POST、DELETE、PATCH、HEAD、OPTIONS）将通过代理传递。有关 REST 消息 VPN 模式的更多信息，请参阅配置 REST 消息 VPN 模式。

出站连接数​

要设置事件代理发起的、打开到给定 REST 消费者的并发 TCP 连接总数，请输入以下 CONFIG 命令：

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

其中：

  • <count> 是到此 REST 消费者的传出连接总数（因此也是 HTTP POST 操作），代理可以发起。有效值在 1 到 50（含）之间。

此命令的 no 版本 no outgoing-connection-count 将传出连接计数参数重置为默认值 3。

最大 POST 等待时间​

事件代理等待 REST 消费者响应的最大时间是有限的。

如果操作已经超出了配置的最大等待时间，TCP 连接将被重置。如果请求是非持久消息，则消息将被丢弃。如果请求是持久消息，则将通过 RDP 的另一个可用传出连接重新尝试消息传递，直到队列上的最大传递次数。如果超过最大传递次数，并且消息符合死信队列（DMQ）的条件，则消息将被移动到 DMQ，否则将被丢弃。

要设置最大等待时间，请输入以下 CONFIG 命令：

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

其中：

  • <seconds> 是等待来自未完成操作的响应的时间（以秒为单位）。有效范围是从 1 到 300。

此命令的 no 版本 no max-post-wait-time 将最大等待时间参数重置为默认值 30。

重试​

要配置重试延迟（即，在重试连接尝试之前应经过的时间），请输入以下 CONFIG 命令：

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

其中：

  • <seconds> 是在重试连接尝试之前必须经过的时间（以秒为单位）。有效范围是从 1 到 300。

此命令的 no 版本 no delay 将重试延迟重置为默认值 3。

如果包含 RDP 的消息 VPN 被配置为作为 Microgateway 运行，则将忽略重试延迟。

为REST消费者配置特定IP接口​

默认情况下，事件代理会自动选择 REST 消费者出站连接所使用的 IP 接口。

然而，如果您的环境需要固定的 IP 接口，也可以为 REST 消费者配置特定的接口。当配置了特定的 IP 接口时，所有与 REST 消费者相关的连接的传出数据包中指定的源 IP 地址将相同。例如，如果客户端应用程序和事件代理之间使用了防火墙，则可能需要固定 IP 接口。在这种情况下，必须配置防火墙以允许事件代理的源 IP 地址通过，因此自动选择的 IP 接口可能会带来问题。

如果为 REST 消费者配置了本地 IP 接口，则该配置将被传播，如果使用了 Config-Sync 和/或复制功能。因此，您必须确保指定的接口在所有将被同步和/或复制的消息 VPN 上都可用，或者您应该使用默认行为，即事件代理自动选择 IP 接口。

要为给定的 REST 消费者配置特定的本地 IP 接口以用于所有相关的传出连接，请输入以下 CONFIG 命令：

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

其中：

  • <phys-intf> 是一个 ASCII 字符串，指定本地设备上用于所有与给定 REST 消费者相关的传出连接的物理以太网接口端口或 LAG。有效值为 eth<port>（例如，eth1）；chassis/lag1；<cartridge>/<slot>/<port>（例如，1/1/8）；<cartridge>/<slot>/lag<N>（例如，1/1/lag1）。仅支持编号为 1 的单个 LAG。

此命令的 no 版本 no interface 将移除任何已配置的本地 IP 接口，并恢复默认行为，即事件代理自动选择 REST 消费者可到达的 IP 接口。

可以在 REST 消费者操作性上线时更改 REST 消费者的本地 IP 接口，但新的 IP 接口仅用于新的消费者连接——现有的消费者连接将不受影响。

配置REST消费者身份验证方案​

要配置给定 REST 消费者将用于与 REST 主机建立连接的身份验证方案，请输入以下 CONFIG 命令：

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

其中：

  • none 指定无需身份验证即可登录。有关更多信息，请参阅无身份验证。
  • http-basic 指定使用用户名和可选密码登录。有关更多信息，请参阅 HTTP 基本身份验证。
  • client-certificate 指定使用客户端 TLS 证书登录。有关更多信息，请参阅客户端证书身份验证。
  • http-header 指定使用指定的 HTTP 头登录。有关更多信息，请参阅 HTTP 头身份验证。
  • oauth-client 指定使用 OAuth 2.0 客户端凭据登录。有关更多信息，请参阅 OAuth 客户端身份验证。
  • oauth-jwt 指定使用 OAuth JWT 配置文件登录。有关更多信息，请参阅 OAuth JWT 身份验证。
  • transparent 指定使用消息属性中的 Authorization 头登录（如果存在）。有关更多信息，请参阅透明身份验证。
  • aws 指定使用 AWS 签名版本 4 身份验证（AWS4-HMAC-SHA256）登录。有关更多信息，请参阅 AWS 身份验证。

auth-scheme 命令的 no 版本 no auth-scheme 将身份验证方案设置重置为其默认值无。

无身份验证​

如果未为 REST 消费者配置身份验证方案，则 REST 消费者将不使用身份验证方案。这可能适用于匿名连接或 REST 消费者不需要身份验证的情况。

HTTP 基本身份验证​

使用 HTTP 基本身份验证方案时，REST 消费者可以使用通过 HTTP 传输的用户名和密码组合进行身份验证。凭据可以使用明文传输，也可以使用 SSL 加密。

要配置 HTTP 基本身份验证方案的设置，请输入以下 CONFIG 命令：

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

其中：

  • <name> 是用于与 REST 主机进行身份验证的客户端用户名。
  • <password> 是与指定用户名一起使用的可选密码。

用户名命令的 no 版本 no username 将移除任何已配置的 REST 消费者身份验证用户名及其关联密码。

客户端证书身份验证​

使用客户端证书身份验证时，REST 消费者提供证书文件以验证其身份。客户端证书身份验证仅适用于使用 TLS/SSL 的连接。

要配置客户端证书身份验证方案的设置，请输入以下 CONFIG 命令：

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

其中：

  • <filename> 是证书文件的文件名。证书文件必须位于事件代理的 certs 文件夹中。一旦配置了证书，就会在内部保存其副本。certs 目录中的文件不再需要。

此命令的 no 版本 no certificate-file 将移除当前 REST 消费者的证书关联。

  • 可以随时更改 REST 消费者的证书文件，但如果 REST 消费者使用客户端证书身份验证连接，则更改证书将导致服务中断。
  • 如果未为使用客户端证书身份验证方案的 REST 消费者指定证书，则将使用事件代理的服务器证书。

当使用 HTTP 头身份验证时，REST 消费者使用指定的 HTTP 头登录到 REST 主机。

如果相应的消息 VPN 处于网关模式，则指定的 HTTP 头将覆盖与消息一起传递的所有同名头，导致出站请求中只有一个该名称的头。有关 REST 消息 VPN 模式的更多信息，请参阅配置 REST 消息 VPN 模式。

要配置身份验证头的名称，请输入以下命令：

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

要配置身份验证头的值，请输入以下命令：

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

其中：

  • <name> 是 REST 消费者用于登录到 REST 主机的身份验证头名称（最多 50 个字符）。身份验证头名称必须根据 RFC 7230 进行验证，该标准规定头名称必须是有效的标记。如果未配置身份验证头名称，则不会发送头。
  • <http-header-value> 是 REST 消费者用于登录到 REST 主机的身份验证头值（最多 2100 个字符）。身份验证头的值必须由可见的 ASCII 字符或 ASCII 空白组成，即 ASCII 值 9 和 32 到 126。如果未配置身份验证头值，则将发送带有空值的命名头。

例如，请参阅如何使用 HTTP 头身份验证连接到 Azure Event Hubs 或 Azure Service Bus 使用 REST。

OAuth 客户端身份验证​

使用 OAuth 客户端身份验证时，REST 消费者使用客户端凭据授权流程（RFC 6749 §4.4），也称为两腿 OAuth，从授权服务器获取访问令牌。在此流程中，向授权服务器发送带有基本身份验证的简单 HTTP 请求以获取访问令牌。然后，REST 消费者可以使用返回的访问令牌对 REST 主机进行身份验证请求，直到它过期（令牌通常有效一小时）。当令牌即将过期时，REST 消费者将自动请求另一个。

此方法不使用重定向或刷新令牌，但在配置 OAuth 客户端身份验证之前，您必须获取 REST 消费者将用于向授权服务器请求访问令牌时的 HTTP 基本身份验证的主凭据（客户端 ID 和客户端密钥）。在大多数情况下，这是通过在 OAuth 身份提供者中创建一个名为服务帐户的特殊帐户来实现的。

要启用 OAuth 客户端身份验证，您必须配置 REST 消费者将用于请求访问令牌的客户端 ID、客户端密钥和令牌端点。可选地，您还可以配置范围、令牌的默认过期时间，并指定令牌请求通过正向代理。

要配置这些设置，请输入以下命令：

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>

其中：

  • client-id <client-id> 是 REST 消费者在请求访问令牌时用于登录授权服务器的 OAuth 客户端 ID。OAuth 客户端 ID 可以包含最多 200 个字符。
  • client-secret <client-secret> 是 REST 消费者在请求访问令牌时用于登录授权服务器的 OAuth 客户端密钥。OAuth 客户端密钥可以包含最多 200 个字符。
  • token-endpoint <token-endpoint> 是 REST 消费者用于请求登录到 REST 主机的令牌的 OAuth 令牌端点 URL。OAuth 令牌端点可以包含最多 2048 个字符。此外，令牌端点参数必须使用 TLS，即必须以 https:// 开头（不区分大小写）。
  • （可选）scope <scope> 是 OAuth 范围。OAuth 范围可以包含最多 200 个字符。
  • （可选）token-expiry-default <value> 是令牌的默认过期时间（以秒为单位）。有效范围是从 60 到 86400，默认为 900。当令牌端点未返回过期时间时，仅使用此值。
  • （可选）proxy <proxy-name> 是在消息 VPN 上配置的正向代理的名称。有关更多信息，请参阅配置正向代理。指定的代理必须在管理网络上可用。此外，请注意，为 REST 消费者配置的代理（请参阅代理）和各个 REST 消费者身份验证方法上的代理设置是独立的。换句话说，REST 消费者代理设置不影响 REST 消费者身份验证代理设置，反之亦然。

OAuth 客户端身份验证设置只能在 REST 消费者关闭时进行配置。

例如，要配置 REST 消费者向 https://login.microsoftonline.com/solace.com/oauth2/v2.0/token 令牌端点发送请求，使用客户端 ID 3d69f5d8-77c9-4f25-9d22-aad25c737aa0 和客户端密钥 vkYDeFI[gUml-tX=7=5ybBGP22fF/@5O，并指定范围 https://eventhubs.azure.net/.default，请输入以下命令：

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

向授权服务器发出的请求将如下所示：

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 身份验证​

使用 OAuth JWT 身份验证时，与 OAuth 客户端身份验证不同，REST 消费者不是使用客户端 ID 和客户端密钥通过 HTTP 基本身份验证对令牌端点进行身份验证，而是创建一个适当的签名 JWT，然后使用 JWT 从令牌端点请求令牌。然后，REST 消费者可以使用返回的访问令牌（或如果返回，则为 ID 令牌）对 REST 主机进行身份验证请求，直到它过期（令牌通常有效一小时）。当令牌即将过期时，REST 消费者将自动请求另一个。有关更多信息，请参阅 RFC 7523。

此方法不使用重定向或刷新令牌，但在配置 OAuth JWT 身份验证之前，您必须获取 REST 消费者将用于创建签名 JWT 的密钥。在大多数情况下，您可以通过在 OAuth 身份提供者中创建一个名为服务帐户的特殊帐户来获取密钥。

要启用 OAuth JWT 身份验证，请配置 JWT 密钥、令牌端点以及 REST 消费者将用于请求访问令牌的任何可选附加声明。您还可以配置令牌的默认过期时间。此外，您可以选择指定令牌请求通过正向代理。

要配置这些设置，请输入以下命令：

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>

其中：

  • secret key <value> 是用于为 OAuth 令牌请求签名 JWT 的 PEM 编码的 PKCS #8 私钥。密钥必须是具有嵌入换行符的多行 base64 编码私钥，并以 "-----BEGIN PRIVATE KEY-----\n<base64 data>\n-----END PRIVATE KEY-----\n" 的形式进行引用。密钥可以包含最多 4096 个字符。
  • token-endpoint <value> 是 REST 消费者用于请求登录到 REST 主机的令牌的 OAuth 令牌端点 URL。OAuth 令牌端点可以包含最多 2048 个字符。此外，令牌端点参数必须使用 TLS，即必须以 https:// 开头（不区分大小写）。
  • claim <name> 是附加声明的名称。声明名称可以包含最多 100 个字符，但不能是 exp、iat 或 jti。这些声明，指的是 expires、issued-at-time 和 jwt-ID，默认已包含。您可以为每个 RDP 配置最多 4 个附加声明。您可以为整个事件代理配置的声明总数取决于代理的规模：对于 100 连接的软件事件代理，您可以配置最多 80 个声明；对于任何其他规模（包括设备），您可以配置最多 800 个声明。
  • claim <value> 是附加声明的值。声明值必须是有效的 JSON，并且可以包含最多 200 个字符。如果您想输入字符串作为声明值，您必须使用以下格式 \"myClaimValue\"（请参阅下面的示例）。
  • token-expiry-default <value> 是令牌的默认过期时间（以秒为单位）。有效范围是从 60 到 86400，默认为 900。当令牌端点未返回过期时间时，仅使用此值。
  • （可选）proxy <proxy-name> 是在消息 VPN 上配置的正向代理的名称。有关更多信息，请参阅配置正向代理。指定的代理必须在管理网络上可用。此外，请注意，为 REST 消费者配置的代理（请参阅代理）和各个 REST 消费者身份验证方法上的代理设置是独立的。换句话说，REST 消费者代理设置不影响 REST 消费者身份验证代理设置，反之亦然。

OAuth JWT 身份验证设置只能在 REST 消费者关闭时进行配置。

例如，要配置 REST 消费者向 https://oauth2.googleapis.com/token 令牌端点发送请求，指定声明 iss=111400995554822290197、sub=111400995554822290197、scope=https://www.googleapis.com/auth/pubsub 和 aud=https://oauth2.googleapis.com/token，请输入以下命令：

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\""

向授权服务器发出的请求将如下所示：

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

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

透明身份验证​

使用透明身份验证时，REST 消费者使用消息属性中的 Authorization 头登录到 REST 主机。换句话说，REST 消费者传递现有的 Authorization 头元数据而不是丢弃它。

如果消息来自 REST 生产者，则必须配置 REST 服务以转发 Authorization 头。有关更多信息，请参阅配置 Authorization 头处理。

透明身份验证只应在特定的部署场景中使用。我们建议您在启用此身份验证方案之前与 Solace 联系。

AWS 身份验证​

使用 AWS 身份验证时，REST 消费者使用 AWS 签名版本 4 身份验证（AWS4-HMAC-SHA256）登录到 REST 主机。您可以使用此身份验证机制使 RDP 能够与大多数 AWS 服务进行通信。

要启用 AWS 身份验证，您必须配置 REST 消费者将用于登录主机的 AWS 访问密钥 ID、秘密访问密钥、区域和服务。

AWS 访问密钥 ID 和秘密访问密钥是 AWS 用户的 API 凭据。

要配置这些设置，请输入以下命令：

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>

其中：

  • <access-key-id> 是 AWS 访问密钥 ID。
  • <secret-access-key> 是 AWS 秘密访问密钥。
  • <region> 是 AWS 区域，例如 us-east-1、ca-central-1 或 ap-southeast-1。
  • <service> 是要调用的服务，例如 s3。

例如，要配置 REST 消费者使用 AKIAIOSFODNN7EXAMPLE AWS 作为访问密钥 ID 和 wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY 作为秘密访问密钥登录到 us-east-1 区域的 AWS 简单存储服务（s3），请输入以下命令：

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

配置REST消费者TLS/SSL参数​

要配置当前 REST 消费者的 TLS/SSL 参数，请输入以下 CONFIG 命令：

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

CLI 进入 REST 消费者 SSL 配置级别，您可以配置以下参数：

  • 密码套件
  • 启用服务器名称验证

密码套件​

您可以配置用于加密事件代理到主机连接的密码套件列表。默认情况下，密码套件列表包括所有密码套件，按从最安全到最不安全的顺序排列。

要使用默认的密码套件列表，请输入以下 CONFIG 命令：

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

要修改密码套件列表，请执行以下操作：

  • 要清空密码套件列表，请输入以下 REST VPN CONFIG 命令：

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

  • 要将密码套件添加到列表中，请输入以下 REST VPN CONFIG 命令：

    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite name <suite-name>

  • 要在列表中的特定位置添加密码套件，请使用以下 REST VPN CONFIG 命令：

    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite name <suite-name> [before|after <existing‑suite‑name>]

    其中：

    • <suite-name> 是要添加到列表中的密码套件的字符串标识符。如果没有指定 before 或 after 关键字，则密码套件将添加到列表末尾。
    • before 指定密码套件应添加到由 <existing-suite-name> 指示的密码套件之前。
    • after 指定密码套件应添加到由 <existing-suite-name> 指示的密码套件之后。
    • <existing-suite-name> 是列表中已存在的密码套件的名称。根据是否指定了 before 或 after 关键字，将要输入的密码套件将被定位在现有套件名称之前或之后。

此命令的 no 版本 cipher-suite name <suite-name> 将从配置的列表中移除指定的密码套件。

密码套件列表只能在 REST 消费者关闭时进行配置。

启用服务器名称验证​

您可以启用或禁用 TLS 身份验证机制以验证连接到远程服务器时使用的名称。如果启用，则用于该连接的服务器名称将与从远程代理返回的证书中的主题备用名称（SAN）扩展中的服务器名称进行验证。

服务器名称验证默认启用，并应在所有生产场景中保持启用。

要启用服务器名称验证，请输入以下命令：

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

要禁用服务器名称验证：

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

有关配置 CA 证书的信息，请参阅配置证书颁发机构。

启用REST消费者​

  • 要启用给定的 REST 消费者，请输入以下 CONFIG 命令：

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

  • 要禁用给定的 REST 消费者，请输入以下 CONFIG 命令：

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

    当 REST 消费者被禁用时，无法发起连接，也无法向其传递消息。

启用REST交付点​

  • 要启用给定的 RDP，请输入以下 CONFIG 命令：

    solace(.../message-vpn/rest/rest-delivery-point)# no shutdown

  • 要禁用给定的 RDP，请输入以下 CONFIG 命令：

    solace(.../message-vpn/rest/rest-delivery-point)# shutdown

    当禁用时，不会发起连接，RDP 也不会向任何包含的 REST 消费者传递消息。