Connection Factories

A client must use a SolConnectionFactory object to create a JMS connection to the Solace PubSub+ event broker that acts as the JMS broker. A JMS connection establishes a data channel between the event broker and the JMS application. A Connection Factory provides a number of configuration parameters to customize the connection between the JMS client and the event broker.

A SolXAConnectionFactory object can also be used to create a JMS connection to the event broker that acts as the JMS broker. A SolXAConnectionFactory is a specialized Connection Factory that allows the JMS application to create XA transactions that can be included in distributed transactions. A SolXAConnectionFactory inherits attributes from SolConnectionFactory. However, SolXAConnectionFactory differs in that the xa messaging property is enabled to allow JMS connections created by the XA Connection Factory to support XA Sessions and the direct‑transport transport property is disabled to allow only Guaranteed messages (that is, non-persistent and persistent messages) to be published or received, which is required for local or XA transactions.

Throughout this section, the information provided for a Connection Factory also pertains to an XA Connection Factory. However, for information on how to work with XA transactions once an XA connection to the event broker is connected, refer to Using XA Transactions.

Before creating a connection with a Connection Factory object, the Connection Factory properties should be modified, as required, because the data channel is established according to the Connection Factory’s configuration parameters. Any Connection Factory property that is not explicitly set will use the default values.

Once a SolConnectionFactory object has been successfully created or looked up (refer to Obtaining Connection Factories), and the Connection Factory properties are modified, as necessary, a client can use it to create a JMS connection (refer to Creating JMS Connections).

Property Prioritizing and Inheritance

JMS properties can often be set through a number of sources (for example, the Initial Context, System, JNDI properties file, JNDI Connection Factory), and the property values are prioritized depending on their source. For example, Username can be set as a system property (highest priority), through the JNDI properties file (lesser priority), or within the provided URL (least priority).

This prioritizing means that the values used for some of the JMS properties at a high level, such as the Initial Context or Java System level, are inherited at a lower level, such as the Connection Factory level.

However, it is also possible, in some cases, to override those inherited properties. For example, when using Basic client authentication, the username and password set for the Initial Context and used for the JNDI connection are inherited from the JMS data connection. However, these properties can be overridden by a username and password provided in the Connection Factory.

For information on where each property can be specified, and the priority that is given to a property according to where it is specified, refer to JMS Properties Reference.

Important Connection Properties

For a JMS client to establish a JNDI connection to the JNDI store (either on an event broker or an LDAP server) and a JMS connection to an event broker, the following properties must be set before the Connection Factory is obtained.

• URL

  This provides the IP address or hostname of the event broker or LDAP server that contains the JNDI store clients must use to perform JNDI lookups. Up to four potential hosts in order of preference can be specified in a comma‑separated list. Listing more than one host allows a client to attempt to connect or reconnect to alternate hosts if some are unavailable. The listed hosts may be in separate geographic locations.

  If you are programmatically creating Connection Factories or looking up Connection Factories for LDAP JNDI stores, the values that would typically be set for the URL property must be set in the Host Connection Factory property. In these cases, the values set for the Host property will override the values that implicitly set through the URL property used for the JNDI connection.

  URL can also provide a port number to use to establish the connection. A specific port number is only required when the client needs to use a port other than the automatically‑assigned default port. The default port number for plain-text transport is 55555. 55003 for plain-text compressed transport. The default port number for transport Layer Security (TLS)/ Secure Sockets Layer (SSL)‑encrypted connections is 55443 (note that compression is not available when TLS/SSL is used).

  Optionally, a username and password can also be specified in the URL property.

  In the case where both the JNDI connection and the JMS connection are made to a single event broker that acts as the JNDI store and JMS broker, the value provided for the URL property is used for both connections. However, when the JNDI store resides on an LDAP server, and the event broker is only to be used as the JMS broker, the IP address and port for the event broker must be set through the Host property in the Connection Factory that is used. The Host property must also include the JMS uniform resource identifier (URI) scheme, which indicates whether the JMS connection should use plain-text over SMF or TLS/ SSL protocols over SMF for secure communications between the application and the event broker.

  When using a Kerberos authentication scheme, you should consider the following:

  • When using a Kerberos authentication scheme in a Windows environment, a fully‑qualified domain name (FQDN) should be used for the host parameter, and it must match the Kerberos Service Principal Name (SPN) the event broker uses.
  • When a SPN is generated for the client, the following format is used: service_name/<customer-provided_host>@REALM. The service name portion is configured through the SupportedProperty.
SOLACE_JMS_KRB_SERVICE_NAME JNDI or data connection property (by default, it is solace), and the realm portion is determined by the configuration files used by the KRB library. An example of a resulting service principle name is solace/dev212@SIMPLESPNEXAMPLE.COM. For more information, refer to JNDI Connection Properties or Data Connection Properties.
  • When using multiple hosts, the SPN is generated from the host being used for the current connection.
• Authentication Scheme

  The authentication scheme specifies the credentials that a client will use to authenticate its connection to the event broker. The authentication scheme can be one of the following:

  • basic authentication—The default client authentication scheme. This scheme allows a client to authenticate with an event broker using a valid client username and password. Refer to Basic Authentication.
  • client certificate authentication—This scheme that allows a client to authenticate with an event broker through a client certificate. This authentication scheme also requires the client to use a secure connection. Refer to Client Certificate Authentication.
  • Kerberos authentication—This scheme allows a client to authenticate with an event broker through Kerberos ticket. Refer to Kerberos Authentication.
  • OAuth authentication - This scheme allows a client to authenticate with an event broker though access tokens issued by an authorization server. Refer to OAuth 2.0.

  All of these client authentication schemes require specific input to successfully authenticate a client. For more information, refer to Defining Client Authentication Information.

  When an event broker initially accepts a JNDI and/or JMS connection from a client, the resulting connection is in an unauthenticated state. Consequently, the event broker cannot process any requests from the client until the connection is authenticated.

• Message VPN

  The Message VPN to assign the connecting client to. Event brokers use Message VPNs to isolate the messaging space that clients can access. For example, messages that are published and received by clients in one Message VPN are isolated from those published and received by clients using different Message VPNs, and the messaging capabilities offered to the clients in on Message VPN may differ from those provided in another Message VPNs. Message VPNs are provisioned on the event broker through the CLI or SolAdmin. For information on configuring Message VPNs, refer to Message VPNs.

  When the Message VPN is provided through the Java command line, environment properties, or JNDI properties file, the password is set as the SOLACE_JMS_VPN property. If no Message VPN is specified, the Message VPN named default is used. The default Message VPN is always present on an event broker. Although a network administrator can change the configuration settings for default, it cannot be deleted.

  On a multi-homed client machine, it is strongly recommended that you provide the IP address of the interface to use on the machine hosting the client application through the JMS_Solace_localhost Java system variable. When running Java, you can provide the IP address through the command line (for example, -DJMS_Solace_localhost="192.168.1.1").
  If you do not provide the IP address of the interface you intend to use, the API could select an interface that cannot provide a route to the event broker.

• Secure Connections

  By default, the data exchanged between a JMS client and the Solace JNDI store through the JNDI connection, as well as the data exchanged between a JMS client and the JMS broker (the event broker) through the JMS connection is transmitted as plain text. However, it is also possible to establish secure connections that use TLS/SSL protocols to encrypt the data.

  To use secure JNDI and JMS connections, you must configure the following TLS/SSL‑specific connection properties:

  • SSL Cipher Suite
  • SSL Certificate Date Validation
  • SSL Certificate Validation
  • SSL Protocol
  • SSL Trust Store
  • SSL Trust Store Format
  • SSL Trust Store Password
  • SSL Trusted Common Name List

  For details on these properties, refer to JNDI Connection Properties and Data Connection Properties.

  In addition, the event broker that you want to create a secure connection to must be properly configured for TLS/ SSL service, and the appropriate server certificate must be in place. For information on configuring an event broker to allow for secure connections, refer to TLS / SSL Service Configuration.

  Related Samples

  For an example of how to create and connect secure Sessions, refer to the SolJMSSecureSession.java sample.

Defining Client Authentication Information

The authentication scheme property specifies the type of credentials required to authenticate a client connection to the event broker.

One of the following types of client authentication can be used to authenticate a client connection:

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

To set the authentication scheme to use for both the JNDI and JMS connections specify SupportedProperty.AUTHENTICATION_SCHEME_BASIC, SupportedProperty.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE, or SupportedProperty.AUTHENTICATION_SCHEME_KRB as an environment property provided for the Initial Context constructor. By default, basic client authentication is used for both the JNDI and JMS connections.

It is also possible for a client application to set the authentication scheme for a data connection when the Connection Factory is programmatically-created (refer to Programmatically Creating Connection Factories).

Basic Authentication

Basic authentication is the default client authentication scheme; it allows a client to authenticate with an event broker in an unsecured method. 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):

• Client ID
• Username
• Password (this is optional)

Client ID

To establish a JNDI and/or JMS data connection to an event broker, a unique client ID is required during client login to register that client with the event broker. If no client ID is entered, the API automatically generates a unique client ID. By default, this parameter is not specified.

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

For information on how to set a specific client ID, refer to JMS Properties Reference.

Username

A username is required for a Session to authenticate a client connecting to an event broker. The username that the JMS client provides must match with a client username account provisioned on the event broker through the Solace CLI (refer to Configuring Client Authentication) or through SolAdmin.

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

When a username is provided through the Java command line, environment properties, or JNDI properties file, the username is set as the SECURITY_PRINCIPAL property. A username can also be provided specifically for the JMS connection through the Connection Factory or the createConnection(...) method.

Password

When password authentication is enabled on the event broker, a valid username/password pair must be provided. By default, no password is required.

When provided through the Java command line, environment properties, or JNDI properties file, the username is set as SECURITY_CREDENTIALS property.

The provided password must match the password provisioned for the client username on the event broker.

Client Certificate Authentication

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

Client certificate authentication depends on the TLS/SSL facility on the event broker, so it can only be used for secure Sessions (refer to Secure Connections).

When a client certificate authentication is used for a connection, the client must provide a keystore file. The keystore is a single file that contains 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 keystore 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 Properties

Property	Description
SSL Key Store	The keystore file to use in URL or path format. This property is set through Initial Context environment or as a system property.
SSL Key Store Password	The password required to verify the integrity of the contents of the keystore. This property is required when the private key is encrypted with a different key than the password used to encrypt the keystore. This property is set through Initial Context environment or as a system property.
SSL Key Store Format	The format of the keystore (either JKS or PKCS12). The default value is JKS. This property is set through Initial Context environment or as a system property.
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. This property is set through Initial Context environment.
SSL Private Key Password	The password that decrypts the private key. For the JMS 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. This property is set through Initial Context environment.

If a specified keystore cannot be loaded (for example, an incorrect 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 authentication must be enabled for the Message VPN that the client is connecting to. The Message VPN to which the client connects can be configured to use the common name, subject alternative name, user identifier, or certificate thumbprint from the client certificate as the client username, or a client username that the client provides (refer to Username). Assigning the client username based on the common name in the client certificate is the default behavior.

Related Samples

For an example of how to use client certificate authentication, refer to the SolJMSSecureSession.java sample.

Kerberos Authentication

The Kerberos authentication scheme allows a client to use the GSSAPI Kerberos mechanism to authenticate its connection with the event broker. Kerberos authentication requires the client to present a valid ticket obtained through an approved Ticket Granting Service (TGS).

Kerberos authentication can be used to authenticate clients for either secured or unsecured Sessions to the event broker. 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 are required for the JMS API:

1. Java distribution 1.8 or greater must be used. By default, the Kerberos libraries provided by the JVM are used. However, you can also configure other Kerberos libraries to be used if these are required (for example, if they are mandated by corporate policies). For more information on configuring other Kerberos libraries, refer to Secure Connections and Authentication.
2. Set Kerberos as the authentication scheme to use for the Session (refer to Defining Client Authentication Information).
3. Enable Kerberos authentication for the JMS API. To do so, 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 Kerberos Authentication.

OAuth 2.0

OAuth 2.0 is commonly used as a way for users to grant websites or applications access to their information on other websites without giving them access to sensitive credentials. The OAuth 2.0 authentication scheme allows access through the use of tokens issued to third-party clients by an authorization server which provides access to Message VPNs on PubSub+ event brokers. For more information, see OAuth Authentication.

The Solace JMS API supports the following fields that can be sent to the broker using these extensions:

• SOLACE_JMS_OAUTH2_ACCESS_TOKEN

  and/or SOLACE_JMS_OIDC_ID_TOKEN

• SOLACE_JMS_OAUTH2_ISSUER_IDENTIFIER

For more information about the JMS API extensions, see Extensions to Standard JMS API.

OAuth 2.0 authentication in the JMS API requires a SOLACE_JMS_OAUTH2_ACCESS_TOKEN, a SOLACE_JMS_OIDC_ID_TOKEN, or both. Here's an example:

/* 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); // Create InitialContext.					
final ConnectionFactory cf = (ConnectionFactory)initialContext.lookup(CONNECTION_FACTORY_JNDI_NAME); // Lookup ConnectionFactory.					
return cf.createConnection(); // Create and return connection.	

Authorizing Clients

After a connecting client is authenticated with an event broker, access to event broker resources and messaging capabilities must be authorized for the client.

For a client to be authorized, it must provide the host event broker with a client username that matches one that is provisioned on the Message VPN to which the connection has been made. If there is a match, the client’s connection is authorized, and the Access Control List (ACL) profile and client profile that are assigned to the provisioned client username are then used to provide the client with its access permissions and messaging capabilities.

ACLs define whether the client is permitted to connect to the Message VPN, and, if it is, permissions are assigned to the client that set whether it can publish messages to topics, whether it can subscribe to topics, and whether those publish and subscribe rights are limited to a specific topics.

Client profiles contain a set of common configuration parameters that can be applied to groups of clients, which allows consistent configurations to be readily defined for many clients. Some of the configurations covered by client profiles includes the maximum number of subscriptions client may use and whether clients may use message eliding, publish and/or receive messages using Guaranteed transport, create endpoints, and so on.

Required Event Broker Configurations

For more information on the client configuration parameters that are controlled by ACL profiles and client profiles that are provisioned on event brokers, refer to Configuring Client Authorization.