Resources

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.

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.

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

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.

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.

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

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.

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.

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

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.