Defining Client Authentication Info

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

To Set an Authentication Scheme

PubSub+ Messaging API

Property

JCSMP

  • JCSMPProperties.AUTHENTICATION_SCHEME_BASIC

  • JCSMPProperties.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE

  • JCSMPProperties.AUTHENTICATION_SCHEME_GSS_KRB

Java RTO

SessionHandle.PROPERTIES.AUTHENTICATION_SCHEME

Possible values in SolEnum.AuthenticationScheme are:

  • AuthenticationScheme.BASIC

  • AuthenticationScheme.CLIENT_CERTIFICATE

  • AuthenticationScheme.GSS_KRB

C

  • SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_BASIC

  • SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE

  • SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_GSS_KRB

.NET

SessionProperties.AuthenticationSchemes

Possible values for the enumeration are:

  • AuthenticationSchemes.BASIC

  • AuthenticationSchemes.CLIENT_CERTIFICATE

  • AuthenticationSchemes.GSS_KRB

JavaScript

Possible values for the enumeration are:

  • solace.AuthenticationScheme.BASIC

  • solace.AuthenticationScheme.CLIENT_CERTIFICATE

Node.js

Possible values for the enumeration are:

  • solace.AuthenticationScheme.BASIC

  • solace.AuthenticationScheme.CLIENT_CERTIFICATE

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

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

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

PubSub+ Messaging API

Property

JCSMP

JCSMPProperties.USERNAME

Java RTO

SessionHandle.PROPERTIES.USERNAME

C

SOLCLIENT_SESSION_PROP_USERNAME

.NET

SessionProperties.UserName

JavaScript and Node.js

solace.SessionProperties.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

PubSub+ Messaging API

Property

JCSMP

JCSMPProperties.PASSWORD

Java RTO

SessionHandle.PROPERTIES.PASSWORD

C

SOLCLIENT_SESSION_PROP_PASSWORD

.NET

SessionProperties.Password

JavaScript and Node.js

solace.SessionProperties.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 (refer to Creating Secure Sessions).

JCSMP

The key store 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.

Java RTO, C, Node.js, and .NET APIs

The key store is in the form of a private key file and a client certificate file. The client certificate and the private key can be in separate files or in the same file, but both properties must be specified. If the private key is encrypted, a password must also be specified.

The JavaScript API is configured through the browser where it runs and does not support these configurations through session properties.

Client Certificate Authentication Session Properties

Property

Description

SSL Client Certificate

(Java RTO, C, Node.js, and .NET APIs.) The client certificate file name.

SSL Key Store

(JCSMP only.) The keystore file to use in URL or path format.

SSL Key Store Password

(JCSMP only.) 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

(JCSMP only.) The format of the keystore; either JKS or PKCS12. The default value is JKS.

SSL Private Key File

(Java RTO, C, Node.js, and .NET APIs.) The private key file name.

SSL Private Key Alias

(JCSMP only.) 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 JCSMP, 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, for JCSMP, a bad file format is used, or, for the C API, a private key file or client certificate file is not readable) 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.

    • Java RTO API on Linux
    • Libraries that implement GSSAPI (Generic Security Services API) Version 2 must be used.

    • Java RTO API on Windows
    • The SSPI that is distributed with Windows is used.

    • C API on Linux and SunOS
    • Libraries that implement GSSAPI Version 2 must be used.

    • C APIs on Windows
    • The Security Support Provided Interface (SSPI) that is distributed with Windows is used.

    • .NET API
    • The SSPI that is distributed with Windows is used.

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

    To enable Kerberos authentication for JCSMP, 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.