连接工厂

客户端必须使用 SolConnectionFactory 对象来创建与充当 JMS 代理的 Solace PubSub+ 事件代理的 JMS 连接。JMS 连接在事件代理和 JMS 应用程序之间建立了一个数据通道。连接工厂提供了许多配置参数，用于自定义 JMS 客户端和事件代理之间的连接。

SolXAConnectionFactory 对象也可以用来创建与作为 JMS 代理的事件代理的 JMS 连接。SolXAConnectionFactory 是一个专门的连接工厂，允许 JMS 应用程序创建可以包含在分布式事务中的 XA 事务。SolXAConnectionFactory 继承了 SolConnectionFactory 的属性。然而，SolXAConnectionFactory 与之不同的是，xa 消息属性被启用，以允许由 XA 连接工厂创建的 JMS 连接支持 XA 会话，direct‑transport 传输属性被禁用，以仅允许发布或接收保证消息（即非持久化和持久化消息），这是本地或 XA 事务所必需的。

在本节中，提供的有关连接工厂的信息也适用于 XA 连接工厂。但是，有关如何在与事件代理的 XA 连接连接后使用 XA 事务的信息，请参阅使用 XA 事务。

在使用连接工厂对象创建连接之前，应根据需要修改连接工厂属性，因为数据通道是根据连接工厂的配置参数建立的。任何未明确设置的连接工厂属性都将使用默认值。

成功创建或查找（参阅获取连接工厂）SolConnectionFactory 对象后，并根据需要修改了连接工厂属性，客户端可以使用它来创建 JMS 连接（参阅创建 JMS 连接）。

属性优先级和继承

JMS 属性通常可以通过多个来源设置（例如，初始上下文、系统、JNDI 属性文件、JNDI 连接工厂），属性值的优先级取决于其来源。例如，Username 可以作为系统属性设置（最高优先级），通过 JNDI 属性文件设置（较低优先级），或在提供的 URL 中设置（最低优先级）。

这种优先级意味着在较高层次（如初始上下文或 Java 系统级别）使用的某些 JMS 属性值会在较低层次（如连接工厂级别）继承。

然而，在某些情况下，也可以覆盖这些继承的属性。例如，当使用基本客户端身份验证时，用于 JNDI 连接的初始上下文设置的用户名和密码会继承到 JMS 数据连接。但是，这些属性可以通过连接工厂提供的用户名和密码覆盖。

有关可以在何处指定每个属性以及根据指定位置给予属性的优先级的信息，请参阅 JMS 属性参考。

重要的连接属性

为了让 JMS 客户端建立到 JNDI 存储库（位于事件代理或 LDAP 服务器上）的 JNDI 连接以及到事件代理的 JMS 连接，在获取连接工厂之前必须设置以下属性。

URL 提供包含 JNDI 存储库的事件代理或 LDAP 服务器的 IP 地址或主机名，客户端必须使用该存储库执行 JNDI 查找。可以按优先顺序指定多达四个潜在主机，以逗号分隔列表形式。列出多个主机允许客户端在某些主机不可用时尝试连接或重新连接到备用主机。列出的主机可能位于不同的地理位置。

如果以编程方式创建连接工厂或查找 LDAP JNDI 存储库的连接工厂，通常为 URL 属性设置的值必须在 Host 连接工厂属性中设置。在这种情况下，为 Host 属性设置的值将覆盖通过用于 JNDI 连接的 URL 属性隐式设置的值。

URL 也可以提供用于建立连接的端口号。仅当客户端需要使用自动分配的默认端口以外的端口时，才需要指定特定端口号。纯文本传输的默认端口号为 55555。纯文本压缩传输的端口号为 55003。传输层安全性（TLS）/安全套接字层（SSL）加密连接的默认端口号为 55443（注意，使用 TLS/SSL 时不可用压缩）。

可选地，还可以在 URL 属性中指定用户名和密码。

如果 JNDI 连接和 JMS 连接都建立到充当 JNDI 存储库和 JMS 代理的单个事件代理，则为 URL 属性提供的值用于两个连接。但是，当 JNDI 存储库位于 LDAP 服务器上，且事件代理仅用作 JMS 代理时，必须通过用于连接的连接工厂的 Host 属性设置事件代理的 IP 地址和端口。Host 属性还必须包括 JMS 统一资源标识符（URI）方案，该方案指示 JMS 连接是否应使用纯文本通过 SMF 或使用 TLS/SSL 协议通过 SMF 进行安全通信。

身份验证方案 身份验证方案指定客户端将用于身份验证其与事件代理的连接的凭据。身份验证方案可以是以下之一：
- 基本身份验证 — 默认的客户端身份验证方案。此方案允许客户端使用有效的客户端用户名和密码与事件代理进行身份验证。参阅基本身份验证。
- 客户端证书身份验证 — 此方案允许客户端通过客户端证书与事件代理进行身份验证。此身份验证方案还要求客户端使用安全连接。参阅客户端证书身份验证。
- Kerberos 身份验证 — 此方案允许客户端通过 Kerberos 票据与事件代理进行身份验证。参阅 Kerberos 身份验证。
- OAuth 身份验证 — 此方案允许客户端通过授权服务器颁发的访问令牌与事件代理进行身份验证。参阅 OAuth 2.0。

所有这些客户端身份验证方案都需要特定输入，以成功身份验证客户端。有关详细信息，请参阅定义客户端身份验证信息。

当事件代理最初接受客户端的 JNDI 和/或 JMS 连接时，结果连接处于未身份验证状态。因此，事件代理无法处理来自客户端的任何请求，直到连接被身份验证。

消息 VPN 分配给连接客户端的消息 VPN。事件代理使用消息 VPN 来隔离客户端可以访问的消息空间。例如，一个消息 VPN 中的客户端发布的和接收的消息与使用不同消息 VPN 的客户端发布的和接收的消息是隔离的，并且一个消息 VPN 中提供的客户端消息功能可能与另一个消息 VPN 中提供的不同。消息 VPN 通过 CLI 或 SolAdmin 在事件代理上配置。有关配置消息 VPN 的信息，请参阅消息 VPN。

当通过 Java 命令行、环境属性或 JNDI 属性文件提供消息 VPN 时，密码设置为 SOLACE_JMS_VPN 属性。如果没有指定消息 VPN，则使用名为 default 的消息 VPN。default 消息 VPN 总是存在于事件代理上。尽管网络管理员可以更改 default 的配置设置，但不能删除它。

在多宿主客户端机器上，强烈建议您通过 JMS_Solace_localhost Java 系统变量提供客户端应用程序托管机器上要使用的接口的 IP 地址。运行 Java 时，可以通过命令行提供 IP 地址（例如，-DJMS_Solace_localhost="192.168.1.1"）。

如果您不提供要使用的接口的 IP 地址，API 可能会选择一个无法为到事件代理的路由提供服务的接口。

安全连接 默认情况下，通过 JNDI 连接在 JMS 客户端和 Solace JNDI 存储库之间交换的数据以及通过 JMS 连接在 JMS 客户端和 JMS 代理（事件代理）之间交换的数据以纯文本形式传输。然而，也可以建立使用 TLS/SSL 协议加密数据的安全连接。

要使用安全的 JNDI 和 JMS 连接，您必须配置以下特定于 TLS/SSL 的连接属性：

SSL 密码套件
SSL 证书日期验证
SSL 证书验证
SSL 协议
SSL 信任库
SSL 信任库格式
SSL 信任库密码
SSL 可信通用名称列表

有关这些属性的详细信息，请参阅 JNDI 连接属性和数据连接属性。

此外，您要建立安全连接的事件代理必须正确配置为 TLS/SSL 服务，并且必须有适当的服务器证书。有关配置事件代理以允许安全连接的信息，请参阅 TLS/SSL 服务配置。

有关如何创建和连接安全会话的示例，请参阅 SolJMSSecureSession.java 示例。

定义客户端身份验证信息

身份验证方案属性指定用于身份验证客户端与事件代理的连接所需的凭据类型。

可以使用以下类型的客户端身份验证之一来身份验证客户端连接：

基本身份验证
客户端证书身份验证
Kerberos 身份验证
OAuth 2.0

要设置用于 JNDI 和 JMS 连接的身份验证方案，请将 SupportedProperty.AUTHENTICATION_SCHEME_BASIC、SupportedProperty.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE 或 SupportedProperty.AUTHENTICATION_SCHEME_KRB 指定为初始上下文构造函数提供的环境属性。默认情况下，基本客户端身份验证用于 JNDI 和 JMS 连接。

客户端应用程序也可以在以编程方式创建连接工厂时为数据连接设置身份验证方案（参阅以编程方式创建连接工厂）。

基本身份验证

基本身份验证是默认的客户端身份验证方案；它允许客户端以不安全的方式与事件代理进行身份验证。使用此方案时，客户端必须为事件代理提供以下属性以身份验证客户端（这些属性未加密）：

客户端 ID
用户名
密码（这是可选的）

客户端 ID

要建立到事件代理的 JNDI 和/或 JMS 数据连接，客户端登录时需要一个唯一的客户端 ID 以在事件代理上注册该客户端。如果没有输入客户端 ID，API 将自动生成一个唯一的客户端 ID。默认情况下，不指定此参数。

客户端 ID 属性与可以通过 Solace CLI 或 SolAdmin 显示的 client 属性相同。

有关如何设置特定客户端 ID 的信息，请参阅 JMS 属性参考。

用户名

会话需要用户名来身份验证连接到事件代理的客户端。JMS 客户端提供的用户名必须与通过 Solace CLI（参阅配置客户端身份验证）或 SolAdmin 在事件代理上配置的客户端用户名帐户匹配。

用户名属性与可以通过 Solace CLI 或 SolAdmin 显示的 client-username 属性相同。

当通过 Java 命令行、环境属性或 JNDI 属性文件提供用户名时，用户名设置为 SECURITY_PRINCIPAL 属性。也可以通过连接工厂或 createConnection(...) 方法为 JMS 连接专门提供用户名。

密码

当在事件代理上启用密码身份验证时，必须提供有效的用户名/密码对。默认情况下，不需要密码。

当通过 Java 命令行、环境属性或 JNDI 属性文件提供时，用户名设置为 SECURITY_CREDENTIALS 属性。

提供的密码必须与事件代理上为客户端用户名配置的密码匹配。

客户端证书身份验证

客户端证书身份验证是一种安全的客户端身份验证方案，允许客户端通过从受信任的证书颁发机构（CA）获得的有效 X509v3 客户端证书向事件代理证明其身份。

客户端证书身份验证依赖于事件代理上的 TLS/SSL 设施，因此它只能用于安全会话（参阅安全连接）。

当使用客户端证书身份验证进行连接时，客户端必须提供一个密钥库文件。密钥库是一个包含客户端证书、私钥和 CA 证书链的单个文件。

需要密钥库的密码。如果私钥被加密，并且密码与用于加密密钥库的密码不同，则还必须指定私钥密码。如果未指定私钥密码，则假定私钥具有与密钥库相同的密码。

属性	描述
SSL 密钥库	要使用的密钥库文件，以 URL 或路径格式表示。\n\n此属性通过初始上下文环境或作为系统属性设置。
SSL 密钥库密码	验证密钥库内容完整所需的密码。当私钥使用与加密密钥库不同的密钥加密时，需要此属性。\n\n此属性通过初始上下文环境或作为系统属性设置。
SSL 密钥库格式	密钥库的格式（JKS 或 PKCS12）。默认值为 JKS。\n\n此属性通过初始上下文环境或作为系统属性设置。
SSL 私钥别名	用于客户端身份验证的私钥的别名。如果给定密钥库中只有一个私钥条目，则无需设置此属性。\n\n此属性通过初始上下文环境设置。
SSL 私钥密码	解密私钥的密码。对于 JMS API，私钥位于密钥库中，当私钥使用与加密密钥库不同的密钥加密时，需要此属性。\n\n此属性通过初始上下文环境设置。

客户端证书身份验证属性

如果无法加载指定的密钥库（例如，使用了错误的文件格式），则不会尝试连接，并且会向应用程序报告错误。

事件代理所需配置

要使用客户端证书身份验证方案，宿主事件代理必须正确配置为 TLS/SSL 连接，并且必须为客户端连接的消息 VPN 启用客户端证书身份验证。客户端连接的消息 VPN 可以配置为使用客户端证书中的通用名称、主题备用名称、用户标识符或证书指纹作为客户端用户名，或者客户端提供的客户端用户名（参阅用户名）。根据客户端证书中的通用名称分配客户端用户名是默认行为。

相关示例

有关如何使用客户端证书身份验证的示例，请参阅 SolJMSSecureSession.java 示例。

Kerberos身份验证

Kerberos 身份验证方案允许客户端使用 GSSAPI Kerberos 机制来身份验证其与事件代理的连接。Kerberos 身份验证要求客户端出示通过批准的票据授予服务（TGS）获得的有效票据。

Kerberos 身份验证可用于身份验证到事件代理的安全或不安全会话。与客户端证书身份验证不同，Kerberos 身份验证不依赖于事件代理上的 TLS/SSL 设施。

要使用 Kerberos 身份验证方案，JMS API 需要以下配置：

必须使用 Java 分发版 1.8 或更高版本。默认情况下，使用 JVM 提供的 Kerberos 库。但是，如果需要（例如，如果它们由公司政策强制执行），也可以配置其他 Kerberos 库。有关配置其他 Kerberos 库的更多信息，请参阅安全连接和身份验证。
将 Kerberos 设置为会话使用的身份验证方案（参阅定义客户端身份验证信息）。
通过以下系统属性启用 JMS API 的 Kerberos 身份验证：

-Djava.security.auth.login.config=jaas.conf

jaas.conf 的示例内容：

SolaceGSS {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true
    isInitiator=true
    doNotPrompt=true
    debug=false;
};

事件代理所需配置

要使用 Kerberos 身份验证方案，必须为宿主事件代理配置 Kerberos 密钥表文件，并且必须为客户端将要连接的任何消息 VPN 配置并启用 Kerberos 身份验证。有关详细信息，请参阅 Kerberos 身份验证。

OAuth 2.0

OAuth 2.0 常用于让用户授权网站或应用程序访问他们在其他网站上的信息，而无需提供敏感凭据。OAuth 2.0 身份验证方案允许通过授权服务器向第三方客户端颁发的令牌访问 PubSub+ 事件代理上的消息 VPN。有关更多信息，请参阅 OAuth 身份验证。

Solace JMS API 支持以下可以使用这些扩展发送到代理的字段：

SOLACE_JMS_OAUTH2_ACCESS_TOKEN

和/或 SOLACE_JMS_OIDC_ID_TOKEN

SOLACE_JMS_OAUTH2_ISSUER_IDENTIFIER

有关 JMS API 扩展的更多信息，请参阅对标准 JMS API 的扩展。

JMS API 中的 OAuth 2.0 身份验证需要 SOLACE_JMS_OAUTH2_ACCESS_TOKEN、SOLACE_JMS_OIDC_ID_TOKEN 或两者都需要。以下是一个示例：

/* Configure service access to use a Open ID connect authentication with an access token, an ID token and an optional issuer identifier. */
Hashtable<String, Object> env = new Hashtable<String, Object>();
env.put(InitialContext.INITIAL_CONTEXT_FACTORY, SOLJMS_INITIAL_CONTEXT_FACTORY);
env.put(InitialContext.PROVIDER_URL, jndiProviderURL);
env.put(SupportedProperty.SOLACE_JMS_AUTHENTICATION_SCHEME, SupportedProperty.AUTHENTICATION_SCHEME_OAUTH2);
env.put(SupportedProperty.SOLACE_JMS_OAUTH2_ACCESS_TOKEN, myAccessToken);
env.put(SupportedProperty.SOLACE_JMS_OIDC_ID_TOKEN, myOIDCToken);
env.put(SupportedProperty.SOLACE_JMS_OAUTH2_ISSUER_IDENTIFIER, issuerIdentifierURL);

final InitialContext initialContext = new InitialContext(env); // 创建 InitialContext。
final ConnectionFactory cf = (ConnectionFactory)initialContext.lookup(CONNECTION_FACTORY_JNDI_NAME); // 查找 ConnectionFactory。
return cf.createConnection(); // 创建并返回连接。

授权客户端

客户端与事件代理建立连接后，必须授权客户端访问事件代理资源和消息功能。

要授权客户端，客户端必须向宿主事件代理提供与连接所连接的消息 VPN 上配置的客户端用户名匹配的客户端用户名。如果有匹配项，则客户端的连接被授权，并且分配给配置的客户端用户名的访问控制列表（ACL）配置文件和客户端配置文件随后用于为客户端提供其访问权限和消息功能。

ACL 定义客户端是否被允许连接到消息 VPN，并且如果允许，分配给客户端的权限设置客户端是否可以向主题发布消息，是否可以订阅主题，以及这些发布和订阅权限是否限于特定主题。

客户端配置文件包含一组可以应用于客户端组的通用配置参数，这允许为许多客户端轻松定义一致的配置。客户端配置文件涵盖的一些配置包括客户端可以使用的最大订阅数以及客户端是否可以使用消息省略、使用保证传输发布和/或接收消息、创建端点等。

事件代理所需配置

有关事件代理上配置的 ACL 配置文件和客户端配置文件控制的客户端配置参数的更多信息，请参阅配置客户端授权。

属性优先级和继承​

重要的连接属性​

定义客户端身份验证信息​

基本身份验证​

客户端 ID​

用户名​

密码​

客户端证书身份验证​

Kerberos身份验证​

事件代理所需配置​

OAuth 2.0​

授权客户端​