Controlling Client Access with ACL Profiles

ACL profiles control which clients can connect to a Message VPN and which topics connected clients are allowed to publish and subscribe to. They provide a powerful and scalable way to control what clients can and cannot access on an event broker.

After a client authenticates successfully with an event broker, the event broker checks the ACL profile assigned to the client based on the client username or the LDAP authorization group that the client belongs to.

For more information about:

  • 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 instructions to configure and manage ACLs, see one of the following topics:

Client Connection Access Controls

ACL profiles include a client connection ACL that determines whether clients are allowed to connect to a Message VPN on an event broker.

The ACL can be configured to either allow or disallow all connections and take the opposite action for clients included on the exception list. The default action for the default ACL profile is allow. The default action for user-defined ACL profiles is disallow.

After you set the default client connection action, you can create a list of clients that are exceptions to the default action. The exceptions list uses 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.

For example, if the client connection 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. 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 allowed to connect 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 Subscription 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. 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 variables can be helpful for deployments that have a large number of connecting clients (for example, IoT deployments may have thousands or hundreds of thousands of clients) where you may want to configure ACLs to limit clients to the following actions:

  • Publishing to topics containing their own client username or MQTT client ID to prevent a client from impersonating another client.
  • Subscribing to topics containing their own client username or MQTT client ID to prevent a client from receiving data that is intended for another client.
  • Listening to their own #P2P topic to prevent a client from receiving a reply message that is intended for another client.

Manually setting up these types of restrictions for large numbers of clients is not practical. Instead you can configure ACL topic exceptions using the following special substitution variables:

Variable Expression Description

Client username

$client-username

When $client-username is encountered in an ACL topic exception, the event broker substitutes the client username provided by the client or retrieved from the TLS client-certificate during client login.

Client username hash

$client-username

When a client attempts to establish a connection, the event broker automatically creates 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 MQTT ID

$client-id

This variable applies only to MQTT sessions. When $client-id is encountered in an ACL topic exception, the event broker substitutes 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 are treated as literal strings and have no special meaning.

If an ACL topic exception includes substitution variables, when the event broker applies the ACL profile for a client, it replaces the variables in the topic exception with the corresponding client username or MQTT client ID 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* is 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. 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.

For more information about using substitution variables with ACLs, see Improving IoT Security with Access Control List Substitution Variables.

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

  • If an ACL profile allows all subscriptions by default , subscriptions containing wildcards have the following behavior:
    • A subscription containing the * wildcard that would include a disallowed exception is allowed. For example, If you have an exception for the SMF subscription animals/cats, animals/c* is allowed.
    • A subscription containing the > wildcard that would include a disallowed exception is also disallowed. For example, If you have an exception for the SMF subscription animals/cats, animals/> is disallowed.
  • If the ACL profile disallows all subscriptions by default, 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, SMF subscription requests to animals/> and animals/d* are both disallowed.

For more information about subscription wildcards, see Wildcard Characters in Topic Subscriptions.

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)