Menu Search

8.3. Access Control Providers

The Access Control Provider governs the actions that a user may perform.

There are two points within the hierarchy that enforce access control: the Broker itself and at each Virtual Host. When an access decision needs to be made, the nearest control point configured with a provider is consulted for a decision. The example, when making a decision about the ability to say, consume from, a Queue, if the Virtual Host is configured with Access Control Provider it is consulted. Unless a decision is made, the decision is delegated to the Access Control Provider configured at the Broker.

Access Control Providers are configured with a list of ACL rules. The rules determine to which objects the user has access and what actions the user may perform on those objects. Rules are ordered and are considered top to bottom. The first matching rule makes the access decision.

ACL rules may be written in terms of user or group names. A rule written in terms of a group name applies to the user if he is a member of that group. Groups information is obtained from the Authentication Providers and Group Providers. Writing ACL in terms of groups is recommended.

The Access Control Providers can be configured using REST Management interfaces and Web Management Console.

8.3.1. Types

There are currently two types of Access Control Provider implementing ACL rules.

  • RulesBased - a provider that stores the rules-set within the Broker's or VirtualHost's configuration. When used with HA, the Virtualhost rules automatically propagated to all nodes participating within the HA group.

  • ACLFile - an older provider that references an externally provided ACL file (or data url). This provider is deprecated.

8.3.2.  ACL Rules

An ACL rule-set is an ordered list of ACL rules.

An ACL rule comprises matching criteria that determines if a rule applies to a situation and a decision outcome. The rule produces an outcome only if the all matching criteria are satisfied.

Matching criteria is composed of an ACL object type (e.g. QUEUE), an ACL action (e.g. UPDATE) and other properties that further refine if a match is made. These properties restrict the match based on additional criteria such as name or IP address. ACL Object type ALL matches any object. Likewise ACL Action ALL matches any action.

Let's look at some examples.

      ACL ALLOW alice CREATE QUEUE              # Grants alice permission to create all queues.
      ACL DENY bob CREATE QUEUE name="myqueue"  # Denies bob permission to create a queue called "myqueue"
    

As discussed, the ACL rule-set is considered in order with the first matching rule taking precedence over all those that follow. In the following example, if the user bob tries to create an exchange "myexch", the action will be allowed by the first rule. The second rule will never be considered.

      ACL ALLOW bob ALL EXCHANGE
      ACL DENY bob CREATE EXCHANGE name="myexch"  # Dead rule
    

If the desire is to allow bob to create all exchanges except "myexch", order of the rules must be reversed:

      ACL DENY bob CREATE EXCHANGE name="myexch"
      ACL ALLOW bob ALL EXCHANGE
    

If a rule-set fails to make a decision, the result is configurable. By default, the RuleBased provider defers the decision allowing another provider further up the hierarchy to make a decision (i.e. allowing the VirtualHost control point to delegate to the Broker). In the case of the ACLFile provider, by default, its rule-set implicit have a rule denying all operations to all users. It is as if the rule-set ends with ACL DENY ALL ALL. If no access control provider makes a decision the default is to deny the action.

When writing a new ACL, a useful approach is to begin with an rule-set containing only

ACL DENY-LOG ALL ALL

at the Broker control point which will cause the Broker to deny all operations with details of the denial logged. Build up the ACL rule by rule, gradually working through the use-cases of your system. Once the ACL is complete, consider switching the DENY-LOG actions to DENY.

ACL rules are very powerful: it is possible to write very granular rules specifying many broker objects and their properties. Most projects probably won't need this degree of flexibility. A reasonable approach is to choose to apply permissions at a certain level of abstractions and apply them consistently across the whole system.

8.3.3.  Syntax

ACL rules follow this syntax:

     ACL {permission} {<group-name>|<user-name>|ALL} {action|ALL} [object|ALL] [property="<property-value>"]
    

Comments may be introduced with the hash (#) character and are ignored. Long lines can be broken with the slash (\) character.

      # A comment
      ACL ALLOW admin CREATE ALL # Also a comment
      ACL DENY guest \
      ALL ALL   # A broken line
    

Table 8.1. List of ACL permission

ALLOW

Allow the action

ALLOW-LOG

Allow the action and log the action in the log

DENY

Deny the action

DENY-LOG

Deny the action and log the action in the log


Table 8.2. List of ACL actions

Action

Description

Supported object types

Supported properties

CONSUME

Applied when subscriptions are created

QUEUE

name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name

PUBLISH

Applied on a per message basis on publish message transfers

EXCHANGE

name, routingkey, virtualhost_name

CREATE

Applied when an object is created, such as bindings, queues, exchanges

VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP

see properties on the corresponding object type

ACCESS

Applied when a connection is made for messaging or management

VIRTUALHOST, MANAGEMENT

name (for VIRTUALHOST only)

BIND

Applied when queues are bound to exchanges

EXCHANGE

name, routingKey, queue_name, virtualhost_name, temporary, durable

UNBIND

Applied when queues are unbound from exchanges

EXCHANGE

name, routingKey, queue_name, virtualhost_name, temporary, durable

DELETE

Applied when objects are deleted

VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP

see properties on the corresponding object type

PURGE

Applied when the contents of a queue is purged

QUEUE

UPDATE

Applied when an object is updated

VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP

see EXCHANGE and QUEUE properties

CONFIGURE

Applied when a Broker/Port/Authentication Provider/Access Control Provider/BrokerLogger is created/update/deleted.

BROKER

ACCESS_LOGS

Allows/denies the specific user to download log file(s).

BROKER, VIRTUALHOST

name (for VIRTUALHOST only)

SHUTDOWN

Allows/denies the specific user to shutdown the Broker.

BROKER

INVOKE

Allows/denies the specific user to invoke the named operation.

BROKER, VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP

method_name, name and virtualhost_name


Table 8.3. List of ACL objects

Object type

Description

Supported actions

Supported properties

Allowed in Virtualhost ACLs?

VIRTUALHOSTNODE

A virtualhostnode or remote replication node

ALL, CREATE, UPDATE, DELETE, INVOKE

name

No

VIRTUALHOST

A virtualhost

ALL, CREATE, UPDATE, DELETE, ACCESS, ACCESS_LOGS, INVOKE

name, connection_limit, connection_frequency_limit

No

QUEUE

A queue

ALL, CREATE, DELETE, PURGE, CONSUME, UPDATE, INVOKE

name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name

Yes

EXCHANGE

An exchange

ALL, ACCESS, CREATE, DELETE, BIND, UNBIND, PUBLISH, UPDATE, INVOKE

name, autodelete, temporary, durable, type, virtualhost_name, queue_name(only for BIND and UNBIND), routingkey(only for BIND and UNBIND, PUBLISH)

Yes

USER

A user

ALL, CREATE, DELETE, UPDATE, INVOKE

name

No

GROUP

A group

ALL, CREATE, DELETE, UPDATE, INVOKE

name

No

BROKER

The broker

ALL, CONFIGURE, ACCESS_LOGS, INVOKE

No


Table 8.4. List of ACL properties

name

String. Object name, such as a queue name or exchange name.

durable

Boolean. Indicates the object is durable

routingkey

String. Specifies routing key

autodelete

Boolean. Indicates whether or not the object gets deleted when the connection is closed

exclusive

Boolean. Indicates the presence of an exclusive flag

temporary

Boolean. Indicates the presence of an temporary flag

type

String. Type of object, such as topic, or fanout

alternate

String. Name of the alternate exchange

queue_name

String. Name of the queue (used only when the object is EXCHANGE for BIND and UNBIND actions)

component

String. component name

from_network

Comma-separated strings representing IPv4 address ranges.

Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.

The rule matches if any of the address ranges match the IPv4 address of the messaging client. The address ranges are specified using either Classless Inter-Domain Routing notation (e.g. 192.168.1.0/24; see RFC 4632) or wildcards (e.g. 192.169.1.*).

from_hostname

Comma-separated strings representing hostnames, specified using Perl-style regular expressions, e.g. .*\.example\.company\.com

Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.

The rule matches if any of the patterns match the hostname of the messaging client.

To look up the client's hostname, Qpid uses Java's DNS support, which internally caches its results.

You can modify the time-to-live of cached results using the *.ttl properties described on the Java Networking Properties page.

For example, you can either set system property sun.net.inetaddr.ttl from the command line (e.g. export QPID_OPTS="-Dsun.net.inetaddr.ttl=0") or networkaddress.cache.ttl in $JAVA_HOME/lib/security/java.security. The latter is preferred because it is JVM vendor-independent.

connection_limit

A maximum number of connections the users belonging to the given identity can establish to the Virtual Host

Intended for use in ACCESS VIRTUALHOST rules to restrict the number of connections which can be made by the messaging user.

connection_frequency_limit

A maximum number of connections the user belonging to the given identity can establish to the Virtual Host within pre-defined period of time, which is 1 minute by default.

Intended for use in ACCESS VIRTUALHOST rules to restrict the frequency of connections which can be made by the messaging user.

If required, the frequency period can be changed using context variable qpid.virtualhost.connectionFrequencyPeriodInMillis. As name suggests, its value needs to be specified in milliseconds. Setting it to zero or negative value turns off the connection_frequency evaluation.

virtualhost_name

String. A name of virtual host to which the rule is applied.

method_name

String. The name of the method. A trailing wildcard (*) is permitted. Used with INVOKE ACL action.

attribute_names

Specifies attribute name criteria. Used by UPDATE ACL actions only. Rules with this criteria will match if and only if the set of attributes being updated Comma separated list of attribute names . This criteria will match if all attributes included within the update appear in the set described by attribute_names.


8.3.4.  Worked Examples

Here are some example ACLs illustrating common use cases.

8.3.4.1.  Worked example 1 - Management rights

Suppose you wish to permission two users: a user operator must be able to perform all Management operations, and a user 'readonly' must be enable to perform only read-only actions. Neither operator nor readonly should be allowed to connect clients for messaging.

Example 8.1. Worked example 1 - Management rights

          # Deny operator/readonly permission to connect for messaging.
          ACL DENY-LOG operator ACCESS VIRTUALHOST
          ACL DENY-LOG readonly ACCESS VIRTUALHOST
          # Give operator permission to perfom all actions
          ACL ALLOW operator ALL ALL
          # Give readonly access permission to virtualhost. (Read permission for all objects implicit)
          ACL ALLOW readonly ACCESS MANAGEMENT
          ...
          ... rules for other users
          ...
        

8.3.4.2.  Resource restrictions

The number of Virtual Host connections and frequency of connections can be restricted with ACCESS rule.

Example 8.2. Restricting user connections to virtual host

          ACL ALLOW-LOG guest ACCESS VIRTUALHOST connection_limit=1
          ACL ALLOW-LOG messaging-users ACCESS VIRTUALHOST connection_frequency_limit=100
          ...
        

In the example above the maximum number of connections allowed to establish to the Virtual Host by user guest is set to 1. The maximum connection frequency for every user belonging to the user group messaging-users is set to 100 (per minute, by default).

8.3.4.3.  Worked example 2 - Simple Messaging

Suppose you wish to permission a system for application messaging. User publisher needs permission to publish to appqueue and consumer needs permission to consume from the same queue object. We also want operator to be able to inspect messages and delete messages in case of the need to intervene. This example assumes that the queue exists on the Broker.

We use this ACL to illustrate separate Broker and Virtualhost access control providers.

The following ACL rules are given to the Broker.

Example 8.3. Worked example 2 - Simple Messaging - Broker ACL rules

# This gives the operate permission to delete messages on all queues on all virtualhost
ACL ALLOW operator ACCESS MANAGEMENT
ACL ALLOW operator INVOKE QUEUE method_name="deleteMessages"
ACL ALLOW operator INVOKE QUEUE method_name="getMessage*"
        

And the following ACL rule-set is applied to the Virtualhost. The default outcome of the Access Control Provider must be DEFERED. This means that if a request for access is made for which there are no matching rules, the decision will be deferred to the Broker so it can make a decision instead.

Example 8.4. Worked example 2 - Simple Messaging - Virtualhost ACL rules

# Configure the rule-set to DEFER decisions that have no matching rules.
CONFIG DEFAULTDEFER=TRUE
# Allow client and server to connect to the virtual host.
ACL ALLOW publisher ACCESS VIRTUALHOST
ACL ALLOW consumer ACCESS VIRTUALHOST

ACL ALLOW publisher PUBLISH EXCHANGE name="" routingKey="appqueue"
ACL ALLOW consumer CONSUME QUEUE name="appqueue"
# In some addressing configurations, the Qpid JMS AMQP 0-x client, will declare the queue as a side effect of creating the consumer.
# The following line allows for this.  For the Qpid JMS AMQP 1.0 client, this is not required.
ACL ALLOW consumer CREATE QUEUE name="appqueue"
        

8.3.4.4.  Worked example 3 - firewall-like access control

This example illustrates how to set up an ACL that restricts the IP addresses and hostnames of messaging clients that can access a virtual host.

Example 8.5. Worked example 3 - firewall-like access control

          ################
          # Hostname rules
          ################

          # Allow messaging clients from company1.com and company1.co.uk to connect
          ACL ALLOW all ACCESS VIRTUALHOST from_hostname=".*\.company1\.com,.*\.company1\.co\.uk"

          # Deny messaging clients from hosts within the dev subdomain
          ACL DENY-LOG all ACCESS VIRTUALHOST from_hostname=".*\.dev\.company1\.com"

          ##################
          # IP address rules
          ##################

          # Deny access to all users in the IP ranges 192.168.1.0-192.168.1.255 and 192.168.2.0-192.168.2.255,
          # using the notation specified in RFC 4632, "Classless Inter-domain Routing (CIDR)"
          ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
          from_network="192.168.1.0/24,192.168.2.0/24"

          # Deny access to all users in the IP ranges 192.169.1.0-192.169.1.255 and 192.169.2.0-192.169.2.255,
          # using wildcard notation.
          ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
          from_network="192.169.1.*,192.169.2.*"