Client Authentication Configuration

Client authentication schemes that are configured for a Message VPN specify what credentials that a connecting client can provide for the event 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 Configuration
  • The default client authentication scheme for a Message VPN; it allows a client to authenticate with an event broker using a valid client name, client username, and optional password.

  • Client Certificate Authentication Configuration
  • This authentication scheme allows a client to prove its identity to a Solace PubSub+ event broker through an X509v3 client certificate from a recognized Certification Authority (CA).

  • Kerberos Authentication Configuration
  • This authentication scheme allows a client to use the Kerberos mechanism within the GSSAPI (Generic Security Service API) to authenticate its connection with the event broker. To authenticate with the Solace PubSub+ event broker, the client must provide a Service Ticket obtained from the key distribution center (KDC) ticket granting service (TGS). KDC services are hosted on an external server.

  • OAuth Authentication Configuration
  • This authentication scheme allows a client to use the OAuth mechanism to authenticate its connection with the event broker. To authenticate with the Solace PubSub+ event broker, the client must provide a valid access token obtained from an OAuth authorization 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 event broker, the event broker will attempt to authenticate the client using that scheme. If the requested authentication scheme is not enabled for the Message VPN, the event 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 event 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(...message-vpn/authentication)# 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)# basic
solace(...e-vpn/authentication/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)# basic
solace(...e-vpn/authentication/basic)# auth-type {radius <radius-profile> | ldap <ldap-profile> | internal | none}

The no version of this command, no authentication, 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 event 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 event broker, and this default authentication type is used, then no users will be allowed to connect to the event 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 event 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 event 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)# basic
solace(...e-vpn/authentication/basic)# no shutdown

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

solace(...message-vpn/authentication)# basic
solace(...e-vpn/authentication/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+ event broker:

Prior to Solace PubSub+ appliance release 8.2.0, while validating the client certificate, the event 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 event 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

You can configure the following client certificate authentication parameters for the given Message VPN:

Allowing API-Provided Usernames

To authenticate with a Solace PubSub+ event broker and connect to a Message VPN, a connecting client must provide the Solace event 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 and REST 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
solace(...message-vpn/authentication)# client-certificate
solace(...ication/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
solace(...message-vpn/authentication)# client-certificate
solace(...ication/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
solace(...message-vpn/authentication)# client-certificate
solace(...ication/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+ event broker and connect to a Message VPN, a connecting client must provide the event broker with a valid client username. By default, when using client certificates, the event 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.
  • If there are multiple SAN extensions with msUPN, the first is taken.

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

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication
solace(...message-vpn/authentication)# client-certificate
solace(...ication/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 event 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/client-certificate)# no shutdown

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

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

Kerberos Authentication Configuration

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

  1. A Kerberos Keytab must be loaded on the event broker. See Event Broker File Management.
  2. Kerberos authentication must be configured and enabled for any Message VPNs that Kerberos-authenticated clients will connect to. See Enabling Kerberos Client Authentication.
  3. Optional: On an appliance, a Kerberos Service Principal Name (SPN) can be assigned to the IP address for the message backbone VRF Kerberos‑authenticated clients will use. See Configuring Kerberos Service Principal Names configuration option in Configuring Management & Message Backbone Interfaces.
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 event 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 event 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 event broker’s
/keytab directory. A typical deployment would use at least three keytab entries—one for each virtual IP address of the event broker and one for the physical IP address of the event 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 event broker’s /keytab directory to the event 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 event 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 event 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 event broker takes the first key.

Note  
  • On an appliance, 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+ event 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+ event broker key table.
  • It is recommended that you use unique passwords to generate service keys for multiple Solace PubSub+ event brokers.
  • 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+ event brokers, then a client may be able to connect to any of the event brokers on which the same password was used to generate a service key, even if those event 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 event 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 event broker’s keytab store.

Displaying Kerberos Keytab Information

To display the Kerberos keys installed on the Solace PubSub+ event 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 event broker’s internal keytab store.

keytab-file <file-name> specifies to display the Kerberos keys contained within the specified keytab file in the event 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+ event 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
solace(...message-vpn/authentication)# kerberos
solace(...pn/authentication/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
solace(...message-vpn/authentication)# kerberos
solace(...pn/authentication/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
solace(...message-vpn/authentication)# kerberos
solace(...pn/authentication/kerberos)# shutdown

OAuth Authentication Configuration

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

  1. OAuth authentication must be configured and enabled for any Message VPNs that OAuth-authenticated clients will connect to. See Enabling OAuth Client Authentication.
  2. An OAuth provider must be configured and enabled on the event broker. See Managing OAuth Providers.

Note:  Solace PubSub+ event brokers support OAuth authentication only for MQTT clients.

Managing OAuth Providers

OAuth providers contain information about the issuer of the token that is needed to validate the token and derive a client username from it. OAuth providers hold configured information such as the location of the introspection endpoint for a particular authorization server or keys used to verify the signature of a JSON Web Token (JWT).

Many public systems that use OAuth have either one specific OAuth authorization server they are designed to use, or a small number of specific servers. Solace PubSub+ event brokers can use any standards compliant OAuth authorization server, but to do this, the following specific information must be known about the server.

  • Name—This is a free-form label that will be assigned to this specific provider. It must conform to the provider specified by the client during login (or must be set up as the default provider).
  • Token Introspection Connection Parameters—The address and credentials used to introspect an access_token (required only if token introspection is used).
  • JSON Web Key Set (JWKS) Refresh URI—The location this provider makes their JWKS keys available from, and how often to refresh them (required only if JWTs are used).

To create an OAuth provider, enter the following commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication
solace(...message-vpn/authentication)# oauth
solace(...e-vpn/authentication/oauth)# create provider <provider>

To configure an existing provider, enter the following command:

solace(...e-vpn/authentication/oauth)# provider <provider>

To enable the provider, enter the following command:

solace(...hentication/oauth/provider)# no shutdown

You can also specify a default OAuth provider you want clients to use if they do not specify a provider name. If no default provider is configured, every client must specify a provider name as part of their password.

To specify a default provider, enter the following command:

solace(...e-vpn/authentication/oauth)# default-provider <provider>

Where:

<provider> is a free-form label that is assigned to this specific provider. It must conform to the provider name specified by the client during login.

The configuration tasks you can perform for an OAuth provider include:

Configuring OAuth Authorization Settings

You can enable OAuth for client authorization and authentication instead of just authentication. For more information about configuring OAuth authorization settings for providers, see OAuth Authorization Configuration.

Configuring Client Disconnects Due to Token Expiry

You can configure whether the event broker disconnects clients when their token expires, or allows client connections to continue beyond the expiration of the tokens. This value is applied to clients at login. Changing this setting does not affect clients that are currently connected to the event broker.

To enable the event broker to disconnect clients when their token expires, enter the following command:

solace(...pn/authentication/oauth/provider)# disconnect-on-token-expiration

Configuring OAuth Token Authentication Settings

Solace PubSub+ event brokers support two different types of OAuth tokens: access_token and id_token. The OAuth standards state that the access_token is required and is opaque data and that the id_token is optional and a JWT. PubSub+ event brokers permit both types of tokens and also allow the access_token to be a JWT.

JWTs can be cryptographically signed. Solace PubSub+ event brokers support four types of JWTs (this corresponds to the alg claim in the JWT header): none, RS256, RS384, RS512. If the alg claim is anything else, it is rejected as an invalid token.

The configuration tasks you can perform for token authentication include:

Ignoring Time Limits in Tokens

You can configure the event broker to ignore time limits in tokens. If enabled, tokens are accepted even if they are not valid yet, or are no longer valid. This does not configure the event broker to allow failed introspection results.

To configure the event broker to accept tokens regardless of configured time limits, enter the following command:

solace(...n/authentication/oauth/provider/token)# ignore-time-limits

Configuring Token Introspection

Token introspection is a process by which a token received from a client is sent to an OAuth authorization server to verify that the token is valid.

The configuration tasks you can perform for token introspection include:

Configuring the Token Parameter Name

The token parameter name is used to denote the start of the token during introspection. A standard compliant OAuth authorization server expects the token parameter name to be token. Other authorization servers may expect a different parameter. The Google authorization server, for example, expects access_token.

To configure the token parameter name, enter the following command:

solace(...on/oauth/provider/token/introspection)# parameter-name <parameter-name>

Where:

<parameter-name> is the name used to identify the token during introspection. The default is token.

Configuring OAuth Authorization Server Connection Parameters

If you configure the OAuth provider to use token introspection to validate tokens, you must provide appropriate connection parameters for the event broker to connect to the OAuth authorization server to complete the introspection attempt. Some authorization servers may not require a username and password, however the URI is always mandatory.

To configure the username to use when logging into the authorization server, enter the following command:

solace(...on/oauth/provider/token/introspection)# username <username>

To configure the password to use when logging into the authorization server, enter the following command:

solace(...on/oauth/provider/token/introspection)# password <password>

To configure the URI to use when logging into the authorization server, enter the following command:

solace(...on/oauth/provider/token/introspection)# uri <uri>

Where:

<uri> is the DNS name or IP address of the OAuth authorization server. Only HTTP and HTTPS are supported. If you specify an HTTPS address, certificates and certificate authorities must be configured on the event broker. See Managing Server Certificates.

To configure the timeout to use when logging into the authorization server, enter the following command:

solace(...on/oauth/provider/token/introspection)# timeout <timeout>

Where:

<timeout> is the number of seconds the event broker attempts an introspection before closing the connection.

Configuring the JWKS Public Key URI

When JWTs are signed, the event broker must be able to validate the signature, which requires access to the issuer's public keys. As part of the OpenID Connect protocol, these keys are published at a known URL. The event broker must retrieve these keys from that URL to validate token signatures.

To configure the JWKS public key URI, enter the following command:

solace(...pn/authentication/oauth/provider/jwks)# uri <uri>

Where:

<uri> is the DNS name or IP address where the OAuth authorization server publishes its public keys. Only HTTP and HTTPS are supported. If you specify an HTTPS address, certificates and certificate authorities must be configured on the event broker. See Managing Server Certificates.

Configuring the JWKS Refresh Interval

By default, PubSub+ event brokers refresh any JWKS public keys obtained from an OAuth authorization server once every hour.

Keys are also refreshed any time the following occurs:

  • The refresh interval is changed.
  • The refresh URI is changed.
  • OAuth authentication is enabled.
  • The VPN is enabled.
  • The broker is restarted.

When keys are refreshed, clients with stale keys are prevented access, however, clients that are currently connected to the event broker are unaffected.

If a provider changes its key and immediately starts issuing new tokens signed with the new key, there will be a period when the event broker rejects clients that try to connect with these newly signed keys. Avoiding this outage requires coordination with the provider. The refresh interval should fall within the time the provider publishes new keys and when it issues new tokens signed with the new keys.

To configure the JWKS refresh interval, enter the following command:

solace(...pn/authentication/oauth/provider/jwks)# refresh-interval <refresh-interval>

Where:

<refresh-interval> is the number of seconds between forced public key refreshes.

Configuring Username Validation

You can configure the event broker to validate the username provided by the client against the username extracted from the token. If they are different, the event broker rejects the connection attempt.

To enable username validation, enter the following command:

solace(...uthentication/oauth/provider/username)# validate

Configuring Username Determination

By default, PubSub+ event brokers use the sub field in OpenID Connect ID tokens to determine the client username. You can change these defaults to suit your deployment.

To configure the token field used to determine the client username, enter the following command:

solace(...uthentication/oauth/provider/username)# claim name <name>

Where:

<name> is the field in the token used to determine the client username. If no value is provided, sub is used as the default.

To configure the token source used to determine the client username, enter the following command:

solace(...uthentication/oauth/provider/username)# claim source {access-token | id-token | introspection}

Where:

access-token specifies to search for the username value in the JWT OAuthv2 access token.

id-token specifies to search for the username value in the OpenID Connect ID token. This is the default token source.

introspection specifies to use token introspection on the access token, regardless of whether it is a JWT or opaque data, to determine the username. If you want to use token introspection, you must also configure the token parameter the OAuth authorization server expects (see Configuring the Token Parameter Name), as well as the appropriate connection details for the server (see Configuring OAuth Authorization Server Connection Parameters).

Configuring Audience Validation

You can configure the event broker to validate the audience parameter provided by the client. If the audience value is incorrect, the event broker rejects the connection attempt.

To configure the audience value required for a token to be considered valid, enter the following command:

solace(...uthentication/oauth/provider/audience)# claim value <value>

To enable audience validation, enter the following command:

solace(...uthentication/oauth/provider/audience)# no shutdown

Configuring Audience Determination

By default, PubSub+ event brokers use the aud field in OpenID Connect ID tokens to determine the audience value. You can change these defaults to suit your deployment.

To configure the token field used to determine the audience, enter the following command:

solace(...uthentication/oauth/provider/audience)# claim name <name>

Where:

<name> is the field in the token used to determine the audience. If no value is provided, aud is used as the default.

To configure the token source used to determine the audience, enter the following command:

solace(...uthentication/oauth/provider/audience)# claim source {access-token | id-token | introspection}

Where:

access-token specifies to search for the audience value in the JWT OAuthv2 access token.

id-token specifies to search for the audience value in the OpenID Connect ID token. This is the default token source.

introspection specifies to use token introspection on the access token, regardless of whether it is a JWT or opaque data, to determine the audience value. If you want to use token introspection, you must also configure the token parameter the OAuth authorization server expects (see Configuring the Token Parameter Name), as well as the appropriate connection details for the server (see Configuring OAuth Authorization Server Connection Parameters).

Displaying OAuth Provider Information

To display information about an OAuth provider, enter the following command:

show message-vpn <vpn name> oauth provider <provider name> [detail [stats]]

Where:

<vpn name> is the name of the Message VPN where the provider is configured.

<provider name> is the name of the OAuth provider you want to monitor.

detail displays detailed information about the OAuth provider.

stats displays statistics about the OAuth provider, including connection attempt, token introspection, and JWKS refresh results.

Note  

The following list includes additional information you can use to interpret some of the output fields displayed by the stats keyword:

  • Missing Authorization Group Claim—This does not mean the login failed. The login will only fail if there is no configured client username.
  • Success—Success in this case does not mean that the client successfully logged in, it means the introspection part of the login path did not fail.
  • Errors—This value shows the number of times the introspection server replied saying the token was not valid.
  • Transport Failures—This value shows the number of times a failure occurred at the transport layer when the event broker attempted to communicate with the introspection server.
  • HTTPS Failures—This value shows the number of times a failure occurred at the HTTPS layer when the event broker attempted to communicate with the introspection server. This usually means there's something wrong with the server certificate, or the event broker is not configured to trust the introspection server's certificate.
  • Invalid—This value shows the number of times the introspection server replied with content that could not be parsed.
  • Timeouts—This value shows the number of times the DNS name resolution or introspection server timed out.
  • Introspection Time—This value shows the one minute average (an average over the past 1-minute) of the time required to complete a token introspection, in milliseconds (ms).

Enabling OAuth Client Authentication

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

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication
solace(configure/message-vpn/authentication)# oauth
solace(...gure/message-vpn/authentication/oauth)# no shutdown

To disable OAuth authentication for clients connecting to the given Message VPN, enter the following command:

solace(...gure/message-vpn/authentication/oauth)# shutdown

OAuth Authentication Example Configuration

The following example shows how to create and set up an OAuth provider on a new Message VPN which is used for OAuth authentication.

In this example:

  • The OAuth authorization server introspection URI is located at 192.168.1.23: 23432 and requires credentials of oauthServerUsername/oauthServerPassword through HTTPS.
  • It is assumed that ID tokens used to log into the event broker contain the following:
    • A non-default userNameClaim claim instead of sub. This means the event broker will search for the client username in the userNameClaim field of the token instead of the sub field.
    • A non-default audience claim instead of aud. This means the event broker will search for the audience value in the audience field of the token instead of the aud field.
  • Audience validation is enabled and audienceValue is the audience value required for an ID token to be considered valid.
  • The JWKS refresh URI is located at http://192.168.1.24:34543.
  • JWKS public keys stored on the event broker are refreshed every 24 hours.
solace(configure)# create message-vpn oauthExample
solace(configure/message-vpn)# authentication oauth
solace(...gure/message-vpn/authentication/oauth)# no shutdown
solace(...gure/message-vpn/authentication/oauth)# default-provider myOauthProvider
solace(...gure/message-vpn/authentication/oauth)# create provider myOauthProvider
solace(...age-vpn/authentication/oauth/provider)# no shutdown
solace(...age-vpn/authentication/oauth/provider)# token introspection
solace(...on/oauth/provider/token/introspection)# username oauthServerUsername
solace(...on/oauth/provider/token/introspection)# password oauthServerPassword
solace(...on/oauth/provider/token/introspection)# uri https://192.168.1.23:23432
solace(...on/oauth/provider/token/introspection)# exit
solace(...n/authentication/oauth/provider/token)# exit
solace(...age-vpn/authentication/oauth/provider)# audience
solace(...uthentication/oauth/provider/audience)# no shutdown
solace(...uthentication/oauth/provider/audience)# claim value audienceValue
solace(...uthentication/oauth/provider/audience)# claim name audience
solace(...uthentication/oauth/provider/audience)# exit
solace(...age-vpn/authentication/oauth/provider)# jwks
solace(...pn/authentication/oauth/provider/jwks)# refresh-interval 86400
solace(...pn/authentication/oauth/provider/jwks)# uri http://192.168.1.24:34543

Duplicate Client Connect Behavior Configuration

When a new client connects to an event broker, and that client uses the same client name as an existing connected client, you can configure the event 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 event 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 event broker takes to expire the old Web client session before accepting the replacement.