跳到主要内容

在PubSub+ JCSMP API中定义客户端身份验证信息

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

在 PubSub+ JCSMP API 中设置身份验证方案时，可以使用以下属性：

  • JCSMPProperties.AUTHENTICATION_SCHEME_BASIC
  • JCSMPProperties.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE
  • JCSMPProperties.AUTHENTICATION_SCHEME_GSS_KRB
  • JCSMPProperties.AUTHENTICATION_SCHEME_OAUTH2

以下代码片段展示了如何使用每个属性：

// 使用基本身份验证进行身份验证
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_BASIC);

// 使用客户端证书身份验证进行身份验证
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE);

// 使用 Kerberos 身份验证进行身份验证
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_GSS_KRB);

// 使用 OAuth2 身份验证进行身份验证
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_OAUTH2);

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

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

基本身份验证​

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

  • 用户名
  • 密码（可选）

用户名​

会话需要用户名来认证任何通过该会话连接到事件代理的客户端。必须为每个创建的会话提供用户名，并且它必须与在事件代理上配置的客户端用户名帐户匹配。

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

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

要设置用户名，请设置以下属性：JCSMPProperties.USERNAME

密码​

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

要设置会话密码，请使用以下代码：

properties.setProperty(JCSMPProperties.PASSWORD, "my_password");

客户端证书身份验证​

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

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

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

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

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

客户端证书身份验证会话属性

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

必需的事件代理配置​

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

Kerberos身份验证​

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

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

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

  • 所需的版本和库：
    • JCSMP

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

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

  • 启用 Kerberos。 要为 PubSub+ JCSMP API 启用 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 keytab 文件，并且必须为客户端将连接到的任何消息 VPN 配置并启用 Kerberos 身份验证。有关详细信息，请参阅配置客户端身份验证。

OAuth身份验证​

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

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

  • OAuth 2.0
  • OpenID Connect

身份验证机制（OAuth2.0 与 OpenID Connect）在 VPN 上的事件代理 OAuth 配置文件中进行配置。在任何情况下，PubSub+ JCSMP API 都配置为使用 OAUTH2 身份验证方案。

OAuth 2.0​

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

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

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

以下代码片段展示了如何设置 OAuth2 访问令牌和可选的发行者标识符：

sessionProperties.setProperty(JCSMPProperties.OAUTH2_ACCESS_TOKEN, accessToken);
sessionProperties.setProperty(JCSMPProperties.OAUTH2_ISSUER_IDENTIFIER, issuerId);

OpenID Connect​

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

  • 必需的 OpenID Connect ID 令牌；由 OpenID Connect（OIDC）定义，ID 令牌是 OAuth2.0 的扩展。ID 令牌由授权服务器颁发，并包含携带有关用户信息的声明。ID 令牌是证明用户已通过身份验证的凭证。令牌中的 iss 声明用于标识事件代理将用于令牌验证的 OAuth 配置文件。如果没有找到与发行者匹配的配置文件，则使用默认配置文件。

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

以下代码片段展示了如何设置 OpenID Connect ID 令牌和可选的访问令牌：

sessionProperties.setProperty(JCSMPProperties.OAUTH2_ACCESS_TOKEN, accessTokenOptional);
sessionProperties.setProperty(JCSMPProperties.OIDC_ID_TOKEN, idToken);

必需的事件代理配置​

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

刷新过期的 OAuth 令牌​

默认情况下，当客户端的令牌过期时，事件代理会断开客户端的连接（参阅在令牌过期时断开连接）。当客户端会话被断开连接时，客户端会根据 API 的重新连接重试属性（参阅重新连接重试）使用相同的 OAuth 令牌尝试重新连接多次。如果由于令牌过期无法重新建立连接，客户端必须重新创建带有所有订阅的会话。为了避免这种情况，您可以更新 PubSub+ JCSMP API 中配置的令牌，以便在客户端下次尝试连接时它是有效的。

以下代码片段展示了如何刷新 OAuth 令牌：

session.setProperty(JCSMPProperties.OAUTH2_ACCESS_TOKEN, newAccessToken);

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

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

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

一般来说，如果应用程序能够意识到潜在的令牌过期，并在令牌过期之前刷新它，会更好。

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