Controlling Client Access with ACL Profiles

After a client authenticates successfully, the event broker checks the ACL profile assigned to the client based on either:

  • the client's username, or
  • the LDAP authorization groups that the client belongs to (when LDAP authorization is used)

This ACL profile controls whether an authenticated client is permitted to:

  • If an administrator doesn't assign a specific ACL profile to a client username, that username is automatically assigned the ACL profile named default. The default ACL profile is preconfigured for each Message VPN on an event broker. Although you can modify the configuration of the default ACL profile, this ACL profile can't be deleted.
  • All internal clients that are automatically created by the system for internal features (for example, the Config-Sync client #config-sync) are assigned to the ACL profile #acl-profile.

For information about using the Solace CLI to configure and manage ACLs on event brokers, see ACL Configuration.

Client Connection Access Controls

ACL profiles have a client connection access control that determines whether clients are allowed to connect to an event broker.

Client connection attempts can be configures to allow (permit client connections) or disallow (deny client connections). The default action for user-defined ACLs is disallow. The default action for the default and #acl-profile ACL profiles is allow.

After you set the default client connection action, you can create a list of clients that should be exceptions to the default action. Clients to be excepted must be defined in Classless Inter‑Domain Routing (CIDR) address format (nnn.nnn.nnn.nnn/nn). Any client whose address falls into any of the IP/mask in this list has the opposite behavior to the configured default action. There is a system-level limit of 10,000 ACL profile connect exceptions.

For example, if the client-connect access control for an ACL uses a default action of allow, but 10.1.1.0/24 is listed as an exception, clients on the 10.1.1.0/24 network are denied access to the Message VPN. Similarly, if the default client connection action is disallow, and a client on a network on the exceptions list attempts to connect, that client is connected with no restrictions.

Changing the default client connect action, or removing clients from the exceptions list, does not immediately affect clients that already have an established connection to the event broker. They remain connected.

A global statistic and a per-message VPN statistic is incremented for every denied connection attempt. In addition, a circular log is also maintained that captures:

  • the current timestamp
  • the IP/port of the denied client
  • the username of the denied client
  • the Message VPN of the denied client
  • the client name of the denied client (shown only when the show log acl User EXEC command is used with the wide parameter option)
  • the ACL profile name that triggered the denial (shown only when the show log acl User EXEC command is used with the wide parameter option)

Topic Access Controls

ACL profiles provide publish-topic and subscribe-topic access controls, which enable you to set which topics Solace Message Format (SMF) and Message Queuing Telemetry Transport (MQTT) clients can publish to and which topics they can subscribe to.

An ACL profileʼs publish-topic access control has:

  • A default action of allow or disallow, where allow sets the default action to allow the publishing of messages to topics, and disallow sets the default action to disallow the publishing of messages to topics. The configured default action applies to both SMF and MQTT topics.
  • An optional list of specific topics that you want to be excepted from the default publish-topic action. Topic exceptions must be made for SMF and MQTT topics syntax separately.

For more information about setting publish-topic access control, see Configuring Topic Publish Permissions.

An ACL profileʼs subscribe-topic access control has:

  • A default action of allow or disallow, where allow sets the default subscribe action to allow clients to subscribe to topics, and disallow sets the default subscribe action to disallow clients from subscribing to topics. The configured default action applies to both SMF and MQTT topics.
  • An optional list of specific topics that you want to be excepted from the default subscribe-topic action. Topic exceptions must be made for SMF and MQTT topics syntax separately.

Using ACL profiles with a default subscribe action set to allow is not recommended when the goal is to restrict access to specific topics. This approach can result in unexpected behavior, particularly concerning wildcard handling (see Wildcard Handling). ACL profiles with a default subscribe action of allow are best suited for scenarios where there are no restrictions on the topics a client can subscribe to.

For more information on setting subscribe-topic access control, see Configuring Topic Subscribe Permissions.

There is no limit to the number of publish or subscription topic exceptions per ACL profile. However, there is a maximum of 40,000 exceptions (publish and subscription topic exceptions combined) allowed among all profiles. Also keep in mind that the more exceptions there are, the more difficult it is to comprehend and manage your topic access control configuration.

The topics that these access controls affect can be regular topic subscriptions, and reserved Solace topics that are used for special messaging features. For example, there are unique topics that allow clients to publish and subscribe to topics bound to durable queues (#P2P/QUE/<queue‑name>) and topics that are only for the consumption of one specific client (#P2P/v:routerName/clientUsernameHash/clientName/>). For a complete list of special topics and their usage, see Reserved Topics.

Using Substitution Variables in Topic Exceptions

Substitution can be helpful for deployments that have a lot of connecting clients (for example, IoT deployments may have thousands or hundreds of thousands of clients) where you may want to configure ACL rules so that those clients can only:

  • publish to topics containing their own client username or MQTT client ID (to prevent a client from impersonating another client)
  • subscribe to topics containing their own client username or MQTT client ID (to prevent a client from receiving data that is intended for another client)
  • listen to their own #P2P topic (to prevent a client from receiving a reply message that is intended for another client)

To manually set up these types of restrictions for large numbers of clients is not practical. So, instead you can configure ACL topic exceptions with special substitution variables for one of the following:

  • client username ($client-username)—When $client-username is encountered in an ACL topic exception, the event broker will substitute the client username provided by the client or retrieved from the TLS client-certificate during client login.
  • client username hash ($client-username-hash)—When a client attempts to establish a connection, the event broker will automatically create a #P2P topic (#P2P/v:routerName/client-username-hash/clientname/>) for the client so that it can use Direct Request/Reply messaging. The event broker creates this topic based on the client username provided by the client or retrieved from the TLS client-certificate during client login. The variable $client-username-hash represents the unique 8-byte long “client-username-hash” that the event broker generates for clients using that client username.
  • client’s MQTT ID ($client-id)— This configuration only applies to MQTT sessions. When $client-id is encountered in an ACL topic exception, the event broker will substitute the MQTT client-ID that the client provided when it established its session.

The strings $client-id, $client-username, and $client-username-hash have special meaning only for ACL exception topics. If they are used in regular topic subscriptions, they will be treated as literal strings and have no special meaning.

If substitution variables are used in ACL topic exceptions, when the event broker applies the ACL profile for a client, it replaces the variables in the topic exceptions with the corresponding client username or MQTT client ID that the client provided when it established its connection to the event broker or the client-username-hash generated by the event broker.

Substitution variables must appear alone at any level in the topic exception, but they can appear multiple times in a single exception. For example, FRUIT/$client-id/$client-username/APPLES are valid uses of substitution variables. While FRUIT/$client-id* and FRUIT/$client-id$client-id/* are not valid because $client-id does not stand alone at a level.

If you use substitution variables in ACL topic exceptions, you must ensure that client usernames or MQTT client IDs do not contain the “/” character. Although “/” is a valid character in MQTT client IDs or client usernames, because the event broker uses “/” as a delimiter between levels in a topic, any MQTT client IDs or client usernames that contain “/” characters will never be able to match the $client-id or $client-username elements of an ACL rule. Note that the event broker does not enforce this restriction.

Wildcard Handling

Subscriptions are either fully accepted or fully rejected depending on whether they match the configured topic access controls. Special rules are employed when handling subscriptions containing wildcards to ensure configured ACLs are effective in blocking the traffic they have been configured to disallow. Wildcard subscriptions that match an ACL profile’s exceptions are disallowed if the ACL profile’s default rule is to allow all subscriptions. For example:

  • If an ACL profile has been configured to allow all subscriptions except for the SMF subscription ANIMALS/CATS, subscriptions containing wildcards can lead to unexpected behavior. A subscription using a > wildcard (covering ANIMALS/CATS) is disallowed, but a subscription containing a * wildcard is allowed. In other words, a subscription to ANIMALS/> is disallowed, but a subscription to ANIMALS/C* is allowed.
  • If the ACL profile’s default rule disallows all subscriptions, wildcard characters in the subscription are not given any special treatment when establishing matching exception rules. For example, if an ACL profile has been configured to disallow all subscriptions except ANIMALS/DOGS, an SMF subscription request to ANIMALS/> would be disallowed given that the “>” would not be treated as a wildcard character and therefore not cover the exception rule of ANIMALS/DOG. In suppressing the subscription, which requested everything below ANIMALS, the ACL profile’s intention of only allowing access to ANIMALS/DOG is enforced.

Subscribe Topic Access Controls with Guaranteed Messaging

ACLs can be used with Guaranteed messaging, but the following limitations should be considered:

  • Subscribe-topic access controls are not considered when a consuming client binds directly to a durable endpoint (either a queue or topic endpoint). Therefore, a client can bypass subscribe-topic access control restrictions that have been set for it.
  • Subscribe-topic access controls can prevent a client from adding a specific topic subscription to a queue if the client is not permitted to subscribe to that topic. However, a client can bind to an existing queue that has been mapped to a topic that the client is not permitted to subscribe to because the client’s subscribe-topic access controls are not checked when it binds to a queue.

Topic Access Control Statistics

A global, per-Message VPN, and per-client statistic is incremented for every denied publish or subscribe topic attempt. In addition, a circular log is also maintained that captures:

  • the current timestamp
  • the username of the denied client
  • the Message VPN the client was a member of
  • the topic that was denied
  • the client name of the denied client (shown only when the show log acl User EXEC command is entered with the wide parameter option)
  • the ACL profile name that triggered the denial (shown only when the show log acl User EXEC command is entered with the wide parameter option)