Sun Java System Web Server 7.0 Update 4 Administrator's Configuration File Reference

Chapter 9 ACL Files

This chapter describes the access control list (ACL) files and their syntax. ACL files are text files containing lists that define who can access resources stored on Web Server. By default, Web Server uses one ACL file that contains the access list. You can, however, create multiple ACL files and reference them in the obj.conf file.

After installation, a default access control list is written to the default.acl file in the instance_dir/config directory. You can change access control rules by editing this file or by creating additional ACL files.

When you make changes to ACL files, you must restart or reconfigure the server for the changes to take effect. For information on reconfiguring the server without restarting, see Dynamic Reconfiguration.

This chapter contains the following sections:

Referencing ACL Files in server.xml and obj.conf

If you create ACL files, you must reference them in server.xml using the acl-file element. Because the acl-file element can appear as a child element of both server and virtual-server elements, you can create ACL files that apply to the entire server or only to specific virtual servers. For more information, see acl-file.

If you have named ACLs, you can reference them in the obj.conf file. You can do this in the PathCheck directive using the check-acl function. The line has the following syntax:

PathCheck fn="check-acl" acl="aclname"

where aclname is a unique name of the ACL as it appears in an ACL file.

For example, you can add the following lines to your obj.conf file if you want to restrict access to a directory using the ACL named testacl:

<Object ppath="/var/htdocs/test/*">
PathCheck fn="check-acl" acl="testacl"

In the above example, the first line is the object that states which server resource to restrict access to. The second line is the PathCheck directive that uses the check-acl function to bind the named ACL testacl to the object in which the directive appears. For more information, see check-acl.

The testacl ACL can be defined in any ACL file referenced in server.xml.

ACL File Syntax

All ACL files must follow a specific format and syntax. The ACL file is a text file containing one or more ACLs. All ACL files must begin with the version number they use. There can be only one version line and it can appear after any comment line. Web Server uses version 3.0. For example:

version 3.0;

You can include comments in the file by beginning the comment line with the # sign.

Each ACL in the file begins with a statement that defines its type. ACLs can follow one of the three types:

Path and URI ACLs can include a wildcard at the end of the entry, for example: /a/b/*. Wildcards placed anywhere except at the end of the entry will not work.

The type line begins with the letters acl and includes the type information in double-quotation marks followed by a semicolon. Each type information for all ACLs must be a unique name even among different ACL files. The following lines are examples of several different types of ACLs:

acl "default";

acl "path=C:/docs/mydocs/";

acl "uri=/mydocs/";

After you define the type of ACL, you can have one or more statements that define the method used with the ACL (authentication statements) and the users and computers who are allowed or denied access (authorization statements). The following sections describe the syntax for these statements.

This section includes the following topics:

General Syntax

Input strings can contain the following characters:

If you use any other characters, add double-quotation marks around the characters. A single statement can be placed on its own line, and terminated with a semicolon. Multiple statements are placed within braces. A list of items must be separated by commas and enclosed in double-quotation marks.

Authentication Methods

ACLs can optionally specify the authentication method that the server must use when processing the ACL. There are three methods:

The basic and digest methods require users to enter a user name and password before accessing a resource. The ssl method requires the user to have a client certificate. The Web Server must have the encryption turned on, and the user’s certificate issuer must be in the list of trusted certificate authorities (CAs) to be authenticated.

By default, the server uses the basic method for any ACL that does not specify a method. If you use the digest method, the server’s authentication database must be able to handle digest authentication. Authentication databases are configured in server.xml with the auth-db element. For more information, see auth-db.

Each authenticate line must specify the attribute (users, groups, or both users and groups) that the server authenticates. The following authentication statement, which appears after the ACL type line, specifies basic authentication with users matched to individual users in the database or directory:

authenticate (user) { method = “basic”; };

The following example uses ssl as the authentication method for users and groups:

authenticate (user, group) { method = “ssl”; };

The following example allows any user whose user name begins with sales:

authenticate (user)

allow (all)

user = sales*

If the last line is changed to group = sales, then the ACL will fail because the group attribute is not authenticated.

Authorization Statements

Each ACL entry can include one or more authorization statements. Authorization statements specify who is allowed or denied access to a server resource. Use the following syntax to write authorization statements:

allow|deny [absolute] (right[,right...]) attribute expression;

Start each line with either allow or deny. Because of the hierarchy rules, it is usually a good practice to deny access to everyone in the first rule and then specifically allow access for users, groups, or computers in subsequent rules. That is, if you allow anyone access to a directory called /my_stuff, and you have a subdirectory /my_stuff/personal that allows access to a few users, the access control on the subdirectory will not work because anyone allowed access to the /my_stuff directory will also be allowed access to the /my_stuff/personal directory. To prevent this, create a rule for the subdirectory that first denies access to anyone and then allows it for the few users who need access.

In some cases, if you set the default ACL to deny access to everyone, your other ACL rules do not need a deny all rule.

The following line denies access to everyone:

deny (all) user = "anyone";

Hierarchy of Authorization Statements

ACLs have a hierarchy that depends on the resource. For example, if the server receives a request for the document (URI) /my_stuff/web/presentation.html, the server builds a list of ACLs that apply for this URI. The server first adds ACLs listed in check-acl statement of its obj.conf file. Then the server appends matching URI and PATH ACLs.

The server processes this list in the same order. Unless absolute ACL statements are present, all statements are evaluated in order. If an absolute allow or absolute deny statement evaluates to true, the server stops processing and accepts this result.

If there is more than one ACL that matches, the server uses the last statement that matches. However, if you use an absolute statement, the server stops looking for other matches and uses the ACL containing the absolute statement. If you have two absolute statements for the same resource, the server uses the first one in the file and stops looking for other resources that match.

version 3.0;
acl "default";
authenticate (user, group) {
  prompt = "Sun Java System Web Server";
allow (read, execute, info) user = "anyone";
allow (list, write, delete) user = "all";

acl "uri=/my_stuff/web/presentation.html";
deny (all) user = "anyone";
allow (all) user = "user1"; 

Expression Attribute

Attribute expressions define who is allowed or denied access based on their user name, group name, host name, or IP address. The following are examples of allowing access to different users or computers:

You can also restrict access to your server by time of day (based on the local time on the server) by using the timeofday attribute. For example, you can use the timeofday attribute to restrict access to certain users during specific hours.

Note –

Use 24-hour time to specify times. For example, use 0400 to specify 4:00 a.m. or 2230 for 10:30 p.m.

The following example restricts access to a group of users called guests between 8:00 a.m. and 4:59 p.m.:

allow (read)

(group="guests") and (timeofday<0800 or timeofday=1700);

You can also restrict access by day of the week. Use the following three-letter abbreviations to specify days: Sun, Mon, Tue, Wed, Thu, Fri, and Sat.

The following statement allows access for users in the premium group any day and any time. Users in the discount group get access all day on weekends and on weekdays, any time except 8 a.m. to 4:59 p.m.

allow (read) (group="discount" and dayofweek="Sat,Sun") or (group="discount" and (dayofweek="mon,tue,wed,thu,fri" and(timeofday<0800 or timeofday=1700)))or (group="premium");

Expression Operators

You can use various operators in an expression. Parentheses delineate the operator order of precedence. With user, group, dns, and ip, you can use the following operators:

With timeofday and dayofweek, you can use:

Sample ACL File

After installation, the instance_dirconfig/default.acl file provides default settings for the server. When editing an ACL file, you can make changes in the default file, then deploy the changes. You can also create additional ACL files.

A sample default.acl file is as follows:

version 3.0;
acl "default";
authenticate (user, group) {
  prompt = "Sun Java System Web Server";
allow (read, execute, info) user = "anyone";
allow (list, write, delete) user = "all";

acl "es-internal";
allow (read, execute, info) user = "anyone";
deny (list, write, delete) user = "anyone";

Note –

The above access control rules allow anyone to read resources on the server but restrict listing, writing, and deleting resources to authenticated users.