ACL Configuration

Access Control Lists (ACLs) are used to manage whether clients may connect to Message VPNs, which topics clients are allowed to publish to, and which topics and share names clients are allowed to subscribe to in that Message VPN. Each of these access controls require a defined default action (allow or disallow connection, allow or disallow publishing to topics, allow or disallow subscribing to topics, and allow or disallow subscribing to share names), and you can configure explicit exceptions to those default actions.

To set up and use ACLs, you perform the following steps:

Creating ACL Profiles

The first thing you need to do is create an ACL Profile.

To create a new ACL profile for a Message VPN, enter the following CONFIG command: 

solace(configure)# create acl-profile <name> message-vpn <vpn-name> [allow-client-connect] [allow-publish-topic] [allow-subscribe-topic] [disallow-subscribe-share-name]

To edit the configuration parameters for an existing ACL profile on a Message VPN, enter the following CONFIG command:

solace(configure)# acl-profile <name> message-vpn <vpn-name>

Where:

  • <name> is the name of the ACL profile. The name can contain up to 32 alphanumeric characters (case-sensitive). The "_" character is also permitted. Names must be unique across all ACL profiles for a Message VPN, although the same name can be used in different Message VPNs.
  • <vpn-name> is the name of the Message VPN that the ACL belongs to.
  • allow-client-connect sets the default action to allow client connection attempts.
  • allow-publish-topic sets the default action to allow the publishing of messages to topics.
  • allow-subscribe-topic sets the default action to allow clients to subscribe to topics.
  • disallow-subscribe-share-name sets the default action to disallow clients from subscribing to share names.

The no version of this command, no acl-profile <name>, deletes the ACL profile from the Message VPN.

Configuring Client Connect Authorization

You can use ACLs to control which clients may connect to a Message VPN.

To set the default action for client connection attempts, enter the following CONFIG commands: 

solace(configure/acl-profile)# client-connect
solace(configure/acl-profile/client-connect)# default-action {allow | disallow}

Where:

  • allow sets the default action to allow client connection attempts.
  • disallow sets the default action to disallow client connection attempts. This is the default value.

To set the exceptions to the default action for client connection attempts, enter the following CONFIG commands:

solace(configure/acl-profile)# client-connect
solace(configure/acl-profile/client-connect)# exception <cidr-addr>

Where:

<cidr-addr> is the IP address and network mask combination of the excepted client in Classless Inter-Domain Routing (CIDR) form: nnn.nnn.nnn.nnn/dd (where nnn is 0-255, dd is 1-32).

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 PubSub+ event broker. They remain connected.

An example of how to use these commands is shown in Controlling Which Clients Can Connect.

Configuring Topic Publish Permissions

You can use ACLs to control the topics to which clients are allowed to publish.

To set whether the default action is to allow clients to publish to topics or not, enter the following CONFIG command: 

solace(configure/acl-profile)# publish-topic
solace(configure/acl-profile/publish-topic)# default-action {allow | disallow}

Where:

  • allow sets the default action to allow the publishing of messages to topics.
  • disallow sets the default action to disallow the publishing of messages to topics. This is the default value.

If you change the default action for an ACL profile, any existing topics listed as exceptions are maintained as exceptions, but their behavior becomes the opposite of what it was.

To set exceptions to the default action for publishing topic access attempts, enter the following CONFIG command:

solace(configure/acl-profile)# publish-topic
solace(configure/acl-profile/publish-topic)# exceptions [smf | mqtt] list <exception-list>

Where:

  • smf indicates that the topic to be excepted uses Solace Messaging Format (SMF) topic syntax. By default, if neither smf or mqtt is explicitly entered, the topic will be an SMF topic exception. For information on topic syntax and considerations that should made for Solace PubSub+ to handle SMF and MQTT topics similarly, see Topic Support & Syntax.
  • mqtt indicates that the topic to be excepted uses Message Queuing Telemetry Transport (MQTT) topic syntax.
  • <exception-list> is a list of space-separated topics (in the form a/b/c) to be excepted from the default action. Each topic may be up to 250 characters. The listed topics should be constructed with the appropriate topic syntax (either SMF or MQTT topic syntax ); however, regardless of syntax, all exceptions apply to all clients, independent of their wireline protocol, to which the ACL is assigned. Leading "!" characters (in the form !a/b/c), which are used to indicate subscription exceptions in queues, do not receive special handling and are treated as literal characters in ACL topic exception lists. For more information about subscription exceptions, see System-Level Subscription Exception Configuration.

The no version of this command, no exceptions, removes any given topic publish exceptions.

Published topics of the form #P2P/v:*/>, which are used for clientsʼ Direct Request/Reply messaging, are exempt from publish-topic ACL checks.

An example of how to use these commands is shown in Controlling Which Topics a Client May Publish and Subscribe To.

Substitution Variables

For Solace PubSub+ software event brokers version 8.2.0+ and Solace PubSub+ appliance versions 8.3.0+, the following substitution variables can be used in a topic level of an ACL topic exception:

  • $client-id—For this variable, the event broker will substitute the MQTT client-ID that the client provided when it established its session. $client-id only applies to MQTT sessions.
  • $client-username—For this variable, 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—For this variable, the event broker will substitute the unique 8-byte long "client-username-hash" that the event broker generates for a client based on the client username the client provided or was retrieved from the TLS client-certificate during client login. This identifying client-username-hash is used in the #P2P topic (#P2P/v:routerName/client-username-hash/clientname/>) that the event broker creates for the client so that it can use Direct Request/Reply messaging.

For more information on how substitution values can be used in topic exceptions, see Using Substitution Variables in Topic Exceptions.

Publishing to Queues

To control publishing to queues, a topic pattern that represents specific queues may be listed. The topic pattern for a queue is #P2P/QUE/<queueName> and an example of how to use this to prevent publication to a queue is shown in Controlling Which Queues Clients May Publish To.

Configuring Topic Subscribe Permissions

You can use ACLs to control the topics to which clients are allowed to subscribe.

To set whether the default action is to allow clients to subscribe to topics or not, enter the following CONFIG commands:

solace(configure/acl-profile)# subscribe-topic
solace(configure/acl-profile/subscribe-topic)# default-action {allow | disallow}

Where:

  • allow sets the default subscribe action to allow clients to subscribe to topics.

    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.

  • disallow sets the default subscribe action to disallow clients from subscribing to topics. This is the default value.

If you change the default action for an ACL profile, existing user-configured exceptions are maintained as exceptions, but their behavior becomes the opposite of what it was.

If you want to ensure that snooping of #P2P topics that are used for Direct Request/Reply messaging cannot occur, you should set the subscribe-topic default-action to disallow. When set to disallow, clients will still be able to subscribe to their own #P2P topics because the event broker automatically adds an exception topic of the form #P2P/v:routerName/$client-username-hash/>. If the subscribe-topic default-action is later changed to allow, this exception topic will be automatically removed. (Note that this auto-added topic is not visible through the Solace CLI.)

To set any exceptions to the default action for topic subscriptions, enter the following CONFIG commands:

solace(configure/acl-profile)# subscribe-topic
solace(configure/acl-profile/subscribe-topic)# exceptions [smf | mqtt] list <exception-list>

Where:

  • smf indicates that the topic to be excepted is an SMF topic. If neither smf or mqtt is not explicitly entered, by default the topic will be an SMF topic exception. For information on topic syntax and considerations that should made for Solace PubSub+ to handle SMF and MQTT topics similarly, see Topic Support & Syntax.
  • mqtt indicates that the topic to be excepted is an MQTT topic.
  • <exception-list> is a list of space-separated topics (in the form a/b/c) to be excepted from the default action. Each topic may be up to 250 characters. The listed topics should be constructed with the appropriate topic syntax (either SMF or MQTT topic syntax); however, regardless of their syntax, all exceptions apply to all clients, independent of their wireline protocol, to which the ACL is assigned. Leading "!" characters (in the form !a/b/c), which are used to indicate subscription exceptions in queues, do not receive special handling and are treated as literal characters in ACL topic exception lists. For more information about subscription exceptions, see System-Level Subscription Exception Configuration.

The no version of this command, no exceptions, removes any given topic subscribe exceptions.

Subscriptions of the form #P2P/v:*/> are subject to subscribe-topic ACL checks.

An example of how to use these commands is shown in Controlling Which Topics a Client May Publish and Subscribe To.

Substitution Variables

For Solace PubSub+ software event brokers version 8.2.0+ and Solace PubSub+ appliance versions 8.3.0+, the following substitution variables can be used in a topic level of an ACL topic exception:

  • $client-id—For this variable, the event broker will substitute the MQTT client-ID that the client provided when it established its session. $client-id only applies to MQTT sessions.
  • $client-username—For this variable, 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—For this variable, the event broker will substitute the unique 8-byte long "client-username-hash" that the event broker generates for a client based on the client username the client provided or was retrieved from the TLS client-certificate during client login. This identifying client-username-hash is used in the #P2P topic (#P2P/v:routerName/client-username-hash/clientname/>) that the event broker creates for the client so that it can use Direct Request/Reply messaging.

For more information on how substitution values can be used in topic exceptions, see Using Substitution Variables in Topic Exceptions.

Configuring Share Name Subscribe Permissions

You can use ACLs to control the share names to which clients are allowed to subscribe. Share names in this case are the identifiers associated with shared subscriptions. For more information, refer to Syntax of Shared Subscriptions.

To set whether the default action is to allow clients to subscribe to share names or not, enter the following CONFIG commands: 

solace(configure/acl-profile)# subscribe-share-name
solace(configure/acl-profile/subscribe-share-name)# default-action {allow | disallow}

Where:

  • allow sets the default subscribe action to allow clients to subscribe to share names. This is the default value.
  • disallow sets the default subscribe action to disallow clients from subscribing to share names.

If you change the default action for an ACL profile, existing user-configured exceptions are maintained as exceptions, but their behavior becomes the opposite of what it was.

To set any exceptions to the default action for share name subscriptions, enter the following CONFIG commands:

solace(configure/acl-profile)# subscribe-share-name
solace(configure/acl-profile/subscribe-share-name)# exceptions [smf | mqtt] list <exception-list>

Where:

  • smf indicates that the share name to be excepted is an SMF share name. If neither smf or mqtt is not explicitly entered, by default the share name will be an SMF share name exception.
  • mqtt indicates that the share name to be excepted is an MQTT share name.
  • <exception-list> is a list of space-separated share names to be excepted from the default action. Each share name may be up to 250 characters. The listed share names should be constructed with the appropriate syntax (either SMF or MQTT syntax).

Assigning ACLs to Client Usernames

To assign an ACL profile to a client username account, enter the following CONFIG commands:

solace(configure)# client-username <username> message-vpn <vpn-name>
solace(configure/client-username)# acl-profile <name>

Where:

  • <username> is the username of the client username account
  • <vpn-name> is the name of the Message VPN the client username belongs to
  • <name> is the name of the ACL profile

The no version of this command, no acl-profile, resets the assigned profile for the client username account back to the profile named default.

A client username must be shutdown before an ACL profile can be assigned to it.

ACL Configuration Examples

This section shows the basic procedural steps that are required configure ACLs on an event broker. The exact steps required will vary depending on your network conditions and preferred configuration.

Controlling Which Clients Can Connect

The following example configures a client-connect ACL profile that disallows clients on IP subnet 10.10.0.0/16 from connecting to the event broker, and allows clients from other IP subnets to connect.

  1. Create an ACL profile:
    2. solace(configure)# create acl-profile analyst_group_d message-vpn blue
    solace(configure/acl-profile)#
  2. Set the default action for client connection access attempts: 
    solace(configure/acl-profile)# client-connect
    solace(configure/acl-profile/client-connect)# default-action allow
  3. Set exceptions to the default action for client connection access attempts: 
    solace(configure/acl-profile/client-connect)# default-action exception 10.10.0.0/16
  4. Assign the ACL profile to a given client username: 
    solace(configure)# client-username joe message-vpn blue
    solace(configure/client-username)# acl-profile analyst_group_d

Controlling Which Topics a Client May Publish and Subscribe To

The following example configures a topic-access ACL profile so that:

  • Clients cannot publish to the animals/domestic/cats topic (all other topics are allowed)
  • Clients cannot use a subscription to the animals/domestic/dogs topic (all other topics are allowed)

It then assigns the configured ACL profile to a particular client username.

  1. Set the default action for publishing topic attempts:
    2. solace(configure)# acl-profile analyst_group_d message-vpn blue
    solace(configure/acl-profile)# publish-topic
    solace(configure/acl-profile/publish-topic)# default-action allow
  2. Set exceptions to the default action for publishing topic attempts:
    3. solace(configure/acl-profile/publish-topic)# exception animals/domestic/cats
  3. Set the default action for topic subscription attempts:
    4. solace(configure/acl-profile)# subscribe-topic
    solace(configure/acl-profile/subscribe-topic)# default-action allow
  4. Set exceptions to the default action for topic subscription attempts:
    5. solace(configure/acl-profile/subscribe-topic)# exception animals/domestic/dogs
  5. Verify that the ACL profile is correct:
    6. solace> show acl-profile analyst_group_d message-vpn blue

                                                       Allowed/#Exceptions
ACL Profile              Message VPN             Conn    Pub     Sub     Share
------------------------ ----------------------- ------- ------- ------- -------
analyst_group_d          blue                    y/1     y/1     y/1     y/0
  6. Assign the ACL profile to a client username:
    7. solace(configure)# client-username fred message-vpn blue
    solace(configure/client-username)# acl-profile analyst_group_d

Controlling Which Queues Clients May Publish To

The following example configures an ACL profile so that clients cannot publish to the queue myQueue (all other topics are allowed). The ACL profile is then assigned to a particular client username.

  1. Set the default action for publishing topic attempts:
    solace> enable
    solace# configure
    solace(configure)# acl-profile queuePublishAcl message-vpn blue
    solace(configure/acl-profile)# publish-topic
    solace(configure/acl-profile/publish-topic)# default-action allow
  2. Set exceptions to the default action for publishing topic attempts:
    solace(configure/acl-profile/publish-topic)# exception #P2P/QUE/myQueue
  3. Verify that the ACL profile is correct: 
    solace(configure/acl-profile/publish-topic)# show acl-profile queuePublishAcl message-vpn blue

                                                       Allowed/#Exceptions
ACL Profile              Message VPN             Conn    Pub     Sub     Share
------------------------ ----------------------- ------- ------- ------- -------
queuePublishAcl          blue                    y/0     y/1     y/0     y/0
  4. Assign the ACL profile to a client username: 
    solace(configure)# client-username fred message-vpn blue
solace(configure/client-username)# acl-profile queuePublishAcl

Viewing ACL Profiles

To view the current ACL profile configurations, enter the following show command:

solace> show acl-profile <name> [message-vpn <vpn-name>] [{detail [[client-connect] [publish-topic] [subscribe-topic] [subscribe-share-name]]} | {users}]

Where:

  • <name> is the name of the ACL profile. Entering the wildcard character * for the name displays all ACL profiles.
  • <vpn-name> is the name of the Message VPN to which the ACL profile belongs to.
  • detail specifies to show detailed ACL profile information.
  • client-connect specifies to show ACL profile information relating only to client connection ACLs.
  • publish-topic specifies to show ACL profile information relating only to topic publishing ACLs.
  • subscribe-topic specifies to show ACL profile information relating only to topic subscription ACLs.
  • subscribe-share-name specifies to show ACL profile information relating only to share subscription ACLs. 
solace> show acl-profile *

                                                       Allowed/#Exceptions
ACL Profile              Message VPN             Conn    Pub     Sub     Share
------------------------ ----------------------- ------- ------- ------- -------
#acl-profile             default                 y/0     y/0     y/0     y/0
default                  default                 y/0     y/0     y/0     y/0

Viewing ACL Logs

To view the ACL log for the last 1,000 most recent service denials for client connections, topic publishing topics, or topic subscriptions, enter the following show command:

solace> show log acl [client-connect | publish-topic | subscribe-topic] [client-username <username>] [message-vpn <vpn-name>] [wide]

Where:

  • client-connect specifies to show service denial logs relating only to client connection ACLs
  • publish-topic specifies to show service denial logs relating only to topic publishing ACLs
  • subscribe-topic specifies to show service denial logs relating only to topic subscription ACLs
  • <username> is the username of an existing client username account.
  • <vpn-name> is the name of an existing Message VPN to which the client username belongs to
  • wide specifies to show ACL log information in a wide screen computer display format (300+ character width)

Entering no command parameters displays service denial log information for all ACLs.

Clearing ACL Logs

To clear the ACL log either globally, or individually for client connections, topic publishing, or topic subscriptions, enter the following Privileged EXEC command:

solace# clear log acl [client-connect | publish-topic | subscribe-topic]

Where:

  • client-connect specifies to clear service denial logs relating only to client connection ACLs
  • publish-topic specifies to clear service denial logs relating only to topic publishing ACLs
  • subscribe-topic specifies to clear service denial logs relating only to topic subscription ACLs

Entering no command parameters clears service denial log information for all ACLs.

ACL Topic Matching Modes

Solace PubSub+ uses a special, internal #P2P/ prefix for some topic subscriptions. For example, a Solace messaging API automatically generates a unique topic subscription for each client, which enables messages to be sent directly to that client (for example, in request/reply scenarios). This client topic subscription is #P2P/v:<router-name>/<client-name>/ or #P2P/v:<router-name>/clientUsernameHash/<client-name>/. Solace PubSub+ also uses the #P2P/ prefix for non-durable topic endpoints and queues.

To ensure that these special topic subscriptions are always available, a Solace event broker exempts these special subscriptions when doing ACL enforcement. How this is done depends on the selected ACL topic matching mode. The following modes are available:

  • Enforce for Queues: Publish or subscribe ACL rules that allow clients to publish or subscribe to any topics starting with #P2P/v:*/ are exempt from ACL checking and are not permitted to be used as publish or subscribe exceptions. This is the default ACL topic matching rule introduced with software version 7.1. This mode is always used for Solace PubSub+ software event brokers.
  • Legacy: Publish or subscribe ACL rules that allow client to publish or subscribe to any topics starting with #P2P are exempt from ACL checking and cannot be used as publish or subscribe exceptions. This ACL topic matching rule was used prior to software version 7.1.

Solace recommends that you use the Enforce for Queues ACL topic matching mode because it provides greater control over which topics clients may not publish or subscribe to. For example, temporary queues and topic endpoints are also automatically assigned topics that use a #P2P/ prefix. However with the legacy ACL topic matching mode, ACL publish or subscribe rules could not be created to prevent clients from publishing or subscribing to those special topics.

Solace PubSub+ software event brokers can only use the Enforce for Queues ACL topic matching mode.

If you switch your event broker from Enforce for Queues ACL topic matching mode to the Legacy mode, some #P2P topics that previously bypassed ACL enforcement may be blocked. For these topics, you can add the appropriate topic exceptions to the ACL profile used by any affected clients (refer to Switching to Enforce for Queues Topic Matching Mode). However, if necessary, you can switch the base ACL topic matching mode to the less-restrictive Legacy ACL topic matching mode (refer to Setting an ACL Topic Matching Mode).

Switching to Enforce for Queues Topic Matching Mode

When an appliance is switched from the Legacy topic matching mode to the more restrictive Enforce for Queues ACL topic matching mode, it is possible that some topics that previously bypassed ACL enforcement will be blocked if the clients are using publisher or subscriber ACLs. The type of clients that may be affected, and the ACL configuration changes that are required to restore normal operations, are listed below:

  • Client applications publishing to durable queues by name

    Client applications that are publishing to durable queues by name that use a client username with restrictive publisher ACLs may be blocked. If this occurs, configure the publisher ACLs for the client usernames they use to allow the following topic:

    • for a particular queue: #P2P/QUE/<queue_name>, OR
    • for all queues: #P2P/QUE/>

  • Clients using temporary queues or topics

    Clients may be blocked from using temporary queues or topics if they use publisher or subscriber ACLs. In this case, configure both publisher and subscriber ACLs to allow the following topics:

    • #P2P/QTMP/>
    • #P2P/TTMP/>

  • Client applications performing cache requests

    Client applications that making cache requests that use a client username with restrictive publisher ACLs may no longer be able to send cache requests to PubSub+ Cache. If this occurs, configure the publisher ACLs for the client usernames they use to allow the following topic:

    • #P2P/CACHEINST/>

  • PubSub+ Cache Instances operational state

    A PubSub+ Cache Instance uses #P2P topics to communicate with the event broker. However, if the PubSub+ Cache Instance uses a client username with restrictive subscriber or publisher ACLs, the PubSub+ Cache Instance may not be able to communicate with the event broker, and will remain in the Not Available operational state. In this case, ACLs should be configured to allow the following topics:

    • publisher ACLs: #P2P/*/#client/CACHEMGR
    • subscriber ACLs: #P2P/CACHEINST/>

  • Clients sending SEMP requests over the message bus using a legacy format

    If client applications are sending SEMP requests over the message bus using the legacy format for show and clear commands, and the client has a restrictive publisher ACL, these requests may no longer be allowed. You should either reconfigure the client application to use the new format or configure their publisher ACLs to allow publishing to the following topic:

    • #P2P/*/#client/>

    For more information on legacy show and clear SEMP formats, refer to Legacy SEMP.

  • Direct Messaging clients listening in on queues by name

    Clients with restrictive subscriber ACLs that want to "snoop" named queues may be blocked from subscribing. In this case, configure the subscriber ACLs to allow the following topic:

    • for a particular queue: #P2P/QUE/<queue_name>, OR
    • for all queues: #P2P/QUE/>

Setting an ACL Topic Matching Mode

To configure an ACL topic matching mode for an appliance, enter the following CONFIG commands:

solace(configure)# hardware topic-routing
solace(configure/hardware/topic-routing)# acl-topic-matching-mode {legacy | enforce-for-queues}

Where:

legacy specifies to ignore publish or subscribe ACL rules for topics starting with #P2P/. This ACL topic matching rule was used prior to software version 7.1.

enforce-for-queues specifies to ignore publish or subscribe ACL rules for topics starting with #P2P/v:*/. This is the default ACL topic matching rule introduced with software version 7.1.

The no version of this command, no acl-topic-matching-mode, resets the base ACL topic matching rule to the default value of enforce-for-queues.

This command is only available for Solace PubSub+ appliances. Solace PubSub+ software event brokers only use the Enforce for Queues ACL topic matching mode.