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.
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.
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.
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 |
| temporary | Boolean. Indicates the presence of an |
| 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
|
Here are some example ACLs illustrating common use cases.
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
...
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).
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"
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.*"
Apache Qpid, Messaging built on AMQP; Copyright © 2015 The Apache Software Foundation; Licensed under the Apache License, Version 2.0; Apache Qpid, Qpid, Qpid Proton, Proton, Apache, the Apache feather logo, and the Apache Qpid project logo are trademarks of The Apache Software Foundation; All other marks mentioned may be trademarks or registered trademarks of their respective owners