定义客户端身份验证信息

身份验证方案会话属性指定是否使用基本身份验证、客户端证书、Kerberos 或 OAuth 身份验证来验证客户端与 Solace PubSub+ 事件代理之间的连接。

PubSub+ 消息 API	属性
JCSMP	- JCSMPProperties.AUTHENTICATION_SCHEME_BASIC

• JCSMPProperties.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE
• JCSMPProperties.AUTHENTICATION_SCHEME_GSS_KRB
• JCSMPProperties.AUTHENTICATION_SCHEME_OAUTH2 | | Java RTO | SessionHandle.PROPERTIES.AUTHENTICATION_SCHEME
SolEnum.AuthenticationScheme 中可能的值包括：
• AuthenticationScheme.BASIC
• AuthenticationScheme.CLIENT_CERTIFICATE
• AuthenticationScheme.GSS_KRB
• AuthenticationScheme.OAUTH2 | | C | - SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_BASIC
• SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE
• SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_GSS_KRB
• SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_OAUTH2 | | .NET | SessionProperties.AuthenticationSchemes
  枚举可能的值包括：
• AuthenticationSchemes.BASIC
• AuthenticationSchemes.CLIENT_CERTIFICATE
• AuthenticationSchemes.GSS_KRB
• AuthenticationSchemes.OAUTH2 | | JavaScript | 枚举可能的值包括：
• solace.AuthenticationScheme.BASIC
• solace.AuthenticationScheme.CLIENT_CERTIFICATE
• solace.AuthenticationScheme.OAUTH2 | | Node.js | 枚举可能的值包括：
• solace.AuthenticationScheme.BASIC
• solace.AuthenticationScheme.CLIENT_CERTIFICATE
• solace.AuthenticationScheme.OAUTH2 |

设置身份验证方案

除了在会话属性中指定将用于客户端的身份验证方案外，每种身份验证类型都有特定的前提条件或配置参数，这些参数是成功使用该身份验证方案所必需的。有关更多信息，请参阅：

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

基本身份验证

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

• 用户名
• 密码（可选）

用户名

会话需要用户名以验证连接到事件代理的客户端。必须为每个创建的会话提供用户名，并且它必须与事件代理上配置的客户端用户名一致。

当会话连接到事件代理上的消息 VPN 时，客户端会随着它们的连接和断开而动态创建和删除。因此，一个用户名可以被单个客户端或多个客户端使用。

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

PubSub+ 消息 API	属性
JCSMP	JCSMPProperties.USERNAME
Java RTO	SessionHandle.PROPERTIES.USERNAME
C	SOLCLIENT_SESSION_PROP_USERNAME
.NET	SessionProperties.UserName
JavaScript 和 Node.js	solace.SessionProperties.userName

设置用户名

密码

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

PubSub+ 消息 API	属性
JCSMP	JCSMPProperties.PASSWORD
Java RTO	SessionHandle.PROPERTIES.PASSWORD
C	SOLCLIENT_SESSION_PROP_PASSWORD
.NET	SessionProperties.Password
JavaScript 和 Node.js	solace.SessionProperties.password

客户端证书身份验证

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

当会话使用客户端证书身份验证方案时，客户端必须指定客户端证书和私钥。根据使用的 API，这些可以是单独的文件，也可以包含在单个密钥库文件中。

客户端证书身份验证依赖于事件代理上的 TLS/SSL 功能，因此只能用于安全会话。有关更多信息，请参阅创建安全会话。

JCSMP

密钥库是一个包含客户端证书、私钥和 CA 证书链的单一文件。需要密钥库密码。如果私钥被加密且密码与密钥库密码不同，则还必须指定私钥密码。如果未指定私钥密码，则假定私钥与密钥库具有相同的密码。

Java RTO、C、Node.js 和 .NET API

密钥库以私钥文件和客户端证书文件的形式存在。客户端证书和私钥可以是单独的文件，也可以在同一个文件中，但必须指定两个属性。如果私钥被加密，则还必须指定密码。

JavaScript API 通过运行它的浏览器进行配置，不支持通过会话属性进行这些配置。

属性	描述
SSL 客户端证书	（Java RTO、C、Node.js 和 .NET API）客户端证书文件名。
SSL 密钥库	（仅限 JCSMP）密钥库文件的 URL/路径格式（基于文件）或 java.security.KeyStore 格式（内存中）。不能混合使用内存和基于文件的用法。当使用内存形式时，一旦传递到 JCSMP API，java.security.KeyStore 被视为不可变的。
SSL 密钥库密码	（仅限 JCSMP）用于验证密钥库内容完整性的密码。密钥库密码可用于解密私钥，如果未指定 SSL_PRIVATE_KEY_PASSWORD 属性。
SSL 密钥库格式	（仅限 JCSMP）密钥库的格式；可以是 JKS 或 PKCS12。默认值为 JKS。
SSL 私钥文件	（Java RTO、C、Node.js 和 .NET API）私钥文件名。
SSL 私钥别名	（仅限 JCSMP）用于客户端身份验证的私钥别名。如果密钥库中只有一个私钥条目，则无需设置此属性。
SSL 私钥密码	解密私钥的密码。对于 JCSMP，私钥在密钥库中，当私钥被不同密钥加密时，此属性是必需的。

如果指定的密钥库无法加载（例如，对于 JCSMP，使用了错误的文件格式，或者对于 C API，私钥文件或客户端证书文件不可读），则不会尝试连接，并会向应用程序报告错误。

事件代理所需配置

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

Kerberos身份验证

Kerberos 身份验证方案允许客户端使用 Kerberos 机制验证与事件代理的连接。

Kerberos 身份验证可用于验证客户端与事件代理的安全或非安全会话。也就是说，与客户端证书身份验证不同，Kerberos 身份验证不依赖于事件代理上的 TLS/SSL 功能。

要使用 Kerberos 身份验证方案，必须进行以下配置：

• 所需版本和库：
  • JCSMP

需要 Java 分发版 1.8 或更高版本。默认情况下，使用 JVM 提供的 Kerberos 库。然而，如果需要符合公司政策，也可以配置要使用的 Kerberos 库。有关更多信息，请参阅安全连接和身份验证指南。

• Java RTO API 在 Linux 上

必须使用实现 GSSAPI（通用安全服务 API）版本 2 的库。

• Java RTO API 在 Windows 上

使用 Windows 分发的 SSPI（安全支持提供程序接口）。

• C API 在 Linux 和 SunOS 上

必须使用实现 GSSAPI 版本 2 的库。

• C API 在 Windows 上

使用 Windows 分发的 SSPI。

• .NET API

使用 Windows 分发的 SSPI。

• 将 Kerberos 设置为会话的身份验证方案。

• 仅限 Java：启用 Kerberos。 要为 JCSMP 启用 Kerberos 身份验证，请使用以下系统属性指定有效的 Java 身份验证和授权服务（JAAS）配置文件：

  -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 身份验证。有关更多信息，请参阅配置客户端身份验证。

OAuth身份验证

OAuth 身份验证方案允许客户端使用 OAuth 机制验证与事件代理的连接。有关更多信息，请参阅 OAuth 身份验证。

PubSub+ 事件代理支持以下 OAuth 身份验证机制：

• OAuth 2.0
• OpenID Connect

OAuth 2.0

当事件代理配置为使用 OAuth 2.0 身份验证（oauth-role 设置为 resource-server）时，客户端必须为事件代理提供以下属性以进行身份验证：

• 必需的访问令牌：根据 OAuth 定义，访问令牌由授权服务器在成功验证用户身份并获得其同意后颁发。访问令牌是允许 OAuth 客户端应用程序访问用户资源的凭证。如果令牌中存在 iss 声明，则用于标识事件代理将用于令牌验证的 OAuth 配置文件。如果未找到匹配的配置文件，则使用默认配置文件。

• （可选）授权服务器颁发者标识符（iss）。如果提供此参数，则必须与事件代理上的 OAuth 配置文件的颁发者匹配。该配置文件将用于令牌验证，而不是令牌的 iss 声明中提供的配置文件（如果存在），或事件代理上配置的默认配置文件。

PubSub+ 消息 API	用途
JCSMP	JCSMPProperties.OAUTH2_ACCESS_TOKEN
JCSMPProperties.OAUTH2_ISSUER_IDENTIFIER
Java RTO	PROPERTIES.SESSION_OAUTH2_ACCESS_TOKEN
PROPERTIES.SESSION_OAUTH2_ISSUER_IDENTIFIER
C	SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN
SOLCLIENT_SESSION_PROP_OAUTH2_ISSUER_IDENTIFIER
.NET	SessionProperties.Oauth2AccessToken
SessionProperties.Oauth2IssuerIdentifier
JavaScript 和 Node.js	solace.SessionProperties.accessToken
solace.SessionProperties.issuerIdentifier

OpenID Connect

当事件代理配置为使用 OpenID Connect 身份验证（oauth-role 设置为 client）时，客户端必须为事件代理提供以下属性以进行身份验证：

• 必需的 OpenID Connect ID 令牌：根据 OpenID Connect 定义，ID 令牌是 OAuth 2.0 的扩展。ID 令牌由授权服务器颁发，包含有关用户的信息声明。ID 令牌是证明用户已通过身份验证的凭证。令牌中的 iss 声明用于标识事件代理将用于令牌验证的 OAuth 配置文件。如果未找到匹配的配置文件，则使用默认配置文件。

• （可选）访问令牌。您的组织可能需要一个可选的访问令牌，事件代理将使用它来确定经过身份验证的客户端的授权范围。

PubSub+ 消息 API	用途
JCSMP	JCSMPProperties.OIDC_ID_TOKEN
JCSMPProperties.OAUTH2_ACCESS_TOKEN
Java RTO	PROPERTIES.SESSION_OIDC_ID_TOKEN
PROPERTIES.SESSION_OAUTH2_ACCESS_TOKEN
C	SOLCLIENT_SESSION_PROP_OIDC_ID_TOKEN
SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN
.NET	SessionProperties.OidcIdToken
SessionProperties.Oauth2AccessToken
JavaScript 和 Node.js	solace.SessionProperties.idToken
solace.SessionProperties.accessToken

事件代理所需配置

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

刷新过期的 OAuth 令牌

默认情况下，事件代理会在客户端令牌过期时断开客户端连接（请参阅令牌过期时断开连接）。当客户端会话断开连接时，客户端会根据 API 的重连重试属性（请参阅重连重试）尝试使用相同的 OAuth 令牌重新连接多次。如果由于令牌过期无法重新建立连接，则客户端需要重新创建会话及其所有订阅。为了避免这种情况，可以在 Solace 消息 API（JavaScript、JCSMP、Java RTO、CCSMP、.NET、C）中更新配置的令牌，以便在客户端下次尝试连接时使用有效的令牌。

PubSub+ 消息 API	用途
C	<br>propIndex = 0;<br>modifyProps[propIndex++] = SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN;<br>modifyProps[propIndex++] = "newAccessToken";<br>modifyProps[propIndex] = NULL;<br>if (solClient_session_modifyProperties(session_p, modifyProps) == SOLCLIENT_OK) {<br>}<br>
Java RTO	<br>tokenUpdate[1] = newAccessToken;<br>session.modifyProperties(tokenUpdate);<br>
JavaScript 和 Node.js	<br>session.updateAuthenticationOnReconnect({accessToken : “newAccessToken”});<br>
JCSMP	<br>session.setProperty(JCSMPProperties.OAUTH2_ACCESS_TOKEN, newAccessToken);<br>
.NET	<br>session.ModifyProperty(SessionProperties.PROPERTY.OAuth2AccessToken, newAccessToken);<br>

刷新 OAuth 令牌

刷新过期的令牌可以在以下情况下发生：

• 客户端已连接。在这种情况下，客户端联系授权服务器刷新令牌，并修改会话以在下次连接到事件代理时使用更新后的令牌。

• 客户端正在重新连接。重新连接事件包括一个诊断子代码。如果子代码为 登录失败，这可能表明您的令牌已过期。在这种情况下，API 会尝试使用过期的令牌重新连接。然后，客户端联系授权服务器刷新令牌，并修改会话以在下次尝试重新连接到事件代理时使用更新后的令牌。

一般来说，如果应用程序能够提前意识到令牌可能过期并刷新令牌，则会更好。

当客户端会话重新连接时，API 会重新应用客户端的直接订阅。如果由于刷新的令牌导致 ACL 发生变化，订阅可能会被事件代理拒绝。