Configuring Access Control Lists

Access Control List (ACL) profiles are used to manage whether clients may connect to Message VPNs and which topics clients are allowed to publish to and subscribe to on that Message VPN. Each of these three access controls requires a defined default action (allow or disallow connect, allow or disallow publishing to topics, and allow or disallow using topic subscriptions), and you can configure explicit exceptions to those default actions.

ACL profiles are assigned on a client username basis (refer to Configuring Client Usernames). 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.

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

You can perform the following configuration tasks for an ACL profile:

Configuring Client Connect Authorization

To configure the client connection access controls for the given ACL profile, do the following:

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

Configuring Topic Publish Permissions

To configure the publishing topic access controls for the given ACL profile, do the following:

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

  • To set any 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.

    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). For Solace VMRs Version 8.2.x or greater, the following substitution variables can be used in a topic level of an ACL topic exception:

    • $client-id—For this variable, the router 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 router 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 router will substitute the unique 8-byte long “client-username-hash” that the router generates for a client based on the client username the client provided or was etrieved 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 router creates for the client so that it can use Direct Request/Reply messaging.

    Note that substitution variables are not currently available for Solace appliances. For more information on how substitution values can be used in topic exceptions, see Using Substitution Variables in Topic Exceptions.

Note:   

  • The no version of this command (no exceptions) removes any give topic publish exceptions.
  • 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.
  • Published topics of the form #P2P/v:*/>, which are used for clientsʼ Direct Request/Reply messaging, are exempt from publish-topic ACL checks. However, all subscriptions, including those of the form #P2P/v:*/>, are subject to subscribe-topic ACL checks.
  • For information on topic syntax and considerations that should made for the Solace Message Platform to handle SMF and MQTT topics similarly, see Topic Support and Syntax.

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 Topic Subscribe Permissions

To configure the topic subscription access controls for the given ACL profile, do the following:

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

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

    Tip:  If you want to ensure that the 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 router 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.

    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 topic syntax or MQTT syntax, if the mqtt parameter is explicitly entered). For Solace VMRs Version 8.2.x or greater, the following substitution variables can be used in a topic level of an ACL topic exception:

    • $client-id—For this variable, the router 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 router 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 router will substitute the unique 8-byte long “client-username-hash” that the router 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 router creates for the client so that it can use Direct Request/Reply messaging.

    Note that substitution variables are not currently available for Solace appliances. For more information on how substitution values can be used in topic exceptions, see Using Substitution Variables in Topic Exceptions.

    Note:   

    • The no version of this command (no exceptions) removes any give topic subscribe exceptions.
    • 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.
    • For information on topic syntax and considerations that should made for the Solace Message Platform to handle SMF and MQTT topics similarly, see Topic Support and 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

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.

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

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.

ACL Topic Matching Modes

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>/ or #P2P/v:<router‑name>/clientUsernameHash/<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 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 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.