Defining Client Authentication Info in the PubSub+ JCSMP API

The authentication scheme session property specifies whether Basic, Client Certificate, Kerberos, or OAuth authentication is to be used to authenticate a client’s connection to the Solace PubSub+ event broker.

To set an authentication scheme in the PubSub+ JCSMP API, you can use the following properties:

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

The following code snippet shows you how to use each property:

// Authentication using Basic authentication
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_BASIC);

// Authentication using Client Certificate authentication
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE);

// Authentication using Kerberos authentication
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_GSS_KRB);

// Authentication using OAuth2 authentication
sessionProperties.setProperty(JCSMPProperties.AUTHENTICATION_SCHEME, JCSMPProperties.AUTHENTICATION_SCHEME_OAUTH2);	

In addition to indicating in the session properties the authentication scheme that will be used for the client, each authentication type has specific prerequisites or configuration parameters that are required to successfully use that authentication scheme. For more information, refer to:

• Basic Authentication
• Client Certificate Authentication
• Kerberos Authentication
• OAuth Authentication

Basic Authentication

Basic authentication is the default client authentication scheme. When this scheme is used, the client must provide the following properties for the event broker to authenticate the client (these properties are not encrypted):

• Username
• Password (optional)

Username

A username is required for a session to authenticate any clients connecting with the event broker over that session. A username must be provided for each session created, and it must match with a client username account provisioned on the event broker.

When a session connects to a message VPN on an event broker, clients are created and deleted dynamically as they connect and disconnect from the event broker on that session. Therefore, it is possible that a username can be used by a single client or by multiple clients.

The username property is the same as the client-username property that can be shown through the Solace CLI or SolAdmin.

To set a username, set the following property: JCSMPProperties.USERNAME

Password

When Session authentication is enabled on the event broker, a valid username/password pair must be provided to connect a Session to an event broker. The default is no password.

To set a session password name, use properties.setProperty(JCSMPProperties.PASSWORD, "my_password");.

Client Certificate Authentication

A client certificate authentication scheme allows a client to prove its identity to the event broker through a valid X509v3 client certificate obtained from a Certification Authority (CA).

When the client certificate authentication scheme is used for the Session, the client must specify a client certificate and a private key. Depending on the API used, these could be separate files or be contained in a single keystore file.

Client certificate authentication depends on the TLS/SSL facility on the event broker, so it can only be used for secure Sessions. For more information, see Creating Secure Sessions in the PubSub+ JCSMP API.

In the PubSub+ JCSMP API, the keystore is a single file containing the client’s certificate, private key, and the CA certificate chain. A password for the keystore is required. A private key password must also be specified when the private key is encrypted and the password is not the same as the key store password. If a private key password is not specified, it is assumed that the private key has the same password as the keystore.

Client Certificate Authentication Session Properties

Property	Description
SSL Client Certificate	The client certificate file name. Not applicable to the PubSub+ JCSMP API.
SSL Key Store	The keystore file URL/path format (file-based) or java.security.Keystore format (in-memory). You cannot mix in-memory and file-based usage. When you use the in-memory form, the java.security.Keystore is considered immutable once you pass it into the PubSub+ JCSMP API.
SSL Key Store Password	The password required to verify the integrity of the contents of the keystore. The keystore password can be used to decipher the private key if the SSL_PRIVATE_KEY_PASSWORD property is not specified.
SSL Key Store Format	The format of the keystore; either JKS or PKCS12. The default value is JKS.
SSL Private Key File	The private key file name. Not applicable to the PubSub+ JCSMP API.
SSL Private Key Alias	The alias of the private key to use for client authentication. If there is only one private key entry in the given keystore then this property does not have to be set.
SSL Private Key Password	The password that decrypts the private key. For the PubSub+ JCSMP API, the private key is in the keystore, and this property is required when the private key is encrypted with a different key than the password used to encrypt the keystore.

If a specified key store cannot be loaded, for example a bad file format is used, the connection is not attempted and an error is reported to the application.

Required Event Broker Configurations

For a client to use a client certificate authentication scheme, the host event broker must be properly configured for TLS/SSL connections, and Client Certificate Verification must be enabled for the particular Message VPN that the client is connecting to. The Message VPN that the client connects to can be configured to use the common name in the client certificate’s subject as the client username or to use a client username (refer to Username) that the client provides. (Assigning the client username based on the common name in the client certificate is the default behavior.)

Kerberos Authentication

The Kerberos authentication scheme allows a client to use the Kerberos mechanism to authenticate its connection with the event broker.

Kerberos authentication can be used to authenticate clients for either secured or unsecured Sessions to the event broker. That is, unlike client certificate authentication, Kerberos authentication does not depend on the TLS/SSL facility on the event broker.

To use the Kerberos authentication scheme, the following configurations must be made:

• Required versions and libraries for the:
  • JCSMP

  Java distribution 1.8 or greater is required. By default, the Kerberos libraries provided by the JVM are used. However, if required for your corporate policies, you can also configure the Kerberos libraries that will be used. For more information, refer to Guidelines for Secure Connections and Authentication.

• Set Kerberos as the authentication scheme to use for the session.
• Enable Kerberos.

  To enable Kerberos authentication for the PubSub+ JCSMP API, use the following system property to specify a valid Java Authentication and Authorization Service (JAAS) configuration file:

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

  Sample contents of jaas.conf:

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

Required Event Broker Configurations

For a client to use a Kerberos authentication scheme, a Kerberos key tab file must be configured for the host event broker and Kerberos authentication must be configured and enabled for any Message VPNs that a client will connect to. Refer to Configuring Client Authentication.

OAuth Authentication

The OAuth authentication scheme allows a client to use the OAuth mechanism to authenticate its connection with the event broker. For more information see OAuth Authentication.

PubSub+ event brokers support the following OAuth authentication mechanisms:

• OAuth 2.0

• OpenID Connect

The authentication mechanism (OAuth2.0 vs OpenID Connect) is configured in the event broker OAuth profile(s) on the VPN. In either case, the PubSub+ JCSMP API is configured with the authentication scheme OAUTH2.

OAuth 2.0

When the event broker is configured for OAuth 2.0 authentication (oauth-role is set to resource-server) the client must provide the following properties for the event broker to authenticate the client:

• A mandatory access token: Defined in OAuth, access tokens are issued by the authorization server after successfully authenticating the user and obtaining their consent. The access token is the artifact that allows an OAuth client application to access the user's resource. The iss claim in the token, if present, is used to identify which OAuth profile the event broker will use for token validation. If no profile with a matching issuer is found, the default profile is used.

• (Optionally) An Authorization Server Issuer Identifier (iss). If provided, this parameter must match the issuer of an OAuth profile on the event broker. That profile will be used for token validation, rather than the profile with the issuer provided in the token’s iss claim, if any, or the default profile configured on the event broker.

The following code snippet shows you how to set an OAuth2 Access Token and Optional Issuer Identifier:

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

OpenID Connect

When the event broker is configured for OpenID Connect authentication (oauth-role is set to client) the client must provide the following properties for the event broker to authenticate the client:

• A mandatory OpenID Connect ID Token; Defined by OpenID Connect(OIDC), ID tokens are an extension to OAuth2.0. ID tokens are issued by the authorization server and contain claims that carry information about the user. An ID token is an artifact that proves that the user has been authenticated. The iss claim in the token is used to identify which OAuth profile the event broker will use for token validation. If no profile with a matching issuer is found, the default profile is used.

• (Optionally) An access token. Your organization may require an optional access token, that the broker will use to determine the authorizations available to the authenticated client.

The following code snippet shows you how to set an OpenID connect ID token and an optional access token:

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

Required Event Broker Configurations

For a client to use an OAuth authentication scheme, a Message VPN OAuth  profile must be configured for the host event broker and OAuth authentication must be configured and enabled for any Message VPNs to which a client connects. Refer to OAuth Authentication.

Refreshing Expired OAuth Tokens

By default, event brokers disconnect clients when their tokens expire (see Disconnect on Token Expiration). When a client session is disconnected, the client tries to reconnect a number of times using the same OAuth token, based on the API's Reconnect Retries property (see Reconnect Retries). If the connection can't be reestablished due to token expiration, the client has to recreate the session with all its subscriptions. To avoid this situation, you can update the configured token in the PubSub+ JCSMP API so that it's valid the next time the client tries to connect.

The following code snippet shows you how to refresh an OAuth token:

session.setProperty(JCSMPProperties.OAUTH2_ACCESS_TOKEN, newAccessToken);

Refreshing the expired token can happen while:

• the client is connected. In this case, the client contacts the authentication server to refresh the token and modifies the session to use the updated token the next time the API connects to the event broker.

• the client is reconnecting. The reconnecting event includes a diagnostic subCode. If this subCode is Login Failure, this may indicate that your token has expired. In this case, the API tries to reconnect (using the expired token). The client then contacts the authentication server to refresh the token and modifies the session to use the updated token the next time the API attempts to reconnect to the event broker.

In general, it is better if the application is aware of potential token expiry and refreshes the token before it expires.

When the client's session is reconnected, the API re-applies the client's direct subscriptions. If there is a change in the ACLs as a result of the refreshed token, the subscriptions may be rejected by the event broker.