Client Authentication Management

Client authentication schemes that are configured for a Message VPN specify what credentials that a connecting client can provide for the message broker to authenticate that client. For the client to be successfully authenticated and then permitted to establish a connection to the Message VPN, the client must provide the expected credentials to fulfill the requirements of a configured and enabled authentication scheme.

One or more of the following types of client authentication schemes can be configured for a Message VPN:

  • Basic authentication—The default client authentication scheme for a Message VPN; it allows a client to authenticate with a message broker using a valid client name, client username, and optional password.
  • Client Certificate authentication—This is a client authentication scheme allows a client to prove its identity to a Solace PubSub+ message broker through an X509v3 client certificate from a recognized Certification Authority (CA).
  • Kerberos authentication—This authentication scheme allows a client to use the Kerberos mechanism within the GSSAPI (Generic Security Service API) to authenticate its connection with the message broker. To authenticate with the Solace PubSub+ message broker, the client must provide a Service Ticket obtained from the KDC ticket granting service (TGS). KDC services are hosted on an external server.

A connecting client indicates through its session properties which authentication scheme it wants to use and has the proper authentication credentials for. If the requested authentication scheme is enabled for the Message VPN on the message broker, the message broker will attempt to authenticate the client using that scheme. If the requested authentication scheme is not enabled for the Message VPN, the message broker will not attempt to authenticate the client, and a connect error indicating that the authentication scheme is not enabled is returned to the client.

Basic Authentication Configuration

Basic authentication is the default client authentication scheme used for by Solace PubSub+. This authentication scheme allows a client to connect to a Message VPN over a non‑Transport Layer Security (TLS)/Secure Sockets Layer (SSL) connection and authenticate with that message broker using a valid client name, client username, and optional password.

To configure basic authentication for client connections to the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication
solace(configure/message-vpn/authentication)# user-class client
solace(...message-vpn/authentication/user-class)# basic

The CLI is now at a level from which you can perform the following configuration tasks for the basic authentication scheme used for the given Message VPN:

Assigning RADIUS Domain Strings

When you are using a RADIUS authentication type, you can assign a RADIUS domain string to the given Message VPN so that outgoing RADIUS access requests will have the string appended to the client name.

To assign a RADIUS domain string for the given Message VPN, enter the following CONFIG command:

solace(...message-vpn/authentication/user-class)# basic
solace(...e-vpn/authentication/user-class/basic)# radius-domain <auth-domain>

Where:

<auth-domain> is an authentication domain string to append to usernames in outgoing RADIUS Access-Requests.

The no version of this command, no radius-domain, removes a configured RADIUS domain string.

Configuring Authentication Types

To configure the authentication type to use for basic authentication of clients, enter the following CONFIG command:

solace(...message-vpn/authentication/user-class)# basic
solace(...e-vpn/authentication/user-class/basic)# auth-type {radius <radius-profile> | ldap <ldap-profile> | internal | none}

The no version of this command, no authentication user-class, resets the authentication parameters back to the default RADIUS authentication type.

auth-type is the authentication type to be configured. It can be one of the following:

  • none indicates users are automatically authenticated. This is not recommended by Solace.
  • radius indicates users are authenticated using provisioned Remote Authentication Dial-in User Service (RADIUS) servers through the specified RADIUS profile name. This is the default authentication type.

    To use a RADIUS authentication type, an external RADIUS server must be configured and provisioned for use by the message broker. (Refer to your third‑party RADIUS server documentation for information on choosing a host machine and installing the server software.) If no RADIUS server is available to the message broker, and this default authentication type is used, then no users will be allowed to connect to the message broker.

  • ldap indicates users are authenticated using provisioned Lightweight Directory Access Protocol (LDAP) servers through the specified LDAP profile name.

    To use a LDAP authentication type, an external LDAP server must be configured and provisioned for use by the message broker. (Refer to your third‑party LDAP server documentation for information on choosing a host machine and installing the server software.)

  • internal indicates users are authenticated using locally-stored account information.

    Note:  There is a single client username named default that exists in each Message VPN, and it is assigned to all clients. A password must be assigned to the client username named default before enabling internal authentication for client users. Otherwise, clients cannot successfully authenticate with the message broker.

Enabling/Disabling Basic Authentication for Clients

  • To enable basic authentication for clients connecting to the Message VPN, enter the following CONFIG commands:

    solace(...message-vpn/authentication/user-class)# basic
    solace(...e-vpn/authentication/user-class/basic)# no shutdown

  • To disable basic authentication for clients connecting to the Message VPN, enter the following CONFIG commands:

    solace(...message-vpn/authentication/user-class)# basic
    solace(...e-vpn/authentication/user-class/basic)# shutdown

Basic Authentication Examples

The following example shows a sample command sequence that sets a basic authentication type for a Message VPN, and then sets the authentication type for client users to RADIUS.

The following example shows how to show the currently configured authentication type.

Client Certificate Authentication Configuration

To implement client certificate authentication for connecting clients, the following configurations are required on the Solace PubSub+ message broker:

Prior to Solace PubSub+ appliance release 8.2.0, while validating the client certificate, the message broker did not check the revocation status of the client certificates. As of Solace PubSub+ 8.2.0, checking of the revocation status for client certificates is supported. To configure your message broker to enable client certificate revocation checking, see Certificate Authorities.

Note:  The client-side requirements for using client certificate authentication include setting specific session properties and creating a secure client session. When using Solace messaging APIs, see Creating Client Sessions, when using the Solace JMS messaging API, see Establishing Connections. Client certificate authentication is not available for Solace Web messaging APIs.

Configuring Client Certificate Parameters for Message VPNs

Perform the following client certificate authentication parameters for the given Message VPN:

Allowing API-Provided Usernames

To authenticate with a Solace PubSub+ message broker and connect to a Message VPN, a connecting client must provide the Solace message broker with a valid client username. By default, when using client certificates, the common name (CN) in a client certificate’s subject is used as the client username. Alternatively, you can configure a Message VPN to use a client username that the client provides through a session property. In that case, the client certificate is still used for the initial authentication, but the API-provided username is used for the subsequent authorization (that is, to determine the client profile, ACL profile, and queue ownership for the client).

Note  
  • The client username must be configured on the Message VPN. If the client username does not exist, the client username named default is used. For more information, see Client Username Configuration.
  • For MQTT clients using client certificate authentication, the use of the allow-api-provided-username option is not supported.

The use of this option is generally not recommended. Allowing client‑provided usernames provides less security than using the CN in the certificate because it permits an authenticated user to assume any client username rather than restricting that authenticated user to a particular client username.

To use an API-provided username, instead of the common name in the client certificate’s subject, enter the following CONFIG command:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication user-class client
solace(...message-vpn/authentication/user-class)# client-certificate
solace(...ication/user-class/client-certificate)# allow-api-provided-username

Note:  The no version of this command (no allow-api-provided-username) uses the common name in the client certificate's subject.

Configuring Max Certificate Chain Depths

The depth of a client certificate chain is the number of signing CA certificates that are present in the chain back to a trusted root CA.

To set the maximum depth for a client certificate chain that can be accepted, enter the following command:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication user-class client
solace(...message-vpn/authentication/user-class)# client-certificate
solace(...ication/user-class/client-certificate)# max-certificate-chain-depth <max-depth>

Where:

max-depth is the maximum depth that will be accepted for a client certificate chain. The valid range is 0 to 8. The default value is 3.

The no version of this command, no max-certificate-chain-depth, resets the maximum depth to the default value.

Configuring Validate Certificate Dates

To enable the validation of the “Not Before” and “Not After” validity dates in a client certificate, enter the following CONFIG command:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication user-class client
solace(...message-vpn/authentication/user-class)# client-certificate
solace(...ication/user-class/client-certificate)# validate-certificate-date

Note:  The no version of this command, no validate-certificate-date, disables the validation of the “Not Before” and “Not After” validity dates in a client certificate. When disabled, a certificate is accepted even if the certificate is not valid according to the “Not Before” and “Not After” validity dates in the certificate.

Configuring Client Username Sources

To authenticate with a Solace PubSub+ message broker and connect to a Message VPN, a connecting client must provide the message broker with a valid client username. By default, when using client certificates, the message broker extracts the CN from the Subject Name field in a given certificate and uses it as the client username. Alternatively, on a Solace PubSub+ appliance, you can configure a Message VPN to use the subject alternative name (SAN) extension in the certificate as the client username source.

If you configure the SAN as the username source:

  • All of the current client username character restrictions apply. For example, if the SAN in a client certificate contains more than 189 characters it is considered invalid and authentication fails. For more information, see Client Username Configuration.
  • If the allow-api-provided-username option is enabled, the username provided by the API supersedes the SAN.
  • If the allow-api-provided-username option is not enabled, when a client attempts to connect to the Message VPN and no SAN is found in the certificate, the authentication fails.
  • The SAN extension in the client certificate must carry a Microsoft Universal Principal Name (msUPN) through the use of the otherName field. No other identity, for example email address, DNS name, or IP address is supported.

To configure the client username source, enter the following CONFIG command:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication user-class client
solace(...message-vpn/authentication/user-class)# client-certificate
solace(...ication/user-class/client-certificate)# username-source {common-name | subject-alternative-name-msupn}

Where:

common-name specifies to use the CN in the client certificate as the client username when clients authenticate against the given Message VPN. This is the default setting.

subject-alternative-name-msupn specifies to use the msUPN (in the otherName field) in the SAN extension of the client certificate as the client username when clients authenticate against the given Message VPN.

The no version of this command, no user-name source, resets the message broker to the default setting.

Enabling Client Certificate Authentication For Clients

  • To enable client certificate authentication for clients connecting to the given Message VPN, enter the following CONFIG command:

    solace(...ication/user-class/client-certificate)# no shutdown

  • To disable client certificate authentication for clients connecting to the given Message VPN, enter the following CONFIG command:

    solace(...ication/user-class/client-certificate)# shutdown

Kerberos Authentication Configuration

To implement Kerberos authentication for clients connecting to a Solace PubSub+ message broker, the following configurations are required on a message broker:

Note  
  • The client-side API requirements for a client to use Kerberos authentication include using the appropriate Java distribution or installed Kerberos libraries for the messaging API that is used (see Quick Start for Solace enterprise APIs or Quick Start for Solace JMS API). A client application must also set the authentication scheme to Kerberos for the respective session (see Creating Client Sessions for the Solace messaging APIs or Establishing Connections for the Solace JMS API). Kerberos authentication is not available for Solace Web messaging APIs.
  • Kerberos authentication is not supported for MQTT clients.
Notice  

Config-Sync will not automatically synchronize the objects/properties discussed in this section. Therefore, if the message broker is being used in a high-availability (HA) pair or in a replicated site, you must manually configure these objects/properties on each mate message broker or replicated Message VPN.

To determine whether an object/property is Config-Syncʼed, look up the command used to configure the object/property in the CLI Command Reference, or, in the Solace CLI, end the command with “?”. The Help will list whether the object/property is Config-Syncʼed.

Managing Kerberos Keytabs

To facilitate Kerberos authentication, the appropriate keytab entries must be added to the message broker’s
/keytab directory. A typical deployment would use at least three keytab entries—one for each virtual IP address of the message broker and one for the physical IP address of the message broker (for example, keys for solace/primary-virtual-router-dnsname@REALM, solace/backup-virtual-router-dnsname@REALM, and solace/physical-router-dnsname@REALM). For some deployments, additional keytab entries will be required (for example, for a deployment where Ethernet interfaces have not been grouped into a LAG, and each interface has its own set of IP addresses and DNS names).

Adding Keytab Entries

To add a key from a .keytab file in the message broker’s /keytab directory to the message broker’s registered keys, enter the following CONFIG command:

solace(configure)# authentication kerberos keytab
solace(configure/authentication/kerberos/keytab)# add-keytab <keytab-filename> <index>

Where:

<keytab-filename> is the filename of the keytab file. This keytab file must be located in the message broker’s /keytab directory, and it must have a group permission of at least read. Note that if the keytab file was transferred to the message broker using a Solace file transfer user account, then the file should have the correct permissions.

<index> is the index of the key in the keytab file to be installed. If no index is specified, the message broker takes the first key.

Note  
  • A VRF interface can be configured with a specific Service Principal Name (SPN) value. When an SPN value is assigned to an interface, clients connecting on that interface must supply a service key that matches a key in the Solace PubSub+ message broker key table and have a matching SPN and Key Version Number (KVNO).
  • When no SPN value is assigned to an interface, clients may connect on that interface using any SPN value as long as the client’s service key matches a key on the Solace PubSub+ message broker key table.
  • It is recommended that you use unique passwords to generate service keys for multiple Solace PubSub+ message broker.
  • If you use RC4 encryption, the password used to generate the key is not salted with the provided SPN value. If you use the same password to generate service keys for multiple Solace PubSub+ message brokers, then a client may be able to connect to any of the message brokers on which the same password was used to generate a service key, even if those message brokers have different SPNs.
  • If you use AES encryption to generate service keys, the password used to generate the service key is salted with the provided SPN value. As a result, using the same password with different SPN values results in unique keys being generated.

Deleting Keytab Entries

To delete a Kerberos key from the message broker’s key table, enter the following CONFIG commands:

solace(configure)# authentication kerberos keytab
solace(configure/authentication/kerberos/keytab)# delete-keytab-entry <index>

Where:

<index> is the index of the key in the message broker’s keytab store.

Displaying Kerberos Keytab Information

To display the Kerberos keys installed on the Solace PubSub+ message broker, including the total number of keys in the key table, and any SPN value mapped to a message backbone VRF, enter the following User EXEC command:

show> kerberos [{keytab | keytab-file <file-name>} [detail]]

Where:

keytab specifies to display the Kerberos keys installed on the message broker’s internal keytab store.

keytab-file <file-name> specifies to display the Kerberos keys contained within the specified keytab file in the message broker’s /keytab directory. Wildcards are allowed for the file name to specify multiple filenames.

detail specifies to display detailed information about each keytab entry.

Allowing API-Provided Usernames

An authenticating client must provide the Solace PubSub+ message broker with a valid client username. By default, when using Kerberos authentication, the Kerberos User Principal name in a Kerberos token is used as the client username. Alternatively, a Message VPN may be configured to use a client username that the client provides through the session properties used to establish the client connection. In that case, the client Kerberos token is still used for the initial authentication, but the API‑provided username is used for the subsequent authorization (that is, to determine the client’s client username).

When the allow-api-provided-username option is not enabled, if the client’s Kerberos user principal name does not match a client username provisioned on the Message VPN, the default username is used. Therefore, when the allow-api-provided-username option is not enabled, ensure that you provision client usernames that match the Kerberos user principals in use and that the default username is shutdown.

To enable API-provided usernames to be used instead of the Kerberos Principal name in a Kerberos token, enter the following CONFIG command:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication user-class client
solace(...message-vpn/authentication/user-class)# kerberos
solace(...pn/authentication/user-class/kerberos)# allow-api-provided-username

The no version of this command, no allow-api-provided-username, disables this option so that the Kerberos User Principal name from the client token is used as the "username" for authorization.

Note:  If the allow-api-provided-username option is used, and no client username is provided in the session properties, the default client user name for the Message VPN will be used for authorization.

Enabling Kerberos Client Authentication

  • To enable Kerberos authentication for clients connecting to the given Message VPN, enter the following CONFIG commands:

    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# authentication user-class client
    solace(...message-vpn/authentication/user-class)# kerberos
    solace(...pn/authentication/user-class/kerberos)# no shutdown

  • To disable Kerberos authentication for clients connecting to the given Message VPN, enter the following CONFIG commands:

    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# authentication user-class client
    solace(...message-vpn/authentication/user-class)# kerberos
    solace(...pn/authentication/user-class/kerberos)# shutdown

Duplicate Client Connect Behavior Configuration

When a new client connects to a message broker, and that client uses the same client name as an existing connected client, you can configure the message broker to either:

  • reject the new duplicate client’s connection attempt (that is, not replace the existing client)
  • disconnect the existing client and connect the new duplicate client

Note:  By default, the replacement of duplicate client connections during authentication is enabled on the message broker.

To enable the replacement of duplicate client connections during authentication, enter the following CONFIG commands:

solace(configure)# authentication
solace(configure/authentication)# replace-duplicate-client-connections

The no version of this command, no replace-duplicate-client-connections, disables the replacement of duplicate client connections during authentication.

Notice  

When used with Web messaging clients, disabling the replacement of duplicate client connections during authentication by the no replace-duplicate-client-connections Authentication CONFIG command could cause a temporary service outage when experiencing momentary network congestion. This is due to the time that the message broker takes to expire the old Web client session before accepting the replacement.