Controlling Client Access with ACL Profiles
After a client is successfully authenticated, the ACL profile assigned to the client username used by the client, or the LDAP the authorization groups that the client belongs to (when LDAP authorization is used), is checked. This ACL profile controls whether an authenticated client is:
- permitted to establish a connection with the router (refer to Client Connection Access Controls)
- permitted to publish and subscribe to specific topics (refer to Topic Access Controls)
- If an administrator does not assign a specific ACL profile to a client username, it is automatically assigned the ACL profile named
default. This default ACL profile is preconfigured for each Message VPN on a Solace router. Although you can modify the configuration of the
defaultACL profile, this ACL profile cannot 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
Related Provisioning and Configuration Information
For information on how to use the Solace CLI to configure and manage ACLs on the Solace router, refer to Configuring Access Control Lists.
ACL profiles have a client connection access control that is used to determine whether clients are allowed to connect to a Solace router.
Client connection attempts can either be
allow (permit client connections) or
disallow (deny client connections). The default action for user-defined ACLs is
disallow. The default actions for the
#acl-profile ACL profiles is
After you have 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 expressed in Classless Inter‑Domain Routing (CIDR) address form (nnn.nnn.nnn.nnn/nn). Any client whose address falls into any of the IP/mask in this list gets 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.
Note: 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 Solace router. 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 capturing:
- 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)
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 may publish to and which topics they may subscribe to.
An ACL profileʼs publish-topic access control will have:
- A default action of
allowsets the default action to allow the publishing of messages to topics, and
disallowsets 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 separately.
An ACL profileʼs subscribe-topic access control will have:
- A default action of
allowsets the default subscribe action to allow clients to subscribe to topics, and
disallowsets 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 separately.
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, as well as reserved Solace topics that are used for special messaging features. For example, there are unique topics 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 Special Solace Topics.
For deployments that will have a lot of connecting clients (for example, IoT deployments may have thousands or hundreds of thousands of clients), you may want to configure ACL rules so that clients can only:
- publish to topics containing their own MQTT client ID or client username (to prevent a client from impersonating another client)
- subscribe to topics containing their own MQTT client ID or client username (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’s MQTT ID (
$client-idis encountered in an ACL topic exception, the router will substitute the MQTT client-ID that the client provided when it established its session.
$client-idonly applies to MQTT sessions.
- client username (
$client-usernameis encountered in an ACL topic exception, the router 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 router 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 router 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-hashrepresents the unique 8-byte long “client-username-hash” that the router generates for clients using that client username.
If substitution variables are used in ACL topic exceptions, when the router applies the ACL profile for a client, it will replace the variables in the topic exceptions with the corresponding MQTT client ID or client username that the client provided when it established its connection to the router or the client-username-hash generated by the router.
Substitution variables must appear alone at any level in the topic exception, but they may 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$client-id/* are not valid because
$client-id does not stand alone at a level.
ALERT! If you use substitution variables in ACL topic exceptions, you must ensure that MQTT IDs or client-usernames do not contain the “/” character. Although “/” is a valid character in MQTT IDs or client usernames, because the router uses “/” as a delimiter between levels in a topic, any MQTT IDs or client usernames that contain “/” characters will never be able to match the
$client-username elements of an ACL rule. Note that the router does not enforce this restriction.
- Substitution variables are only used by Solace VMRs Version 8.2.x or greater. They are not available for Solace appliances.
- The strings
$client-username-hashhave 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
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, a subscription to
ANIMALS/CATS) is disallowed. If
ANIMALS/>were accepted, then messages published to
ANIMALS/>and be delivered to the client. This would contradict the intention of the ACL.
- 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
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 could 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 capturing:
- 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)