Client Authentication

When an application or device connects to a particular Message VPN, the resulting client connection must be authenticated before any client requests can be processed. A connecting client is authenticated on a per-Message VPN‑basis through one of the following client authentication schemes:

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

More than one type of authentication scheme can be configured and enabled for a Message VPN, but a client can only be configured to use one type of authentication scheme.

Basic Authentication

A basic authentication scheme allows a connecting client to authenticate with an event broker by providing a valid client username and password as its credentials.

Basic authentication is the default client authentication scheme for a Message VPN. It's available for client applications using any Solace messaging API. It's also available for client applications using OpenMAMA API, REST, AMQP, or MQTT.

Clients can use Basic authentication for either a plain-text or a Transport Layer Security (TLS) / Secure Sockets Layer (SSL)-encrypted client connection to the event broker.

This authentication scheme uses one of the following authentication types:

• Internal

The client username and password provided by the client are verified against an internal event broker database.

• RADIUS

The client username and password are sent to an external RADIUS server for authentication.

• LDAP

The client username and password are sent to an external LDAP server for authentication.

• None

No client authentication is performed for the client. Solace strongly recommends against using no client authentication.

Provisioning & Configuration Information

To use basic authentication to authenticate connecting clients, the following configuration is required for the following areas:

• Client configuration
  • For clients using Solace messaging APIs, their client username and password are provided as configurable session properties.
  • For information on using Basic Authentication with Solace APIs, see:
  • Basic Authentication for Solace enterprise APIs.
  • Basic Authentication for Solace's JMS API.
  • For OpenMAMA clients, basic authentication parameters are configured for the Solace Middleware Bridge that is used to establish a connection to the event broker.For more information, see the Authentication Scheme section in Per-Transport Properties.
  • For REST clients, the client username and password are provided as a string in an HTTP standard header. See Client Authentication.
  • For MQTT clients, the connect packet contains username and password fields. The CONNECT Packet contains Username and Password fields. These are mapped to a Solace client username and password. For more information, see 3.1.3.4 User Name in the Solace MQTT 3.1.1 Messaging Protocol Conformance section.
• Event broker configuration
  • A client username and password combination must be configured and enabled for internal authentication.

  For information on the system and Message VPN-level configurations that are required on an event broker to implement a basic authentication scheme, refer Basic Authentication.

For REST and MQTT clients

For REST and MQTT clients, there are some additional Message VPN configurations, such as enabling the appropriate listen ports, are required. For more information, see REST Messaging Management and Using MQTT.

Client Certificate Authentication

A client certificate authentication (also referred to as mutual TLS or mTLS) scheme allows a client to prove its identity to the event broker by providing a valid X509v3 client certificate from a recognized Certificate Authority (CA).

For this authentication scheme, the common name (CN) of the certificate provided to the event broker is mapped to the client’s assigned client username, which can be used for subsequent client authorization. Alternatively, you can configure a different source for the client username. For details, see Configuring Client Username Sources.

If your deployment cannot guarantee that the username extracted from the certificate is unique across certificates issued by all of the CAs configured on the broker, you may want to configure client certificate to Message VPN matching to restrict the types of certificates that can be used as credentials in a Message VPN. For details, see Configuring Client Certificate to Message VPN Matching.

Client certificate authentication is available for clients using Solace enterprise messaging APIs. It's also available for client applications using OpenMAMA API, REST, AMQP, or MQTT.

Provisioning & Configuration Information

To use client certificates to authenticate connecting clients, the following configuration is required for the following areas:

• Client configuration
  • For clients using Solace messaging APIs, secure sessions must be used to establish TLS/SSL-encrypted client connections to the event broker. To create a secure session, a client certificate authentication scheme, client certificate, and a private key (depending on the API used, these could be separate files or be contained in a single keystore file) must be specified.
  • For information on using Client Certificate Authentication with Solace APIs, see:
    • Client Certificate Authentication for Solace enterprise APIs.
    • Client Certificate Authentication for Solace's JMS API.
  • For OpenMAMA clients, client certificate authentication parameters are configured for the Solace Middleware Bridge that is used to establish a connection to the event broker. For more information, see the Authentication Scheme section in Per-Transport Properties.
  • TLS/SSL authentication is supported for REST clients. For information, see Client Authentication.
  • TLS/SSL authentication is supported for MQTT clients. For information, see MQTT Protocol Conformance, Section 5 Security.
• Event broker configuration
  1. PubSub+ 6.1 or greater must be used.
  2. CA certificates must be loaded onto the event broker. Client certificate authentication must be configured and enabled for any Message VPNs that the clients will connect to.
  3. To enable the required secure client connections, TLS/SSL service must be configured and enabled.

  For further information about event broker configuration refer to Client Certificate Authentication.

For REST and MQTT clients

For REST and MQTT clients, some additional Message VPN configurations, such as enabling the appropriate listen ports, are required. For more information, see REST Messaging Management and Using MQTT.

For Message VPN bridges, Message VPN replication bridges, and Replication Config-Sync bridges

Client certificate authentication can be used on Message VPN bridges, Message VPN replication bridges, and Replication Config-Sync bridges. For more information, see TLS/SSL Service Connections.

For DMR clusters

Client certificate authentication can also be used on DMR clusters. For more information, see Configuring Authentication Using Client Certificates.

Kerberos Authentication

A Kerberos authentication scheme allows clients that have been granted a valid Kerberos ticket to connect to an event broker.

Kerberos authentication is only available for clients using Solace enterprise messaging APIs or the OpenMAMA API.

When a Kerberos authentication scheme is used for client authentication, a client must first authenticate with a Kerberos Authentication Server (AS) which grants the client a Ticket Granting Ticket (TGT) for a specified Kerberos User Principal. The TGT is typically obtained as part of a Single Sign-on procedure, such as logging into a Windows domain. With a valid TGT, a client can attempt to log onto an event broker using a service ticket that is in the client’s local ticket cache or has been obtained from the Ticket Granting Service (TGS). The AS and TGS (components of a Key Distribution Center (KDC)) are hosted on an external server or servers—not on an event broker.

The client then provides this time-stamped "Kerberos" ticket to the event broker. If the ticket is successfully validated, the client’s connection to the Message VPN is granted.

For this authentication scheme, the client’s assigned client username, which is used for subsequent client authorization, is the user principal name in the ticket provided to the event broker.

Provisioning & Configuration Information

To use Kerberos to authenticate clients connecting to an event broker, the following configurations are required:

• Client-side configuration
  • For clients using Solace messaging APIs, the appropriate Java distribution must be used or the appropriate Kerberos libraries must be installed for the Solace messaging API used, and the client session must use a Kerberos authentication scheme.
  • For information on setting a Kerberos authentication scheme using Solace APIs, see:
    • Kerberos Authentication for Solace messaging APIs.
    • Kerberos Authentication for Solace's JMS API.
  • For OpenMAMA clients, Kerberos authentication parameters are configured for the Solace Middleware Bridge used to establish a connection to the event broker. For more information, see the Authentication Scheme section in Per-Transport Properties.
• Event broker configuration
  1. PubSub+ 7.0 or greater must be used.
  2. A Kerberos Keytab must be loaded on the event broker.
  3. Kerberos authentication must be configured and enabled for any Message VPNs that Kerberos-authenticated clients will connect to.
  4. Optional: A Kerberos Service Principal Name (SPN) can be assigned to the IP address for the message backbone VRF that will be used for Kerberos‑authenticated clients. For information, see Kerberos Authentication.

Supported Encryption Types

The following table shows the supported encryption types.

Encryption Type
aes256-cts-hmac-sha1-96
aes128-cts-hmac-sha1-96
des3-cbc-sha1
arcfour-hmac-md5

OAuth Authentication

OAuth is an open standard for access delegation, commonly used as a way for users to grant websites or applications access to their information on other websites without giving them access to their passwords. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials. More specifically, an OAuth authentication scheme allows access tokens issued to third-party clients by an authorization server to be used to access Message VPNs on PubSub+ event brokers.

For this authentication scheme, the client's assigned client username, which is used for subsequent client authorization, is extracted from the token provided to the event broker.

Provisioning & Configuration Information

To use OAuth to authenticate clients connecting to an event broker, the following configurations are required:

• Client-side configuration

  • For SMF clients, each API has specific methods or functions for passing Access or ID tokens to the event broker. See Defining Client Authentication Info.

  • For MQTT clients, passwords must adhere to one of the following forms:

    If the OAuth profile is configured with the oauth-role set to resource-server:

    OAUTH~<profile>~<access_token>

    If the OAuth profile is configured with the oauth-role set to client:

    OPENID~<profile>~<id_token>~<access_token>

    Where:

    <profile> must match an OAuth profile configured on the event broker. If no profile is provided, the iss claim in the ID token (for OpenID) or access token (for OAuth), if present, is used to identify which OAuth profile to use. If no profile with a matching issuer is found, the default profile is used.

    <access_token> is the access token given to the client by the authorization server. For OpenID, the access token is optional and can be omitted if it is not needed.

    <id_token> is the OpenID Connect ID token represented as a JWT given to the client by the authorization server.

    In addition, the maximum length of the password is 8192 bytes and the maximum length for each token is 4096 bytes.

  • For REST producers, requests must include one or more OAuth tokens in the HTTP Authorization header as a bearer token in one of the following forms:

    If the OAuth profile is configured with the oauth-role set to resource-server:

    Bearer <access_token>

    If the OAuth profile is configured with the oauth-role set to client:

    Bearer <id_token>/<access_token>

    Where:

    <access_token> is the access token given to the client by the authorization server. For OpenID, the access token is optional and can be omitted if it is not needed.

    <id_token> is the OpenID Connect ID token represented as a JWT given to the client by the authorization server.

    The maximum header length supported is 8KiB; the maximum ID token or access token size is 4KiB.

    The bearer token in the Authorization header must be provided on every request.

    In general, the iss claim in the ID token (for OpenID Connect) or access token (for OAuth 2.0), if present, is used by the event broker to identify which OAuth profile to use.

    A specific OAuth profile can also be selected by adding ~base64(<issuer>)~ to the beginning of the bearer token. Base64 padding should not be used. For example, to use an OAuth profile called solace that has an issuer of https://www.solace.com with an access token:

    Bearer ~aHR0cHM6Ly93d3cuc29sYWNlLmNvbQ~<access_token>

    If a profile cannot be identified from the iss claim in the token, and no issuer prefix is provided in the Authorization header, the default profile is used.

    If your deployment also uses REST consumers, and you want them to authenticate with REST hosts using OAuth, you must configure the appropriate authentication scheme. See Configuring REST Consumer Authentication Schemes.

  • For AMQP clients, PubSub+ event brokers support the XOAUTH2 SASL authentication mechanism. In this case, the AMQP URL must be amqps://<host>:<port>?amqp.saslMechanisms=XOAUTH2.

    The XOAUTH2 authentication mechanism allows an AMQP client to specify an OAuth 2.0 bearer token in the password field of the connection as a Base64 encoded token without any prefix, in other words:

    user=<username>

    password=<access token>

    Where:

    <username> is a placeholder. The client username is derived from the access token.

    <access token> is the same value that would be used in an HTTP Authorization header with a bearer token without the Bearer prefix.

    The bearer token must be provided on every request. In many cases, the token will be a JSON web token (JWT) with an issuer claim that matches an OAuth profile. The event broker will verify the token and automatically select the correct profile. If the token is not a JWT or if the issuer does not match, the default OAuth profile is used. If there are multiple profiles for which the issuer cannot be automatically determined from the token, an OAuth profile can also be explicitly specified in the token.

• Event broker configuration
  1. PubSub+ 9.12.1 or greater must be used.
  2. OAuth authentication must be configured and enabled for any Message VPNs that OAuth-authenticated clients will connect to. See Enabling OAuth Client Authentication.
  3. An OAuth profile must be configured and enabled on the message broker. See Managing Message VPN OAuth Profiles.