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.

To Set an Authentication Scheme

PubSub+ Messaging API Property

JCSMP

  • JCSMPProperties.AUTHENTICATION_SCHEME_BASIC

  • JCSMPProperties.AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE

  • JCSMPProperties.AUTHENTICATION_SCHEME_GSS_KRB

  • JCSMPProperties.AUTHENTICATION_SCHEME_OAUTH2

Java RTO

SessionHandle.PROPERTIES.AUTHENTICATION_SCHEME

Possible values in SolEnum.AuthenticationScheme are:

  • AuthenticationScheme.BASIC

  • AuthenticationScheme.CLIENT_CERTIFICATE

  • AuthenticationScheme.GSS_KRB

  • AuthenticationScheme.OAUTH2

C

  • SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_BASIC

  • SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE

  • SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_GSS_KRB

  • SOLCLIENT_SESSION_PROP_AUTHENTICATION_SCHEME_OAUTH2

.NET

SessionProperties.AuthenticationSchemes

Possible values for the enumeration are:

  • AuthenticationSchemes.BASIC

  • AuthenticationSchemes.CLIENT_CERTIFICATE

  • AuthenticationSchemes.GSS_KRB

  • AuthenticationSchemes.OAUTH2

JavaScript

Possible values for the enumeration are:

  • solace.AuthenticationScheme.BASIC

  • solace.AuthenticationScheme.CLIENT_CERTIFICATE

  • solace.AuthenticationScheme.OAUTH2

Node.js

Possible values for the enumeration are:

  • solace.AuthenticationScheme.BASIC

  • solace.AuthenticationScheme.CLIENT_CERTIFICATE

  • solace.AuthenticationScheme.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

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

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 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 JCSMP API.

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.

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:

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.

To Set a OAuth2 Access Token and Optional Issuer Identifier

PubSub+ Messaging API Use

JCSMP

JCSMPProperties.OAUTH2_ACCESS_TOKEN

JCSMPProperties.OAUTH2_ISSUER_IDENTIFIER

Java RTO

PROPERTIES.SESSION_OAUTH2_ACCESS_TOKEN

PROPERTIES.SESSION_OAUTH2_ISSUER_IDENTIFIER

C

SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN

SOLCLIENT_SESSION_PROP_OAUTH2_ISSUER_IDENTIFIER

.NET

SessionProperties.Oauth2AccessToken

SessionProperties.Oauth2IssuerIdentifier

JavaScript and Node.js

solace.SessionProperties.accessToken

solace.SessionProperties.issuerIdentifier

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.

To Set an OpenID Connect ID Token and Optional Access Token

PubSub+ Messaging API Use

JCSMP

JCSMPProperties.OIDC_ID_TOKEN

JCSMPProperties.OAUTH2_ACCESS_TOKEN

Java RTO

PROPERTIES.SESSION_OIDC_ID_TOKEN

PROPERTIES.SESSION_OAUTH2_ACCESS_TOKEN

C

SOLCLIENT_SESSION_PROP_OIDC_ID_TOKEN

SOLCLIENT_SESSION_PROP_OAUTH2_ACCESS_TOKEN

.NET

SessionProperties.OidcIdToken

SessionProperties.Oauth2AccessToken

JavaScript and Node.js

solace.SessionProperties.idToken

solace.SessionProperties.accessToken

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.

To Refresh OAuth Token

PubSub+ Messaging API Use

C

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) {
}

Java RTO

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

JavaScript and Node.js

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

JCSMP

session.setProperty(JCSMPProperties.OAUTH2_ACCESS_TOKEN, newAccessToken);

.NET

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.