# Configuring ACLs

In Qpid, ACLs specify which actions can be performed by each authenticated user. To enable the ACL <acl/> element is used within the <security/> element of the configuration XML. In the Java Broker, the ACL may be imposed broker wide or applied to individual virtual hosts. The <acl/> references a text file containing the ACL rules. By convention, this file should have a .acl extension.

## Enabling ACLs

To apply an ACL broker-wide, add the following to the config.xml (Assuming that conf has been set to a suitable location such as ${QPID_HOME}/etc)

          <broker>
            ...
            <security>
              ...
              <acl>${conf}/broker.acl</acl>
            </security>
          </broker>

To apply an ACL on a single virtualhost named test, add the following to the config.xml:

          <virtualhost>
            ...
            <name>test</name>
            <test>
              ...
              <security>
                <acl>${conf}/vhost_test.acl</acl>
              </security>
            </test>
          </virtualhost>

## Writing .acl files

The ACL file consists of a series of rules and group definitions. Each rule grants or denies specific rights to a user or group. Group definitions declare groups of users and serve to make the ACL file more concise.

Each ACL rule grants (or denies) a particular action on a object to a user. 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 a implict rule denying all operations to all users. It is as if each file ends with

    ACL DENY ALL ALL

To allow all operations, other than those controlled by earlier use

    ACL ALLOW ALL ALL

instead.

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, switch the DEBY-LOG to DENY for optimum performamce.

ACL rules are very powerful: it is possible to write very expressive rules permissioning every AMQP objects enumerating all object 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 (i.e. QUEUE) and apply consistently across the whole system.

## Syntax

ACL rules must follow this syntax:

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

GROUP definitions must follow this syntax:

         GROUP {group name} {username 1}..{username n} # Where username is a username, or a groupname.

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
          GROUP securegroup bob \
          alice # Another broker line

ACL Rules: 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

ACL Rules:action

`CONSUME` | Applied when subscriptions are created
`PUBLISH` | Applied on a per message basis on publish message transfers
`CREATE` | Applied when an object is created, such as bindings, queues, exchanges
`ACCESS` | Applied when an object is read or accessed
`BIND` | Applied when queues are bound to exchanges
`UNBIND` | Applied when queues are unbound from exchanges
`DELETE` | Applied when objects are deleted
`PURGE` | Applied when purge the contents of a queue
`UPDATE` | Applied when an object is updated

ACL Rules:object

`QUEUE` | A queue
`EXCHANGE` | An exchange
`VIRTUALHOST` | A virtualhost (Java Broker only)
`METHOD` | Management or agent or broker method (Java Broker only)
`BROKER` | The broker (not currently used in Java Broker)
`LINK` | A federation or inter-broker link (not currently used in Java Broker)

ACL Rules:property

`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
`passive` | Boolean. Indicates the presence of a passive flag
`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 (Java Broker only)
`schemapackage` | String. QMF schema package name (Not used in Java Broker)
`schemaclass` | String. QMF schema class name (Not used in Java Broker)

ACL rules:components (Java Broker only)

`UserManagement` | User maintainance; create/delete/view users, change passwords etc | permissionable at broker level only
`ConfigurationManagement` | Dynammically reload configuration from disk. | permissionable at broker level only
`LoggingManagement` | Dynammically control Qpid logging level | permissionable at broker level only
`ServerInformation` | Read-only information regarding the Qpid: version number etc | permissionable at broker level only
`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

## Worked Examples

Here are three example ACLs illustrating some common use-cases.

### 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 allow to connect for messaging.

            # Give operator permission to execute all JMX Methods
            ACL ALLOW operator ALL METHOD
            # Give operator permission to execute only read-only JMX Methods
            ACL ALLOW readonly ACCESS METHOD
            # Deny operator/readonly permission to perform messaging.
            ACL DENY operator ACCESS VIRTUALHOST
            ACL DENY readonly ACCESS VIRTUALHOST
            ...
            ... rules for other users
            ...
            # Explicitly deny all (log) to eveyone
            ACL DENY-LOG ALL ALL

### 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 a individual component and a group definition.

            # Create a group usermaint with members bob and alice
            GROUP usermaint bob alice
            # Give operator permission to execute all JMX Methods
            ACL ALLOW usermaint ALL METHOD component="UserManagement"
            ACL DENY ALL ALL METHOD component="UserManagement"
            ...
            ... rules for other users
            ...
            ACL DENY-LOG ALL ALL

### 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 response.  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