An access control properties file (ACL file) contains rules that specify the operations that users and groups of users can perform. You edit the ACL file to restrict operations to certain users and groups. You can use a different ACL file for each broker instance.
The ACL file is used whether user information is placed in a flat-file user repository or in an LDAP user repository. A broker checks its ACL file when a client application performs one of the following operations:
Creates a connection
Creates a producer
Creates a consumer
Browses a queue
The broker checks the ACL file to determine whether the user that generated the request, or a group to which the user belongs, is authorized to perform the operation.
If you edit an ACL file, the new settings take effect the next time the broker checks the file to verify authorization. You need not restart the broker after editing the file.
The ACL file is instance specific. Each time you start a broker instance, a default file named accesscontrol.properties is created in the instance directory. The path to the file has the following format (see Appendix A, Platform-Specific Locations of Message QueueTM Data):
…/instances/brokerInstanceName/etc/accesscontrol.properties
The ACL file is formatted like a Java properties file. It starts by defining the version of the file and then specifies access control rules in three sections:
Connection access control
Physical destination access control
Physical destination auto-create access control
The version property defines the version of the ACL properties file; you may not change this entry.
version=JMQFileAccessControlModel/100
The three sections of the ACL file that specify access control are described below, following a description of the basic syntax of access rules and an explanation of how permissions are calculated.
In the ACL properties file, access control defines what access specific users or groups have to protected resources like physical destinations and connection services. Access control is expressed by a rule or set of rules, with each rule presented as a Java property:
The basic syntax of these rules is as follows:
resourceType.resourceVariant .operation.access. principalType=principals
Table 7–3 describes the elements of syntax rules.
Table 7–3 Syntactic Elements of Access Rules
Element |
Description |
---|---|
resourceType |
One of the following: connection, queue or topic. |
resourceVariant |
An instance of the type specified by resourceType. For example, myQueue. The wild card character (*) may be used to mean all connection service types or all physical destinations. |
operation |
Value depends on the kind of access rule being formulated. |
access |
One of the following: allow or deny. |
principalType |
One of the following: user or group. For more information, see Groups. |
principals |
Who may have the access specified on the left-hand side of the rule. This may be an individual user or a list of users (comma delimited) if the principalType is user; it may be a single group or a list of groups (comma delimited list) if the principalType is group. The wild card character (*) may be used to represent all users or all groups. |
Here are some examples of access rules:
The following rule means that all users may send a message to the queue named q1.
queue.q1.produce.allow.user=*
The following rule means that any user may send messages to any queue.
queue.*.produce.allow.user=*
To specify non-ASCII user, group, or destination names, use Unicode escape (\\uXXXX) notation. If you have edited and saved the ACL file with these names in a non-ASCII encoding, you can convert the file to ASCII with the Java native2ascii tool. For more detailed information, see
http://java.sun.com/j2se/1.4/docs/guide/intl/faq.html
When there are multiple access rules in the file, permissions are computed as follows:
Specific access rules override general access rules. After applying the following two rules, all users can send to all queues, but Bob cannot send to tq1.
queue.*.produce.allow.user=* queue.tq1.produce.deny.user=Bob
Access given to an explicit principal overrides access given to a * principal. The following rules deny Bob the right to produce messages to tq1, but allow everyone else to do it.
queue.tq1.produce.allow.user=* queue.tq1.produce.deny.user=Bob
The * principal rule for users overrides the corresponding * principal for groups. For example, the following two rules allow all authenticated users to send messages to tq1.
queue.tq1.produce.allow.user=* queue.tq1.produce.deny.group=*
Access granted a user overrides access granted to the user’s group. In the following example, even if Bob is a member of User, he cannot produce messages to tq1. All other members of User will be able to do so.
queue.tq1.produce.allow.group=User queue.tq1.produce.deny.user=Bob
Any access permission not explicitly granted through an access rule is implicitly denied. For example, if the ACL file contains no access rules, all users are denied all operations.
Deny and allow permissions for the same user or group cancel themselves out. For example, the following two rules cause Bob to be unable to browse q1:
queue.q1.browse.allow.user=Bob queue.q1.browse.deny.user=Bob
The following two rules prevent the group User from consuming messages at q5.
queue.q5.consume.allow.group=User queue.q5.consume.deny.group=User
When multiple same left-hand rules exist, only the last entry takes effect.
The connection access control section in the ACL properties file contains access control rules for the broker’s connection services. The syntax of connection access control rules is as follows:
connection.resourceVariant. access.principalType= principals
Two values are defined for resourceVariant: NORMAL and ADMIN. These predefined values are the only types of connection services to which you can grant access.
The default ACL properties file gives all users access to NORMAL connection services and gives users in the group admin access to ADMIN connection services:
connection.NORMAL.allow.user=* connection.ADMIN.allow.group=admin
If you are using a file-based user repository, the default group admin is created by the User Manager utility. If you are using an LDAP user repository, you can do one of the following to use the default ACL properties file:
Define a group called admin in the LDAP directory.
Replace the name admin in the ACL properties file with the names of one or more groups that are defined in the LDAP directory.
You can restrict connection access privileges. For example, the following rules deny Bob access to NORMAL but allow everyone else:
connection.NORMAL.deny.user=Bob connection.NORMAL.allow.user=*
You can use the asterisk (*) character to specify all authenticated users or groups.
The way that you use the ACL properties file to grant access to ADMIN connections differs for file-based user repositories and LDAP user repositories, as follows:
File-based user repository
If access control is disabled, users in the group admin have ADMIN connection privileges.
If access control is enabled, edit the ACL file. Explicitly grant users or groups access to the ADMIN connection service.
LDAP user repository. If you are using an LDAP user repository, do all of the following:
Enable access control.
Edit the ACL file and provide the names of users or groups who can make ADMIN connections. Specify any users or groups that are defined in the LDAP directory server.
The destination access control section of the access control properties file contains physical destination-based access control rules. These rules determine who (users/groups) may do what (operations) where (physical destinations). The types of access that are regulated by these rules include sending messages to a queue, publishing messages to a topic, receiving messages from a queue, subscribing to a topic, and browsing messages in a queue.
By default, any user or group can have all types of access to any physical destination. You can add more specific destination access rules or edit the default rules. The rest of this section explains the syntax of physical destination access rules, which you must understand to write your own rules.
The syntax of destination rules is as follows:
resourceType.resourceVariant.operation.access.principalType=principals
Table 7–4 describes these elements:
Table 7–4 Elements of Physical Destination Access Control Rules
Component |
Description |
---|---|
resourceType |
Can be queue or topic. |
resourceVariant |
A physical destination name or all physical destinations (*), meaning all queues or all topics. |
operation |
Can be produce, consume, or browse. |
access |
Can be allow or deny. |
principalType |
Can be user or group. |
Access can be given to one or more users and/or one or more groups.
The following examples illustrate different kinds of physical destination access control rules:
Allow all users to send messages to any queue destinations.
queue.*.produce.allow.user=*
Deny any member of the group user the ability to subscribe to the topic Admissions.
topic.Admissions.consume.deny.group=user
The final section of the ACL properties file, includes access rules that specify for which users and groups the broker will auto-create a physical destination.
When a user creates a producer or consumer at a physical destination that does not already exist, the broker will create the destination if the broker’s auto-create property has been enabled.
By default, any user or group has the privilege of having a physical destination auto-created by the broker. This privilege is specified by the following rules:
queue.create.allow.user=* topic.create.allow.user=*
You can edit the ACL file to restrict this type of access.
The general syntax for physical destination auto-create access rules is as follows:
resourceType.create.access.principalType=principals
Where resourceType is either queue or topic.
For example, the following rules allow the broker to auto-create topic destinations for everyone except Snoopy.
topic.create.allow.user=* topic.create.deny.user=Snoopy
Note that the effect of physical destination auto-create rules must be congruent with that of physical destination access rules. For example, if you 1) change the destination access rule to forbid any user from sending a message to a destination but 2) enable the auto-creation of the destination, the broker will create the physical destination if it does not exist but it will not deliver a message to it.