Configuring Client Authentication

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

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

Also referred to as mutual TLS (mTLS) authentication. 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

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

  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

Basic authentication is the default client authentication scheme used by PubSub+ event brokers. 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
• Configuring Authentication Types
• Enabling/Disabling Basic Authentication for Clients

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.

  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

To implement client certificate or mutual TLS (mTLS) authentication for connecting clients, the following configurations are required on the Solace PubSub+ event broker:

• Client certificate authentication must be configured and enabled for any Message VPNs that the clients will connect to. See Configuring Client Certificate Parameters for Message VPNs.
• TLS/SSL service must be configured and enabled. See TLS/SSL Encryption Configuration for Publishing / Receiving Messages.

To configure your event broker to enable client certificate revocation checking, see Configuring Certificate Authorities.

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.

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
• Configuring Max Certificate Chain Depths
• Configuring Validate Certificate Dates
• Configuring Client Username Sources
• Configuring Client Certificate to Message VPN Matching
• Enabling/Disabling Client Certificate Authentication For Clients

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

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

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

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 first CN from the Subject Name field of the certificate and uses it as the client username. Alternatively, you can configure a Message VPN to use one of the following as a source for the client username:

• The msUPN from the subject alternative name (SAN) extension in the certificate.
• The user identifier (UID) attribute in the Subject Name field of the certificate.
• The SHA-1 thumbprint of the certificate.

If you configure the CN, SAN, or UID as the username source:

• All of the current client username character restrictions apply. For example, if the SAN or UID 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 or UID.
• If the allow-api-provided-username option is not enabled, when a client attempts to connect to the Message VPN and no SAN or UID 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 {certificate-thumbprint | common-name | common-name-last | subject-alternative-name-msupn | uid | uid-last}

Where:

certificate-thumbprint specifies to use the certificate thumbprint as the client username when clients authenticate against the given Message VPN. The certificate thumbprint is a SHA-1 hash of the entire DER-encoded certificate calculated by the broker after it receives the client certificate.

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

common-name-last specifies to use the last instance of the CN in the client certificate as the client username when clients authenticate against the given Message VPN.

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.

uid specifies to use the first instance of the user identifier (UID) attribute in the client certificate as the client username when clients authenticate against the given Message VPN.

uid-last specifies to use the last instance of the UID attribute in 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.

Configuring Client Certificate to Message VPN Matching

By default when a client attempts to login to a Message VPN using a client certificate, the username for the client is extracted from the certificate (CN, UID, msUPN or certificate thumbprint) which can be used for subsequent client authorization.

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.

Some use cases for client certificate to Message VPN matching include:

• Segregating Message VPNs by Certificate Authorities

• Validating the Organization Unit Subject Attribute

• Linking a Client Username to a Particular Certificate

When you configure client certificate matching, you create a set of matching rules per Message VPN. For a client certificate to be accepted as a valid credential, the certificate must match at least one rule. Each rule contains a set of one or more conditions, all of which must be satisfied for a certificate to match the rule. Each condition compares a certificate field with an attribute associated with the client username (extracted from the certificate based on the username source) or a fixed glob expression. The attributes are store in the internal user database if you are using internal authorization or looked up in an external LDAP database if you are using LDAP authorization. If you use an expression, it is compared directly to the certificate field (and may contain wildcards).

You can also create attribute filters to ensure that the matching rule applies only to client usernames with certain attribute values. For example, if you want to allow legacy users to log in without other requirements, you could mark existing client usernames as legacy (by creating username attributes) and then create a rule that contains an attribute filter which checks that the value of the legacy attribute is set to true without any conditions. Once configured, you could then add custom conditions to the rule for new users.

To create a certificate matching rule, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# authentication
solace(...message-vpn/authentication)# client-certificate
solace(...ication/client-certificate)# matching-rules
solace(...certificate/matching-rules)# create rule <name>

To create a certificate matching rule condition, enter the following CONFIG commands:

solace(...certificate/matching-rules/rule)# create condition {certificate-thumbprint | common-name | common-name-last | subject-alternate-name-msupn | uid | uid-last | org-unit | org-unit-last | issuer | subject | serial-number | dns-name | ip-address} {{matches-attribute <attribute>} | {matches-expression <expression>}}

To create a certificate matching rule attribute filter, enter the following CONFIG commands:

solace(...certificate/matching-rules/rule)# create attribute-filter <name> 
solace(...certificate/matching-rules/rule/attribute-filter)# attribute <value>
solace(...certificate/matching-rules/rule/attribute-filter)# value <value>    

Modifying client certificate matching rules does not have any effect on existing connections. Only new connections are affected.

To enable a certificate matching rule, enter the following CONFIG commands:

solace(...certificate/matching-rules/rule)# no shutdown

By default, client certificate matching is disabled and any otherwise valid certificate is accepted. To enable client certificate matching, enter the following CONFIG commands:

solace(...certificate/matching-rules)# no shutdown

Where:

rule <name> specifies the name of the certificate matching rule.

certificate-thumbprint compares the certificate thumbprint with the specified attribute or glob expression. The certificate thumbprint is a SHA-1 hash of the entire DER-encoded certificate calculated by the broker after it receives the client certificate.

common-name compares the first instance of the CN in the client certificate with the specified attribute or glob expression.

common-name-last compares the last instance of the CN in the client certificate with the specified attribute or glob expression.

subject-alternative-name-msupn compares the msUPN (in the otherName field) in the SAN extension of the client certificate with the specified attribute or glob experssion.

uid compares the first instance of the user identifier (UID) attribute in the client certificate with the specified attribute or glob expression.

uid-last compares the last instance of the UID attribute in the client certificate with the specified attribute or glob expression.

org-unit compares the first instance of the Org Unit attribute in the client certificate with the specified attribute or glob expression.

org-unit-last compares the last instance of the Org Unit attribute in the client certificate with the specified attribute or glob expression.

issuer compares the Issuer attribute in the client certificate with the specified attribute or glob expression.

subject compares the Subject attribute in the client certificate with the specified attribute or glob expression.

serial-number compares the client certificate serial number with the specified attribute or glob expression.

dns-name compares the DNS name in the SAN extension of the client certificate with the specified attribute or glob expression.

ip-address compares IP address in the SAN extension of the client certificate with the specified attribute or glob expression.

matches-attribute <attribute> specifies the attribute used in the comparison.

matches-expression <expression> specifies the glob expression used in the comparison. The expression is compared directly to the field extracted from the certificate and may contain wildcards.

attribute-filter <name> specifies the name of the attribute filter.

attribute <value> specifies the name of the attribute to be tested.

value <value> specifies the expected value of the attribute in order to apply the certificate matching rule.

Username attributes are stored in the internal user database when using internal authorization or converted to an LDAP search filter when using LDAP authorization. Attributes must match exactly and wild card characters are treated as literals.

Examples:

Segregating Message VPNs by Certificate Authorities

The list of CAs is currently a global event broker setting. Because a particular subject CN might not be unique across all CAs, limiting a Message VPN to a certain CA can help ensure only the appropriate CA is trusted and the subject CN is unique.

You can achieve this by creating a matching rule with one condition that compares the certificate issuer to a glob expression.

solace(configure/message-vpn/authentication/client-certificate/matching-rules)# create rule issuer
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# create condition issuer matches-expression "C = CA, ST = Ontario, L = Kanata, O = Solace Systems, OU = IT, CN = *.messaging.solace"
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# no shutdown
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# exit
solace(configure/message-vpn/authentication/client-certificate/matching-rules)# no shutdown

In this example, a rule called issuer is created. The event broker will attempt to match a client certificate to this rule by comparing the issuer of the certificate to the expression C = CA, ST = Ontario, L = Kanata, O = Solace Systems, OU = IT, CN = *.messaging.solace (this rule contains a single condition). If the issuer of the certificate matches the expression, then the rule is considered a match.

Validating the Organization Unit Subject Attribute

Some organizations require administrators to sign off on any certificate with their respective OU field in the certificate subject.

You can achieve this by creating a matching rule with one condition that compares the certificate subject OU with an ou client username attribute.

solace(configure/message-vpn/authentication/client-certificate/matching-rules)# create rule org-unit
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# create condition org-unit matches-attribute ou
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# no shutdown
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# exit
solace(configure/message-vpn/authentication/client-certificate/matching-rules)# no shutdown

This requires that you also create the appropriate attribute on the client username, for more information, see Setting Client Username Attributes.

solace(configure)# client-username App1 message-vpn vpn1
solace(configure/client-username)# create attribute ou Unit1

Once configured, a matching certificate can have a subject like this: CN=App1, OU=Unit1, O=Org, C=US.

In this example, a rule called org-unit is created. The event broker will attempt to match a client certificate to this rule by comparing the organizational unit (OU) of the certificate to an attribute configured against the username. The username extracted from the certificate (App1) has an attribute called ou configured with a value of Unit1. To satisfy the condition (and match the rule since there is only one condition), the OU extracted from the certificate must match exactly the value of the ou attribute looked up against the username.

Linking a Client Username to a Particular Certificate

One of the most secure options is only allowing a particular certificate (or two to facilitate certificate rotation) to be used to authenticate a given user.

You can achieve this by creating a matching rule with one condition that compares the certificate thumbprint with a certificateThumbprint client username attribute.

solace(configure/message-vpn/authentication/client-certificate/matching-rules)# create rule thumbprint
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# create condition certificate-thumbprint matches-attribute certificateThumbprint
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# no shutdown
solace(configure/message-vpn/authentication/client-certificate/matching-rules/rule)# exit
solace(configure/message-vpn/authentication/client-certificate/matching-rules)# no shutdown

This requires that you also create the appropriate attributes on the client username, for more information, see Setting Client Username Attributes.

solace(configure/client-username)# create attribute certificateThumbprint ea:13:85:ca:a9:d0:91:a6:e4:b3:4b:80:4c:08:bb:cb:34:88:8b:dc
solace(configure/client-username)# create attribute certificateThumbprint 06:d7:82:da:12:6a:11:8b:e7:29:84:8d:60:4c:40:27:a4:54:44:3c

In this example, a rule called thumbprint is created. The event broker will attempt to match a client certificate to this rule by comparing the thumbprint calculated from the certificate to attribute(s) configured against the username. In this case, the client username has two certificateThumbprint attributes configured against it to facilitate certificate rotation. To satisfy the condition, the thumbprint calculated from the certificate must match exactly the value of one of the certificateThumbprint attributes against the username.

Alternatively, you can create a rule with two conditions, one for checking the certificate issuer is correct (see Segregating Message VPNs by Certificate Authorities), and another for comparing the certificate serial number with a certificateSerialNumber client username attribute. This pair of values uniquely identifies a certificate.

Because client username attributes can have multiple values, this allows for smooth transition when a certificate is reissued. You can add a new thumbprint or serial number and remove an old one after that, so the client will be able to reconnect at any time using an old or new certificate.

Enabling/Disabling 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

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/Disabling 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 the Management Interface and Message Backbone Interface.

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.

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

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.

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.

Managing Kerberos Realms

A Kerberos realm is a domain, or group of systems over which Kerberos has the authority to authenticate a client to a service. Within a realm are user principals (clients), service principals (resources provided to a client) and a KDC, which supplies tickets and grants temporary sessions keys that allow a client to authenticate to a service.

When you create a Kerberos realm object on an event broker, you provide the means to configure realm to KDC address mapping. This mapping is required before you can enable Kafka receivers and senders to authenticate to remote Kafka brokers using Kerberos (refer to Configuring Authentication Schemes for Kafka Receivers or Configuring Authentication Schemes for Kafka Senders).

To create a Kerberos realm, enter the following CONFIG command:

solace(...e/message-vpn/authentication/kerberos)# create realm <name>

To edit the properties of an existing realm, enter the following CONFIG command:

solace(...e/message-vpn/authentication/kerberos)# realm <name>

Where:

<name> is the Kerberos realm name. This name must start with @ and is typically written using all uppercase letters.

The no version of this command, no realm, deletes the realm.

You can perform the following tasks for a configured Kerberos realm:

• Configuring the Key Distribution Center Address

• Enabling/Disabling a Kerberos Realm

• Displaying Kerberos Realm Information

Configuring the Key Distribution Center Address

To configure the IP address or hostname of the KDC for principals in this realm, enter the following CONFIG command:

solace(...e/message-vpn/authentication/kerberos)# realm <name>
solace(...age-vpn/authentication/kerberos/realm)# kdc-address <value>

Where:

<value> is the IP address or FQDN and optional port of the KDC.

The no version of this command, no kdc-address, removes the configuration.

Enabling/Disabling a Kerberos Realm

To enable a Kerberos realm, enter the following CONFIG command:

solace(...e/message-vpn/authentication/kerberos)# realm <name>
solace(...age-vpn/authentication/kerberos/realm)# no shutdown

The disable a realm, enter the following CONFIG command.

solace(...age-vpn/authentication/kerberos/realm)# shutdown

Displaying Kerberos Realm Information

To display information about a Kerberos realm, enter the following User EXEC command:

show message-vpn <vpn-name> kerberos realm <realm>

Where:

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

<realm> is the name of the Kerberos realm.

Enabling/Disabling 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

To implement OAuth authentication for clients connecting to a PubSub+ event broker at the Message VPN level, the following configurations are required:

• PubSub+ 9.12.1 or greater must be used. Although OAuth authentication for MQTT clients was introduced in version 9.2, the existing OAuth provider configuration is deprecated (see Compatibility with Older Versions). If your deployment uses OAuth providers to authenticate MQTT clients you must manually migrate to the new Message VPN scoped OAuth profiles. Contact Solace for assistance.
• The event broker must be configured to use TLS by setting a server certificate. For more information, see Managing Server Certificates.
• An OAuth profile must be created on the event broker with the following additional configuration (see Managing Message VPN OAuth Profiles):
  • client-id: Client ID configured on the event broker must match with the OAuth Client ID.
  • client-secret: Client secret configured on the event broker must match with the OAuth Client Secret.
  • endpoints: It is a best practice to either: configure the discovery endpoint and leave the other endpoints unset; or leave the discovery endpoint unset and configure the other endpoints.
• OAuth authentication must be enabled for any Message VPNs that OAuth-authenticated clients will connect to. See Enabling OAuth Client Authentication.

You will need to perform additional configurations depending on what token you want to get your claims from (id-token or access-token), and claims you expect to receive from the token. The additional configuration will depend on your specific setup. Detailed configuration information is provided below.

Differences between Message VPN OAuth Profiles and Global OAuth Profiles

• Global profiles have SEMPv2 access level configuration, Message VPN OAuth profiles have username-claim-name and authorization-groups-claim-name for client ACLs.
• With SEMPv2 the OAuth token is provided with each request; client connections are authenticated when they are established but not with each message. The disconnect-on-token-expiration setting is provided to allow control over whether disconnection happens when the token expires.
• The settings related to interactive OAuth in global profiles are not present in Message VPN profiles.
• OAuth for MQTT has the username validate setting. The username is always determined from OAuth, but this setting, when enabled, fails authentication if the name discovered via OAuth doesn't match the username specified during connection establishment. This setting is brought forward to Message VPN OAuth profiles in the form of the mqtt-username-validate configuration option (see MQTT Username Validation).

Managing Message VPN OAuth Profiles

To implement OAuth authentication for clients connecting to a PubSub+ event broker at the Message VPN level, you must first create a Message VPN OAuth profile. The number of Message VPN OAuth profiles you can create is limited by the number of Message VPNs on the event broker, or 500, whichever is lower.

To create a profile, enter the following commands:

solace(...gure/message-vpn/authentication/oauth)# create profile <profile>
solace(...sage-vpn/authentication/oauth/profile)# 

To configure an existing profile, enter the following command:

solace(...gure/message-vpn/authentication/oauth)# profile <profile>

To enable the profile, enter the following command:

solace(...sage-vpn/authentication/oauth/profile)# no shutdown

To specify a default profile, enter the following command:

solace(...gure/message-vpn/authentication/oauth)# default-profile <profile>

Where:

<profile> is the name of the Message VPN OAuth profile.

The settings you can configure for the profile include:

• OAuth Role
• Endpoints
• Client
• Resource Server
• Client ID
• Client Secret
• Issuer Identifier
• Disconnect on Token Expiration
• Authorization Groups Claim
• Username Claim Name
• Forward Proxy

OAuth Role

You can configure the event broker to act as an OAuth client or resource server. If you configure the client role for a profile, this means the profile is using OpenID Connect, and once enabled, the event broker expects to receive ID tokens when clients attempt to authenticate. If you configure the resource server role for a profile, this means the profile is using OAuth2, and if enabled, the broker expects to receive access-tokens when clients authenticate.

By default, the event broker role is set to client. If oauth-role is set to resource-server and client scope does not contain openid scope, the oauth-role cannot be changed to client. The change will be rejected and oauth-role will remain as resource-server. The client scope configuration must contain the openid scope before switching from resource-server to client role. If oauth-role is client, the introspection endpoint is not used and need not be configured, and similarly, the userinfo endpoint will not be used if oauth-role is resource-server.

To set the event broker as an OAuth client or resource server, enter the following command:

solace(...sage-vpn/authentication/oauth/profile)# oauth-role [client | resource-server]

The no version of the command, no oauth-role, sets the event broker role to the default client role.

Endpoints

OAuth endpoints are the URLs that you use to make authentication requests. All endpoints must be TLS. Any endpoint that does not start with https:// (case insensitive) will be rejected at configuration. Endpoints that are determined through discovery will be rejected at runtime if they are not TLS.

To configure OAuth endpoints, enter the following command:

solace(...sage-vpn/authentication/oauth/profile)# endpoints

From this level, you can configure the following endpoint settings:

solace(...uthentication/oauth/profile/endpoints)# [discovery | discovery-refresh-interval | introspection | introspection-timeout | jwks | jwks-refresh-interval  | userinfo | userinfo-timeout]

Discovery Endpoint

The discovery endpoint is the OpenID Connect Discovery endpoint or the OAuth 2.0 Authorization Server Metadata endpoint. Generally, this is the only endpoint that you will need to configure, as this endpoint provides information about the OAuth issuer and all the other endpoints. It is a best practice to either: configure the discovery endpoint and leave the other endpoints unset; or leave the discovery endpoint unset and configure the other endpoints.

To configure a discovery endpoint, enter the following command:

solace(...uthentication/oauth/profile/endpoints)# discovery <value>

Where:

<value> is the discovery URL.

The no version of the command, no discovery <value>, returns the endpoint value to none.

Discovery Refresh Interval

The discovery refresh interval is used to configure the number of seconds between discovery endpoint requests.

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

solace(...uthentication/oauth/profile/endpoints)# discovery-refresh-interval <value>

Where:

<value> is number of seconds between discovery endpoint requests.

The no version of the command, discovery-refresh-interval, returns its value to the default of 86400 seconds (1 day).

Introspection Endpoint

The token introspection endpoint returns claims associated with the user identified by the access token.

To configure an introspection endpoint, enter the following command:

solace(...uthentication/oauth/profile/endpoints)# introspection <value>

Where:

<value> is the URI of the OAuth introspection endpoint. Only HTTPS is supported. If you specify an HTTPS address, certificates and certificate authorities must be configured on the event broker. See Managing Server Certificates.

The no version of the command, no introspection, returns the endpoint value to none.

Introspection Timeout

The configure introspection timeout is the maximum time in seconds a token introspection request is allowed to occur.

To configure the introspection timeout, enter the following command:

solace(...uthentication/oauth/profile/endpoints)# introspection-timeout <value>

Where:

<value> is the value to set in seconds.

The no version of the command, no introspection-timeout, returns its value to 1 second.

JWKS Endpoint

To verify the ID and access tokens, the event broker needs access to the public keys. These keys are available from the OAuth identity provider's JSON Web Key Set (JWKS) endpoint. This endpoint can be explicitly configured or determined from the discovery document. Thejwks endpoint returns the keys that was used to verify JSON Web Tokens (JWTs) from the OAuth identity provider. The event broker retrieves these keys from that URL to validate token signatures and caches

To configure a JWKS endpoint, enter the following command:

solace(...uthentication/oauth/profile/endpoints)# jwks <value>

Where:

<value> is the URI of the jwks endpoint. Only HTTPS is supported. If you specify an HTTPS address, certificates and certificate authorities must be configured on the event broker. See Managing Server Certificates.

The no version of the command, no jwks, returns the endpoint value to none.

JWKS Refresh Interval

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

Keys are also refreshed any time the following occurs:

• The refresh interval is changed.
• The JWKS endpoint is changed.
• The issuer is changed.
• The OAuth profile is enabled.
• The Message VPN is enabled, or OAuth authentication is enabled for the Message VPN.
• The broker is restarted.

Once every jwks-refresh-interval, the event broker will refresh the set of keys. If the event broker attempts to refresh the key and the request fails, the following retries are performed:

• retry every 60s indefinitely if valid data is missing
• retry three times every 60s if valid data exists. The event broker will then stop and wait for the next scheduled refresh or data expiry

In addition, JWKS keys expire when they are older than three times the jwks-refresh-interval.

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

solace(...uthentication/oauth/profile/endpoints)# jwks-refresh-interval <value>

Where:

<value> is the number of seconds between forced public key refreshes.

The no version of the command, no jwks-refresh-interval, returns its value to the default of 86400 seconds (1 day).

Userinfo Endpoint

The UserInfo endpoint is part of the OpenID Connect standard (OIDC), designed to return claims about the authentication user. The endpoints is used in situations where ID token may not contain all the required claims, in which case the access token is used to retrieve the userinfo.

To configure a userinfo endpoint, enter the following command:

solace(...uthentication/oauth/profile/endpoints)# userinfo <value>

Where:

<value> is the URL of the userinfo endpoint.

The no version of the command, no userinfo, returns the endpoint value to none.

Userinfo Timeout Endpoint

Using the userinfo timeout endpoint, you can set the maximum time a userinfo request is allowed to take.

To configure a userinfotimeout endpoint, enter the following command:

solace(...uthentication/oauth/profile/endpoints)# userinfo-timeout <value>

Where:

<value> is the number of seconds is the number of seconds that a userinfo request is allowed to take.

The no version of the command, no userinfo-timeout, returns its value to the default value of 1 second.

Client

A client is the application that wants to access the resource server data. It is the application that requests the access token or ID token from the authorization server and then passes it to the token server to get access to the data.

To configure OAuth client settings on the event broker, enter the following command:

solace(...sage-vpn/authentication/oauth/profile)# client
solace(...n/authentication/oauth/profile/client)# 

From this level, you can configure the following settings:

solace(...n/authentication/oauth/profile/client)# [required-claim ... | required-type ... |  validate-type]

Required Claim

You can configure required claims in the event broker to verify the ID token. All claims specified under required-claim must match exactly. The required-claim values are specified as JSON, and may be strings, numbers, or arbitrary JSON objects. A maximum of four required claims can be configured per OAuth profile.

To create a required claim, enter the following command:

solace(...n/authentication/oauth/profile/client)# create required-claim <name> <value>

Where:

<name> is name of the ID token claim to verify. The claim names must be unique and are case-sensitive.

<value> is the required claim value, which must be a string containing a valid JSON value.

The no version of the command, no required-claim <value>, deletes the configured claim.

Required Type

The content type required for the ID token header. The default value is JWT.

To configure required type value, enter the following command:

solace(...n/authentication/oauth/profile/client)# required-type <value>

Where:

<value> is the value to set for the required-type.

The no version of the command, no required-type <value>, returns its value to JWT.

Validate Type

The validate-type parameter verifies the token ID type. By default, it is set to true. If validate-type is true, tokens that don't have the typ header field will fail to validate. Generally, most OAuth identity providers set typ to JWT. Also, if validate-type is enabled (default), the typ field in the JWT header must match the value configured in required-type.

To configure the validate type parameter, enter the following command:

solace(...n/authentication/oauth/profile/client)# validate-type

The no version of the command, no validate, changes the default value (true) to false.

Resource Server

In the OAuth flow, the resource server accepts the access token and verifies that it's valid. The configurations under resource-server only has effect if oauth-role is resource-server.

To configure OAuth resource server settings, enter the following command:

solace(configure/authentication/oauth-profile)# resource-server
solace(...e/authentication/oauth-profile/resource-server)# 

From this level, you can configure the following settings:

solace(...e/authentication/oauth-profile/resource-server)# [parse-access-token | required-audience | required-claim | required-issuer | required-scope | required-type | validate-audience | validate-issuer | validate-scope | validate-type]

Parse Access Token

You can enable or disable parsing of the access token as a JWT. It is enabled by default. When parse-access-token is enabled, the access token is examined to determine whether it contains the claims specified for the username and groups. If it contains both claims, no further processing is required, and values of the appropriate claims are used. However, if an introspection endpoint is provided (either directly or via discovery), every access token is checked even if the token contains the username and groups. If parse-access-token is disabled, the introspection-endpoint must be specified.

To disable the default parse-access-token, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# no parse-access-token

Required Type

The content type required for the access token header. The default value is at+jwt.

To configure required type value, enter the following command:

solace(configure/authentication/oauth-profile/client)# required-type <value>

Where:

<value> is the value to set for the required-type.

The no version of the command, no required-type <value>, returns its value to at+jwt.

Required Audience

You can configure the event broker to validate the required audience parameter provided by the client. The required-audience value must match the aud claim if the aud claim is a string and if it is an array of strings, it must match one of the values of the aud claims. If the required-audience value is incorrect, the event broker rejects the connection attempt.

To configure OAuth required audience value, enter the following command:

solace(...e/authentication/oauth-profile/resource-server)# required-audience <value>

The no version of the command, no required-audience <value>, returns the value to none.

Required Claim

You can configure required claims in the event broker to verify the access token or introspection response. All claims specified under required-claim must match exactly. The required-claim values are specified as JSON, and may be strings, numbers, or arbitrary JSON objects. A maximum of 8 required claims can be configured per OAuth profile.

To create a required claim, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# create required-claim <name> <value>

Where:

<name> is name of the id-token claim to verify. The claim names must be unique and are case-sensitive.

<value> is the required claim value, which must be a string containing a valid JSON value.

The no version of the command, no required-claim <value>, deletes the configured claim.

Required Issuer

You can configure the required issuer claim value in the event broker as part verifying the access token or introspection response. The configured required-issuer value must match the iss claim. If the required-issuer is not specified, the issuer from the discovery endpoint is used to verify the iss claim.

To configure a required issuer claim, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# required-issuer <value>

Where:

<value> is the value to configure for the required issuer claim.

The no version of the command, no required-claim <value>, returns the value to none.

Required Scope

The required scopes are space-separated list of scopes that must be present in the scope claim The scope claim must contain all of the values in required-scope, but may contain other scopes, and the scopes may be in a different order. If the required-scope is empty or not set, no scope verification is performed.

To configure the required scope on the event broker, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# required-scope <value>

Where:

<value> is the value to configure for the required issuer claim.

The no version of the command, no required-scope <value>, returns the value to none.

Validate Audience

You can configure the event broker to validate the audience parameter to verify the aud claim in the access token or introspection response. By default this feature is enabled. If validate-audience is disabled, required-audience validation is not performed. If it is enabled, the validation described at required-audience will be performed.

To configure the event broker to validate the audience claim, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# validate-audience

The no version of the command, no validate-audience, disables it.

Validate Issuer

You can configure the event broker to validate issuer parameter to verify the iss claim in the access token or introspection response. By default this feature is enabled. If validate-issuer is disabled, required-issuer validation is not performed. If it is enabled, the validation described at required-issuer will be performed.

To configure the event broker to validate the issuer claim, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# validate-issuer

The no version of the command, no validate-issuer, disables it.

Validate Scope

You can configure the event broker to validate the scope parameter to verify the scope claims in the access token or introspection response. By default this feature is enabled. If validate-scope is disabled, required-scope validation is not performed. If it is enabled, the validation described at required-scope will be performed.

To configure the event broker to validate scope claims, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# validate-scope

The no version of the command, no validate-scope, disables it.

Validate Type

You can configure the event broker to validate the scope parameter to verify the typ field in the access token header. By default this feature is enabled. If validate-type is disabled, required-type validation is not performed. If it is enabled, the validation described at required-type will be performed.

To configure the event broker to validate the typ field, enter the following command:

solace(configure/authentication/oauth-profile/resource-server)# validate-type

The no version of the command, no validate-type, disables it.

Client ID

When a client registers with an OAuth identity provider they receive a client ID along with a client secret. These are essentially equivalent to username and password, which the authorization server uses to authenticate the application. The client-id identifies the client responsible for the OAuth request.

If you set the OAuth role on event broker to client, the client-id is checked against the aud claim in received ID tokens. If you set the OAuth role to resource server, this verification depends on the validate-audience setting. If validate-audience is enabled, the client-id is checked against the claim indicated in the required-audience configuration. In either case if the value is incorrect, the event broker rejects the connection attempt.

To configure a client ID on your event broker, enter the following command:

solace(configure/authentication/oauth-profile)# client-id <value>

<value> is the OAuth provided Client ID.

The no version of the command, no client-id, returns the value to none.

Client Secret

When a client registers with an OAuth identity provider they receive a client ID and client secret. These are essentially equivalent to username and password, which the authorization server uses to authenticate the application. Client secrets are only necessary if you are using an introspection endpoint (see Introspection Endpoint).

To configure a client secret on your event broker, enter the following command:

solace(configure/authentication/oauth-profile)# client-secret <value>

<value> is the OAuth provided Client Secret.

The no version of the command, no client-secret, returns the value to none.

MQTT Username Validation

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

To enable MQTT username validation, enter the following command:

solace(configure/authentication/oauth-profile)# mqtt-username-validate

The no version of the command, no mqtt-username-validate, disables MQTT username validation.

Issuer Identifier

To configure the issuer identifier for the authorization server, enter the following command:

solace(configure/authentication/oauth-profile)# issuer <value>

Where:

<value> is the authorization server's issuer identifier URL.

The no version of the command, no issuer <value>, returns its value to none.

Disconnect on Token Expiration

By default, PubSub+ event brokers disconnect clients when their tokens expire. You can change this default to suit your deployment. Changing this value does not affect existing clients, only new client connections.

To configure the event broker to disconnect clients when their tokens expire, enter the following command:

solace(configure/authentication/oauth-profile)# disconnect-on-token-expiration

The no version of the command, no disconnect-on-token-expiration, stops the event broker from disconnecting clients when their tokens expire.

Authorization Groups Claim

By default, PubSub+ event brokers use the groups field in OAuth tokens to determine the client authorization group. You can change this default to suit your deployment. For more information about authorization groups, see Configuring Authorization Groups.

To configure the authorization groups claim name, enter the following command:

solace(configure/authentication/oauth-profile)# authorization-groups-claim-name <value>

Where:

<value> is the field in the token used to determine the client authorization group. If no value is provided, groups is used as the default. When using JWTs, claim names must be at the top level of the JWT. In other words, they cannot be embedded. In addition, the value of any claim that you want to use as a client authorization group must be a string or an array of strings.

In this example the "authGroupClaim" field is used to determine the authorization group, and its value is the string "abcdefghi":

{
...
   "authGroupClaim": "abcdefghi",
...
}

In this example the "authGroup" field is used to determine the authorization group, and its value is the string array ["a b c", "def", "ghi"]. The event broker interprets this array as three authorization groups, "a b c" (including the spaces), "def", and "ghi". In this case, the client will be assigned to the highest priority authorization group which matches one of the supplied names.

{
...
   "authGroup": ["a b c", "def", "ghi"],
...
}

The no version of the command, no authorization-groups-claim-name <value>, returns its value to the default groups.

For compatibility, you can configure the event broker to interpret a string value for the claim as a space-delimited set of groups, similar to the scope claim. For example, a claim value of "a b c" would be interpreted as three groups: "a", "b", and "c".

To configure this behaviour, enter the following command:

solace(configure/authentication/oauth-profile)# authorization-groups-claim-string-format space-delimited

The no version of the command, no authorization-groups-claim-string-format, returns its value to the default single.

Username Claim Name

By default, PubSub+ event brokers use the sub field in OAuth tokens to determine the client username. You can configure a custom username-claim-name, which must be a string; for example, email. Claims of other types such as number, boolean, object, array, etc., are not supported.

To configure the username claim name, enter the following command:

solace(configure/authentication/oauth-profile)# username-claim-name <value>

Where:

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

The no version of the command, no username-claim-name <value>, returns its value to the default sub.

Forward Proxy

Depending on your deployment, you may require that communication between the event broker and authorization servers goes through a forward proxy. This is often the case if your event broker sits behind a firewall and egress traffic needs to connect to a proxy server to go outside the firewall.

To configure a forward proxy for a Message VPN OAuth profile, enter the following command:

solace(...sage-vpn/authentication/oauth/profile)# proxy <proxy-name>

Where:

<proxy-name> is the name of the forward proxy configured on the event broker to use for discovery, user info, and introspection requests. For more information, see Configuring a Forward Proxy.

The no version of this command, no proxy, removes any configured forward proxy.

Enabling Message VPN OAuth Profiles

To enable a Message VPN OAuth profile, 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)# profile <profile>
solace(...sage-vpn/authentication/oauth/profile)# no shutdown

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

solace(...sage-vpn/authentication/oauth/profile)# shutdown

Displaying Message VPN OAuth Profile Information

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

show message-vpn <vpn-name> oauth profile <profile> [client required-claim <required-claim-name-pattern> | resource-server required-claim <required-claim-name-pattern>] | [detail [stats]]

Where:

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

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

client required claim displays claim values required to be present in the ID token.

resource server required-claim displays claim values required to be present in the access token.

<required-claim-name-pattern> is the required claim name filter to apply to the command; may contain wildcard characters * or ?.

detail displays detailed information about the OAuth profile.

stats displays statistics about the OAuth profile.

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 Client Authentication Example Configuration

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

In this example:

• The OAuth discovery endpoint is located at https://oauthdiscovery.com and requires credentials of oauthServerUsername/oauthServerPassword through HTTPS.
• The OAuth issuer is located at https://oauthissuer.com.
• The OAuth role is set to resource-server, which means the event broker is configured to expect clients to present access tokens when they attempt to authenticate.

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-profile myOauthProfile
solace(...gure/message-vpn/authentication/oauth)# create profile myOauthProfile
solace(...sage-vpn/authentication/oauth/profile)# no shutdown
solace(...sage-vpn/authentication/oauth/profile)# oauth-role resource-server
solace(...sage-vpn/authentication/oauth/profile)# issuer https://oauthissuer.com
solace(...sage-vpn/authentication/oauth/profile)# client-id oauthServerUsername
solace(...sage-vpn/authentication/oauth/profile)# client-secret oauthServerPassword
solace(...uthentication/oauth/profile/endpoints)# discovery https://oauthdiscovery.com

Compatibility with Older Versions

For compatibility with versions prior to 9.12.1, the OAuth provider for MQTT client commands have been deprecated but will continue to work until September 15, 2024. After September 15, 2024, these commands will be removed.

If you have an existing OAuth MQTT deployment you must migrate your OAuth provider configuration to a Message VPN OAuth profile configuration before the deprecation period ends.

Differences between OAuth Providers and OAuth Profiles in Message VPNs

• The OAuth Issuer Identifier is used to identify the appropriate OAuth provider configuration. In most cases this allows identification of the appropriate provider from the token alone. Note that MQTT clients that explicitly specify a provider must still specify the broker configuration name, for API compatibility.
• The OpenID Connect Userinfo endpoint (similar to the OAuth introspection endpoint) is supported.
• The username and groups claim are searched in multiple places, supporting deployments where both thick tokens (tokens with extra information such as groups) and thin tokens (tokens that only have the bare minimum information for authentication) are present for the same provider.
• Configuration is fetched from the discovery URL, meaning you aren't required to configure other endpoints and the issuer identifier.
• Issuer identity is verified, plus a number of other security checks.
• The allowed OAuth type (OpenID Connect or plain OAuth) is determined by the OAuth role in the configuration (see OAuth Role), instead of being dynamically determined on a per-connection basis from connection information.
• There is no configuration flag to ignore time limits specified in the token.

Configuring the Connection Behavior for Duplicate Clients

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

By default, they 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.

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.