Managing Access Control Lists

Access Control List (ACL) Profiles are used to manage clients’ access to Message VPNs on a router. ACLs are assigned on a client username basis (refer to Configuring Client Username Accounts).

ACL profiles provide the following access controls to a given Message VPN:

  • client-connect—controls whether clients are allowed to connect to the Message VPN.
  • publish-topic—controls which topics clients are allowed to publish messages to on the Message VPN.
  • subscribe-topic—controls the topic subscriptions that consuming clients are allowed to use. A subscribe-topic ACL affects both messages that may be received through a topic subscription and those that may be received through binding to a durable endpoint that is assigned that topic subscription.

For each access control, you define a default action (allow or disallow connect, allow or disallow publishing to topics, and allow or disallow using topic subscriptions)and any exceptions to the default actions.

Once an ACL profile is configured, it can then be assigned to existing client usernames to apply the controls that it defines to clients using those client usernames. Refer to Assigning ACLs to Client Usernames.

Configuring Access Control Lists

  • 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>

  • 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 an existing Message VPN that the ACL belongs to.

Note:   

  • The no version of this command (no acl-profile <name>) deletes the given ACL profile from the Message VPN.
  • A maximum of 20,000 combined publish topic and subscribe topic exceptions permitted for all ACL profiles on the router.

For an ACL profile you can perform the following configuration tasks:

Configuring Client Connect Authorization

To configure the client connection access controls for the given ACL profile, enter the following CONFIG command:

solace(configure/acl-profile)# client-connect

You can then configure the default action and any exceptions for client connections:

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

    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 command:

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

Configuring the Topics Clients May Publish To

To configure the publishing topic access controls for the given ACL profile, enter the following CONFIG command:

solace(configure/acl-profile)# publish-topic

You can then configure the default action and any exceptions for publishing topics:

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

    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.

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

    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.

    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 topic syntax or MQTT syntax, if the mqtt parameter is explicitly entered).

    Note:  For information on topic syntax and considerations that should made for the Solace Message Platform to handle SMF and MQTT topics similarly, refer to Topic Support and Syntax.

Note:  The no version of this command (no exceptions) removes any give topic publish exceptions.

Tip:  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>.

Configuring the Topics Clients May Subscribe To

To configure the topic subscription access controls for the given ACL profile, enter the following CONFIG command:

solace(configure/acl-profile)# subscribe-topic

You can then configure the default action and any exceptions for subscribing to topics:

  • To set whether the default action will be to allow clients to subscribe to topics or not, enter the following CONFIG command:

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

    Where:

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

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

  • To set the exceptions to the default action for topic subscriptions, enter the following CONFIG command:

    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.

    mqtt indicates that the topic to be excepted is an MQTT topic.

    <exception-list> is the topic to be excepted. This topic subscription should be constructed with the appropriate topic syntax (either SMF topic syntax or MQTT syntax, if the mqtt parameter is explicitly entered).

    Note:   For information on topic syntax and considerations that should made for the Solace Message Platform to handle SMF and MQTT topics similarly, refer to Topic Support and Syntax.

ACL Topic Matching Mode

The Solace Messaging Platform 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>/. The Solace Messaging Platform also uses the #P2P/ prefix for non-durable topic endpoints and queues.

To ensure that these special topic subscriptions are always available, a Solace router bypasses these special subscriptions when doing ACL enforcement. Exactly how this is done depends on the current ACL topic matching mode. The following modes are available:

  • Enforce for Queues—publish or subscribe ACL rules that allow client 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 SolOS 7.1. This mode is always used for Solace VMRs.
  • 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 SolOS 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.

Note:  Solace VMRs can only use the Enforce for Queues ACL topic matching mode.

If you switch your router 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 SolCache. If this occurs, configure the publisher ACLs for the client usernames they use to allow the following topic:
    • #P2P/CACHEINST/>
  • SolCache Instances operational state—A SolCache Instance uses #P2P topics to communicate with the router. However, if the SolCache Instance uses a client username with restrictive subscriber or publisher ACLs, the SolCache Instance may not be able to communicate with the router, 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 a Solace 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 SolOS 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 SolOS 7.1.

Note:   

  • 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 appliances. Solace VMRs only use the Enforce for Queues ACL topic matching mode.

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

Note:   

  • A client username must be shutdown before an ACL profile can be assigned to it.
  • The no version of this command (no acl-profile) resets the assigned profile for the client username account back to the profile named default.

Access Control List Configuration Examples

This section shows the basic procedural steps that are required configure ACLs on a router. 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 router, 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)#

  3. Set the default action for client connection access attempts:

    solace(configure/acl-profile)# client-connect

    solace(configure/acl-profile/client-connect)# default-action allow

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

  5. Assign the ACL profile to a given client username:

    solace(configure)# client-username joe message-vpn blue

    solace(configure/client-username)# acl-profile in_field

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 topic “animals/domestic/cats” (all other topics are allowed)
  • Clients cannot use a subscription to the topic “animals/domestic/dogs (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

  3. Set exceptions to the default action for publishing topic attempts:
  4. solace(configure/acl-profile/publish-topic)# exception animals/domestic/cats

  5. Set the default action for topic subscription attempts:
  6. solace(configure/acl-profile)# subscribe-topic

    solace(configure/acl-profile/subscribe-topic)# default-action allow

  7. Set exceptions to the default action for topic subscription attempts:
  8. solace(configure/acl-profile/subscribe-topic)# exception animals/domestic/dogs

  9. Verify that the ACL profile is correct:
  10. solace> show acl-profile analyst_group_d message-vpn blue

     

                                                         Allowed/#Exceptions

    ACL Profile              Message VPN           Connect  Publish  Subscribe

    ------------------------ --------------------- -------  -------- ---------

    analyst_group_d          blue                  yes/0    yes/1    yes/1

  11. Assign the ACL profile to a client username:
  12. 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 a topic-acess 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. Verify that the router is configured to use Enforce for Queues ACL topic matching mode:
  2. solace> show hardware details

    ...

      Slot 1/3: Topic Routing Blade

        Product #:               TRB-000000-02-A

        Serial #:                S003001351

        ACL Topic Matching Mode: enforce-for-queues (ignore #P2P/v:* and #P2P/    v:*/>)

    ...

  3. Set the default action for publishing topic attempts:
  4. solace> enable

    soalce# configure

    solace(configure)# acl-profile queuePublishAcl message-vpn blue

    solace(configure/acl-profile)# publish-topic

    solace(configure/acl-profile/publish-topic)# default-action allow

  5. Set exceptions to the default action for publishing topic attempts:
  6. solace(configure/acl-profile/publish-topic)# exception #P2P/QUE/myQueue

  7. Verify that the ACL profile correct:
  8. solace(configure/acl-profile/publish-topic)# show acl-profile queuePublishAcl message-vpn blue

                                                         Allowed/#Exceptions

    ACL Profile              Message VPN           Connect  Publish  Subscribe

    ------------------------ --------------------- -------  -------- ---------

    queuePublishAcl          blue                  yes/0    yes/1    yes/0

  9. Assign the ACL profile to a client username:
  10. solace(configure)# client-username fred message-vpn blue

    solace(configure/client-username)# acl-profile queuePublishAcl

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)

Note:  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

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

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