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 ACL profiles, see the following sections:

• Considerations for Using ACL Profiles
• Client Connection Access Controls
• Topic Access Controls
• Creating ACL Profiles
• Updating ACL Profiles
• Associating an ACL Profile with a Client Username
• Associating an ACL Profile with an Authorization Group

Considerations for Using ACL Profiles

You should be aware of the following details when using ACL profiles:

• PubSub+ Cloud includes a preconfigured ACL profile named Default, which includes no restrictions. You can modify the configuration of the Default ACL profile, but you can't delete it.
• If no ACL profile is assigned to a client, the client is assigned the Default profile.
• All clients that are automatically created by the system for internal features are assigned to a preconfigured ACL profile named #acl-profile. You can't modify or delete this profile.

• Each ACL profile has the following ACLs. You set the default action to Allow or Disallow and then set exceptions for each one:

  • Client connect—Specify a list of clients that are exceptions to the default action for client connections. 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 default action. For more information, see Client Connection Access Controls.

  • Publish topic—Specify a list of topics that are exceptions to the default action for publishing topics. Each topic can be up to 250 characters and must be constructed with the appropriate topic syntax (SMF or MQTT) as specified in the exception. To control publishing to queues, you can use a topic pattern that represents specific queues. For more information, see Publish Topic Exceptions.

    Subscribe topic—Specify a list of topics that are exceptions to the default action for client subscriptions to topics. The ACL profile does not apply to subscriptions from queues and topic endpoints. For more information, see Subscribe Topic Exceptions.

  • Subscribe share name—Specify a list of shared subscription identifiers that are exceptions to the default action for shared subscriptions. For more information, see Shared Subscriptions.

For instructions to configure ACL profiles, see Creating ACL Profiles.

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.

Topic Access Controls

ACL profiles include publish topic and subscribe topic ACLs that let you specify which topics clients can publish to and which topics they can subscribe to. You can also control shared subscriptions that the client can subscribe to.

The topic access ACLs can each be configured to allow or disallow publishing or subscribing to all topics and take the opposite action for topics included on the exceptions list. The default action for the Default ACL profile is Allow. The default action for user-defined ACL profiles is Disallow. The default action applies to both SMF and MQTT topics. However, you must specify exceptions for SMF and MQTT topic syntax separately.

There is no limit to the number of topic exceptions per ACL profile. However, keep in mind that the more exceptions you have, the more difficult it is to comprehend and manage your topic access control configuration.

Topic ACLs can affect both regular topic subscriptions and reserved topics that are used for special messaging features. For example, event brokers have unique topics that allow clients to publish and subscribe to topics bound to queues (#P2P/QUE/<queue‑name>) and topics that are only for the consumption of one specific client (#P2P/v:brokerName/clientUsernameHash/clientName/>). For a complete list of special topics and their use, see Reserved Topics.

Publish Topic Exceptions

Publish topic exceptions can include topics in SMF and MQTT format and exceptions for publishing topics for Direct messaging and to specific queues for Guaranteed messaging. The topic pattern for a queue is #P2P/QUE/<queueName>.

For example, if you want to configure an ACL that allows clients to publish messages only to the queue named MyQueue, you would set the default action to Disallow and enter the topic exception #P2P/QUE/MyQueue.

Topics used for Direct request/reply messaging, are exempt from publish topic ACL checks and won't be blocked.

Subscribe Topic Exceptions

If you want to restrict access to subscribe to specific topics, Solace recommends setting the default subscribe action set to Disallow and including allowed topics in the exceptions list.

Topic subscription exceptions have the following limitations with Guaranteed messaging:

• Subscribe topic access controls do not apply to queues and topic endpoints, and are not checked when a client binds to an endpoint. Consuming clients can bypass subscribe topic access control restrictions by binding directly to a queue or topic endpoint with a topic subscription that is disallowed by the ACL profile.
• Subscribe topic access controls do prevent a client from adding a specific topic subscription to a queue if the client is not permitted to subscribe to that topic.

If you want to ensure that snooping of #P2P topics used for Direct request/reply messaging cannot occur, set the subscribe topic default action to disallow. When set to disallow, clients can still subscribe to their own #P2P topics because the event broker automatically adds an exception topic of the form #P2P/v:brokerName/$client-username-hash/>. This subscription topic is not shown in the exceptions list.

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.

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.

Creating ACL Profiles

You can create ACL profiles to assign to clients. If you don't assign an ACL profile to a client, the Default profile is automatically assigned.

To create an ACL profile, perform these steps:.

1. Open Broker Manager. For instructions, see Using PubSub+ Broker Manager.
2. On the left navigation bar, select Access Control.
3. Select the ACL Profiles tab.
4. Click + ACL Profile.
5. Enter a name for the ACL profile and click Create.
6. To set client connect exceptions, perform the following steps: 
   1. Select the Client Connect tab.
   2. (Optional) To change the Client Connect Default Action to Allow, click Edit , select Allow from the drop-down list and click Apply.
   3. To add a client to the Exceptions list, click + Exception, enter the client address in CIDR format (nnn.nnn.nnn.nnn/nn) and click Create.
   4. Repeat step c for every exception you want to add.
7. To set publish topic exceptions, perform the following steps: 
   1. Select the Publish Topic tab.
   2. (Optional) To change the Publish Default Action to Allow, click Edit , select Allow from the drop-down list and click Apply.
   3. To add a topic to the Exceptions list, click + Exception, enter the topic and select the topic format, then click Create.
   4. Repeat step c for every exception you want to add.
8. To set subscribe topic exceptions, perform the following steps: 
   1. Select the Subscribe Topic tab.
   2. (Optional) To change the Subscribe Default Action to Allow, click Edit , select Allow from the drop-down list and click Apply.
   3. To add a topic to the Exceptions list, click + Exception, enter the topic and select the topic format, then click Create.
   4. Repeat step c for every exception you want to add.
9. To set subscribe share name exceptions, perform the following steps: 
   1. Select the Subscribe Share Name tab.
   2. (Optional) To change the Subscribe Share NameDefault Action to Allow, click Edit , select Allow from the drop-down list and click Apply.
   3. To add a topic to the Exceptions list, click + Exception, enter the shared subscription identifiers and select the topic format, then click Create.
   4. Repeat step c for every exception you want to add.

Updating ACL Profiles

You can update existing ACL profiles used by clients. You can also create new ACL profiles by cloning and updating an existing profile.

You can change default actions when you update an ACL profile, but keep in mind that changing the default reverses the meaning of the exceptions list. For example, if the default publish action is disallow and you list topic exceptions that clients can publish to, changing the default publish action to allow means that clients are now blocked from publishing to any of the topics on the exceptions list.

When you update an ACL profile by changing the default client connect action or removing clients from the exceptions list, clients with established connections are not disconnected.

To update an ACL profile, perform these steps:.

1. Open Broker Manager. For instructions, see Using PubSub+ Broker Manager.
2. On the left navigation bar, select Access Control.
3. Select the ACL Profiles tab.
4. (Optional) To create a new profile by cloning and updating an existing one, perform these steps:
   1. Select the check box next to the profile you want to clone.
   2. Click Action , and select Clone.
   3. Enter a name for the new ACL profile.
   4. Select the exception lists you want to clone.
   5. Click Apply.
5. Click the name of the ACL profile you want to update.
6. To update an exception list, perform the following steps: 
   1. Select the tab for the ACL type.
   2. To add an item to the Exceptions list, click + Exception, enter the client address, topic, or share name you want to add.
   3. To remove an item to the Exceptions list, select the check box next to the item you want to remove, then click Action , and select Delete.

Associating an ACL Profile with a Client Username

When clients connect to an event broker using a client username, each client uses the ACL profile associated with their client username. For more information about managing client usernames, see Creating and Managing Client Usernames.

To assign an ACL profile to a client username perform these steps:

1. Open Broker Manager. For instructions, see Using PubSub+ Broker Manager.
2. On the left navigation bar, select Access Control.
3. Select the Client Usernames tab.
4. Click the client username you want to update.
5. Click Edit .
6. In the ACL Profile list, select the name of the ACL profile you want to associate with the client username.
7. Click Apply.

Associating an ACL Profile with an Authorization Group

If you are using LDAP client authorization you can associate an ACL profile with an authorization group.

To assign an ACL profile to an authorization group, perform these steps:

1. Open Broker Manager. For instructions, see Using PubSub+ Broker Manager.
2. On the left navigation bar, select Access Control.
3. On the Client Authentication tab, select the Authorization Groups tab.
4. Click the authorization group you want to update.
5. Click Edit .
6. In the ACL Profile list, select the name of the ACL profile you want to associate with the authorization group.
7. Click Apply.