Defining Client Authentication Info

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.

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 (this is 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.

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.

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.

JCSMP

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.

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.

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. See 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, JCSMP 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.

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.

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 Solace Messaging APIs (JavaScript, JCSMP, Java RTO, CCSMP, .NET, C) so that it's valid the next time the client tries to connect.

propIndex = 0;
modifyProps[propIndex++] = SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN;
modifyProps[propIndex++] = "newAccessToken";
modifyProps[propIndex]   = NULL;
if (solClient_session_modifyProperties(session_p, modifyProps) == SOLCLIENT_OK) {
}

tokenUpdate[1] = newAccessToken;
session.modifyProperties(tokenUpdate);

session.updateAuthenticationOnReconnect({accessToken : “newAccessToken”});

session.setProperty(JCSMPProperties.OAUTH2_ACCESS_TOKEN, newAccessToken);

session.ModifyProperty(SessionProperties.PROPERTY.OAuth2AccessToken, 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.