Menu Search

11.3. Access Control Lists

In Qpid, Access Control Lists (ACLs) specify which actions can be performed by each authenticated user. To enable, an Access Control Provider needs to be configured on the Broker. The Access Control Provider of type "AclFile" uses local file to specify the ACL rules. By convention, this file should have a .acl extension.

A Group Provider can be configured with ACL to define the user groups which can be used in ACL to determine the ACL rules applicable to the entire group. The configuration details for the Group Providers are described in Section 11.2, “Group Providers”. On creation of ACL Provider with group rules, the Group Provider should be added first. Otherwise, if the individual ACL rules are not defined for the logged principal the following invocation of management operations could be denied due to absence of the required groups.

Only one Access Control Provider can be used by the Broker. If several Access Control Providers are configured on Broker level only one of them will be used (the latest one).

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

The following ACL Provider managing operations are available from Web Management Console:

  • A new ACL Provider can be added by clicking onto "Add Access Control Provider" on the Broker tab.

  • An ACL Provider details can be viewed on the Access Control Provider tab. The tab is shown after clicking onto ACL Provider name in the Broker object tree or after clicking onto ACL Provider row in ACL Providers grid on the Broker tab.

  • An existing ACL Provider can be deleted by clicking onto buttons "Delete Access Control Provider" on the Broker tab or Access Control Provider tab.

11.3.1.  Writing .acl files

The ACL file consists of a series of rules associating behaviour for a user or group. Use of groups can serve to make the ACL file more concise. See Configuring Group Providers for more information on defining groups.

Each ACL rule grants or denies a particular action on an object to a user/group. The rule may be augmented with one or more properties, restricting the rule's applicability.

      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"
    

The ACL is considered in strict line 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 operation 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
    

All ACL files end with an implict rule denying all operations to all users. It is as if each file ends with

ACL DENY ALL ALL 

If instead you wish to allow all operations other than those controlled by earlier rules, add

ACL ALLOW ALL ALL

to the bottom of the ACL file.

When writing a new ACL, a good approach is to begin with an .acl file containing only

ACL DENY-LOG ALL ALL

which will cause the Broker to deny all operations with details of the denial logged to the Qpid log file. 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 to improve performamce and reduce log noise.

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 abstraction (e.g. QUEUE) and apply them consistently across the whole system.

Note

Some rules can be restricted to the virtual host if property virtualhost_name is specified.

Example 11.1. Restrict rules to specific virtual hosts

      ACL ALLOW bob CREATE QUEUE virtualhost_name="test"
      ACL ALLOW bob ALL EXCHANGE virtualhost_name="prod"
    


In the example above the first rule allows user "bob" to create queues on virtual host "test" only. The second rule allows user "bob" any action with exchanges on virtual host "prod".

11.3.2.  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 11.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 11.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, immediate, virtualhost_name

CREATE

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

EXCHANGE, QUEUE, USER, GROUP

see properties on the corresponding object type

ACCESS

Applied when an object is read or accessed

VIRTUALHOST, MANAGEMENT

name (for VIRTUALHOST only)

BIND

Applied when queues are bound to exchanges

EXCHANGE

name, routingKey, queuename, virtualhost_name, temporary, durable

UNBIND

Applied when queues are unbound from exchanges

EXCHANGE

name, routingKey, queuename, virtualhost_name, temporary, durable

DELETE

Applied when objects are deleted

EXCHANGE, QUEUE, USER, GROUP

see properties on the corresponding object type

PURGE

Applied when purge the contents of a queue

QUEUE

UPDATE

Applied when an object is updated

EXCHANGE, QUEUE, USER, GROUP

see EXCHANGE and QUEUE properties

CONFIGURE

Applied when an object is configured via REST management interfaces.

BROKER

ACCESS_LOGS

Allows/denies to the specific user an operation to download broker log file(s) over REST interfaces

BROKER


Table 11.3. List of ACL objects

Object type

Description

Supported actions

Supported properties

VIRTUALHOST

A virtualhost

ALL, ACCESS

name

MANAGEMENT

Management - for web and JMX

ALL, ACCESS

QUEUE

A queue

ALL, CREATE, DELETE, PURGE, CONSUME, UPDATE

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

EXCHANGE

An exchange

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

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

USER

A user

ALL, CREATE, DELETE, UPDATE

name

GROUP

A group

ALL, CREATE, DELETE, UPDATE

name

METHOD

Management or agent or broker method

ALL, ACCESS, UPDATE

name, component, virtualhost_name

BROKER

The broker

ALL, CONFIGURE, ACCESS_LOGS


Table 11.4. List of ACL properties

name

String. Object name, such as a queue name, exchange name or JMX method 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, fanout, or xml

alternate

String. Name of the alternate exchange

queuename

String. Name of the queue (used only when the object is something other than queue

component

String. JMX 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.

virtualhost_name

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

immediate

Boolean. A property can be used to restrict PUBLISH action to publishing only messages with given immediate flag.


Table 11.5. List of ACL JMX Components

UserManagement

User maintainance; create/delete/view users, change passwords etc

ConfigurationManagement

Dynammically reload configuration from disk.

LoggingManagement

Dynammically control Qpid logging level

ServerInformation

Read-only information regarding the Qpid: version number etc

VirtualHost.Queue

Queue maintainance; copy/move/purge/view etc

VirtualHost.Exchange

Exchange maintenance; bind/unbind queues to exchanges

VirtualHost.VirtualHost

Virtual host maintainace; create/delete exchanges, queues etc


11.3.3.  Worked Examples

Here are some example ACLs illustrating common use cases. In addition, note that the Java broker provides a complete example ACL file, located at etc/broker_example.acl.

11.3.3.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 functions. Neither 'operator' nor 'readonly' should be allowed to connect clients for messaging.

# Deny (loggged) operator/readonly permission to connect messaging clients.
ACL DENY-LOG operator ACCESS VIRTUALHOST
ACL DENY-LOG readonly ACCESS VIRTUALHOST
# Give operator permission to perfom all other actions
ACL ALLOW operator ALL ALL
# Give readonly permission to execute only read-only actions
ACL ALLOW readonly ACCESS ALL
...
... rules for other users
...
# Explicitly deny all (log) to eveyone
ACL DENY-LOG ALL ALL
      

11.3.3.2.  Worked example 2 - User maintainer group

Suppose you wish to restrict User Management operations to users belonging to a group 'usermaint'. No other user is allowed to perform user maintainence This example illustrates the permissioning of an individual component.

# Give usermaint access to management and permission to execute all JMX Methods on the
# UserManagement MBean and perform all actions for USER objects
ACL ALLOW usermaint ACCESS MANAGEMENT
ACL ALLOW usermaint ALL METHOD component="UserManagement"
ACL ALLOW usermaint ALL USER
ACL DENY ALL ALL METHOD component="UserManagement"
ACL DENY ALL ALL USER
...
... rules for other users
...
ACL DENY-LOG ALL ALL
      

11.3.3.3.  Worked example 3 - Request/Response messaging

Suppose you wish to permission a system using a request/response paradigm. Two users: 'client' publishes requests; 'server' consumes the requests and generates a response. This example illustrates the permissioning of AMQP exchanges and queues.

# Allow client and server to connect to the virtual host.
ACL ALLOW client ACCESS VIRTUALHOST
ACL ALLOW server ACCESS VIRTUALHOST

# Client side
# Allow the 'client' user to publish requests to the request queue. As is the norm for the request/response paradigm, the client
# is required to create a temporary queue on which the server will respond.  Consequently, there are rules to allow the creation
# of the temporary queues and consumption of messages from it.
ACL ALLOW client CREATE QUEUE temporary="true"
ACL ALLOW client CONSUME QUEUE temporary="true"
ACL ALLOW client DELETE QUEUE temporary="true"
ACL ALLOW client BIND EXCHANGE name="amq.direct" temporary="true"
ACL ALLOW client UNBIND EXCHANGE name="amq.direct" temporary="true"
ACL ALLOW client PUBLISH EXCHANGE name="amq.direct" routingKey="example.RequestQueue"

# Server side
# Allow the 'server' user to consume from the request queue and publish a response to the temporary response queue created by
# client.  We also allow the server to create the request queue.
ACL ALLOW server CREATE QUEUE name="example.RequestQueue"
ACL ALLOW server CONSUME QUEUE name="example.RequestQueue"
ACL ALLOW server BIND EXCHANGE
ACL ALLOW server PUBLISH EXCHANGE name="amq.direct" routingKey="TempQueue*"

ACL DENY-LOG all all
      

11.3.3.4.  Worked example 4 - 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.

################
# 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.*"

ACL DENY-LOG all all
      

11.3.3.5.  Worked example 5 - REST management ACL example

This example illustrates how to set up an ACL that restricts usage of REST management interfaces.

# allow to the users from webadmins group to change broker model
# this rule allows adding/removing/editing of Broker level objects:
# Broker, Virtual Host, Group Provider, Authentication Provider, Port, Access Control Provider etc
ACL ALLOW-LOG webadmins CONFIGURE BROKER

# allow to the users from webadmins group to perform
# create/update/delete on Virtual Host children
ACL ALLOW-LOG webadmins CREATE QUEUE
ACL ALLOW-LOG webadmins UPDATE QUEUE
ACL ALLOW-LOG webadmins DELETE QUEUE
ACL ALLOW-LOG webadmins PURGE  QUEUE
ACL ALLOW-LOG webadmins CREATE EXCHANGE
ACL ALLOW-LOG webadmins DELETE EXCHANGE
ACL ALLOW-LOG webadmins BIND   EXCHANGE
ACL ALLOW-LOG webadmins UNBIND EXCHANGE

# allow to the users from webadmins group to create/update/delete groups on Group Providers
ACL ALLOW-LOG webadmins CREATE GROUP
ACL ALLOW-LOG webadmins DELETE GROUP
ACL ALLOW-LOG webadmins UPDATE GROUP

# allow to the users from webadmins group to create/update/delete users for Authentication Providers
ACL ALLOW-LOG webadmins CREATE USER
ACL ALLOW-LOG webadmins DELETE USER
ACL ALLOW-LOG webadmins UPDATE USER

# allow to the users from webadmins group to move, copy and delete messagaes
# using REST management interfaces
ACL ALLOW-LOG webadmins UPDATE METHOD

# at the moment only the following UPDATE METHOD rules are supported by web management console
#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="moveMessages"
#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="copyMessages"
#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="deleteMessages"

ACL DENY-LOG all all