Understanding Sun Web Server 7.0 Configuration Files

This chapter is from the book

Sun Web Server: The Essential Guide

Learn More Buy

This chapter is from the book

This chapter is from the book 

Sun Web Server: The Essential Guide

Learn More Buy

5.8 The default.acl File

You can control access to the entire Web Server or to parts of the server (for example, directories, files, and file types). When the Web Server evaluates an incoming request, it determines access based on a hierarchy of rules called access control entries (ACEs). The Web Server uses the matching entries to determine whether the client request is allowed or denied.

The collection of ACEs is called an access control list (ACL). The Web Server processes the ACL list from top to bottom. If at any time an ACE evaluates to a value of false, then processing of the ACL stops and the user is denied access to the resource.

ACL files contain rules that define who can access resources stored on the Web Server. By default, the Web Server uses one ACL file (default.acl) that contains the default access list. You can change access control rules by editing this file or by creating additional ACL files for one or more instances. If you create additional ACL files, you can associate them to different virtual servers by using the <acl-file> element in the server.xml.

Example 5.9 demonstrates the use of the <acl-file> element to specify an additional ACL file for a particular virtual server:

Example 5.9. Virtual Server Definition for an ACL File

<virtual-server>
  <name>www.example.com</name>
  <http-listener-name>http-listener-1</http-listener-name>
  <host>www.example.com</host>
  <object-file>www.example.com-obj.conf</object-file>
  <mime-file>mime.types</mime-file>
  <acl-file>example.acl</acl-file>
  <document-root>/export/home/example.com/public_html</document-root>
  <access-log>
  <file>/export/home/example.com/logs/access</file>
  </access-log>
</virtual-server>

Associating different ACL files to each virtual server provides you with the flexibility to provide different access control at the virtual server level.

5.8.1 File Structure

The ACL file is a text file containing one or more ACLs. Example 5.10 demonstrates the access control list file for the default Administration Node.

Example 5.10. Default default.acl File

#--Sun Microsystems Inc. MIME Information
# Do not delete the above line. It is used to identify the file type.
#
# Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#
# Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#

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";

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

5.8.2 Syntax

All ACL files must follow a specific format and syntax. 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 7 uses version 3.0. For example:

    version 3.0;

You can include comments in the file by beginning the comment line with the hash (#) character.

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

• Path ACLs specify an absolute path to the resource they affect.
• URI ACLs specify a directory or file relative to the server’s document root.
• Named ACLs specify a name that is referenced in the obj.conf file. Web Server 7 comes with a default named resource that allows read access to all users and write access to users in the LDAP directory. Even though you can create a named ACL from the Web Server user interface, you must manually reference the named ACLs with resources in the obj.conf file.

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 do 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.

5.8.2.1 General Syntax

Input strings can contain the following characters:

• Alphanumeric characters a through z or 0 through 9
• A period (.) or underscore (_) character

If you use any other characters, add double quotation marks around them. 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.

5.8.2.2 Authentication Methods

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

• basic
• digest
• ssl

The basic and digest methods both require users to enter a username and password before accessing a resource. The two differ, however, in the manner in which data is transmitted between the client and the Web Server and how the password is verified within the authentication database.

The basic authentication method enables users to enter a username and password and transmits the information to the Web Server in known Base 64-Encoded text. For security reasons, basic authentication is almost always used with SSL connections so that the username and password are encrypted before being sent from the client.

The digest authentication method prevents the client’s username and password from being sent in known text. The browser uses the MD5 algorithm to create a message digest using the password and information sent by Web Server. The digest value is computed and compared on the server side using the Digest Authentication plug-in.

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. See Section 5.7, “The certmap.conf File,” for more information on using client certificates for authentication.

By default, the server uses the basic method for any ACL that does not explicitly 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. See Chapter 8 for more information on configuring authentication databases.

Each authenticated 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 username begins with sales:

    authenticate (user)
    allow (all)
    user = sales*

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

5.8.2.3 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 does not work because anyone allowed access to the /my_stuff directory is also 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";

5.8.2.4 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 the 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 more than one ACL 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.

Example 5.11 demonstrates how an ACL might be written to allow user1 access to the content found at /my_stuff/web/presentation.html.

Example 5.11. Sample ACL Entries to Protect Web Server Content

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";

5.8.2.5 Expression Attribute

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

• user = "anyone"
• user = "smith*"
• group = "sales"
• dns = "*.sun.com"
• dns = "*.sun.com,*.mozilla.com"
• ip = "198.*"
• ciphers = "rc4"
• ssl = "on"

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.

The following example restricts access to a group of users called guests between 8:00 a.m. and 5:00 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:00 a.m. to 5:00 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");

5.8.2.6 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:

• and
• or
• not
• = (equals)
• != (not equal to)

With timeofday and dayofweek, you can use

• > (greater than)
• < (less than)
• >= (greater than or equal to)
• <= (less than or equal to)

5.8.3 Context

The server.xml file contains definitions for each virtual server contained within the instance, so there is a one-to-many relationship between the server.xml file and virtual servers.

Each virtual server can use one or more access control list files for protecting resources specific to that virtual server; therefore, there is a one-to-many relationship between an instance and the access control list file(s). Additionally, there is a one-to-many relationship between the virtual server and its access control list file(s).

5.8.4 Modifications

Administrators can update any of the access control list files through the Administration Console or the command line interface. If this file is updated as a result of changes made through either of these two interfaces, you must deploy the updated configuration before the changes are reflected on the appropriate Administration Node(s).

Access control list files are read when the instance is started or when a dynamic reconfiguration is performed. The syntax for the entries contained in these files is validated within the start-up or reconfiguration code base. They are not validated against a schema like the server.xml file is.

Errors found within the file may prevent the instance from starting or processing requests properly.