Previous Contents Index Next
Sun ONE Web Server 6.1 Administrator's Guide

> ## Appendix C
> ACL File Syntax

> This appendix describes the access-control list (ACL) files and their syntax. ACL files are text files that contain lists that define who can access resources stored on your web server. By default, the web server uses one ACL file that contains all of the lists for access to your server. However, you can create multiple ACL files and reference them in the obj.conf file.

> You need to know the syntax and function of ACL files if you plan on customizing access control using the access-control API. For example, you might use the access control API to interface with another database, such as an Oracle or Informix database. For more information on the API, see the Sun ONE documentation site at:

> http://docs.sun.com

> This appendix contains the following sections:

> - ACL File Syntax
> - Referencing ACL Files in obj.conf

> ##

> ACL File Syntax

> All ACL files must follow a specific format and syntax. An 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 lines. Sun ONE Web Server 6.1 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 three types:

> - Path ACLs specify an absolute path to the resource they affect
> - URI (Uniform Resource Indicator) ACLs specify a directory or file relative to the server’s document root.
> - Named ACLs specify a name that is referenced in resources in the obj.conf file. The server comes with a “default” named resource that allows read access to anyone and write access to users in the LDAP directory. Even though you can create a named ACL from the Sun ONE Web Server windows, you must manually reference the named ACLs with resources in the obj.conf file.

> Path and URI ACLs can include wildcards at then 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 then 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 "path=C:/sun/Servers/docs/mydocs/";
> acl "default";
> 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 people 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:

> - Authentication Methods
> - Authorization Statements
> - The Default ACL File

> ### Authentication Methods

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

> - Basic (default)
> - Digest
> - SSL

> Basic and digest require users to enter a username and password before accessing a resource.

> SSL requires the user to have a client certificate. The web server must have encryption turned on, and the user’s certificate issuer must be in the list of trusted CAs to be authenticated.

> By default, the server uses the Basic method for any ACL that doesn’t specify a method. Your server’s authentication database must be able to handle digest authentication sent by a user.

> Each authenticate line must specify what attribute (users, groups, or both users and groups) the server authenticate. The following authentication statement, which would appear 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 the letters sales:

> authenticate (user)

> allow (all)

> user = sales*

> If the last line was changed to group = sales, then the ACL would 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 when writing authorization statements:

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

> Start each line with either allow or deny. It’s usually a good idea to deny access to everyone in the first rule and then specifically allow access for users, groups, or computers in subsequent rules. This is because of the hierarchy of rules. That is, if you allow anyone access to a directory called /my_stuff, and then you have a subdirectory /my_stuff/personal that allows access to a few users, the access control on the subdirectory won’t 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.

> However, in some cases if you set the default ACL to deny access to everyone, then your other ACL rules don’t need a “deny all” rule.

> The following line denies access to everyone:

> deny (all)
> user = "anyone";

> This section includes the following topics:

> - Hierarchy of Authorization Statements
> - Attribute Expressions
> - Operators For Expressions

> #### 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’ statements of it’s 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 are more than one ACLs that match, the server uses the last statement that matches. However, if you use an absolute statement, then 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="Web Server"; }; allow (read,execute,list,info) user = "anyone"; allow (write,delete) user = "all"; acl "uri=/my_stuff/web/presentation.html"; deny (all) user = "anyone"; allow (all) user = "joe";

> #### Attribute Expressions

> Attribute expressions define who is allowed or denied access based on their username, group name, host name, or IP address. The following lines are examples of allowing access to different people 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.

> 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 of the week: 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 anytime except 8am-4:59pm.

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

> #### Operators For Expressions

> You can use various operators in attribute expressions. 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

> ### The Default ACL File

> After installation, the server_root/httpacl/generated.https-serverid.acl file provided default settings for the server. The server uses the working file genwork.https-serverid.acl until you create settings in the user interface. When editing an ACL file, you could make changes in the genwork file, then save and apply the changes using Sun ONE Web Server.

> genwork File.

> #### General Syntax Items

> Input strings can contain the following characters:

> - Letters a through z
> - Numbers 0 through 9
> - Period and underscore

> If you use any other characters, you need to use double-quotation marks around the characters.

> A single statement can be placed on its own line and be 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.

> ##

> Referencing ACL Files in obj.conf

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

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

> The aclname is a unique name of an ACL as it appears in any ACL file.

> For example, you might 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="/usr/ns-home/docs/test/*"
> PathCheck fn="check-acl" acl="testacl"
> </Object

> In the previous example, the first line is the object that states which server resource you want to restrict access to. The second line is the PathCheck directive that uses the check-acl function to bind the name ACL (testacl) to the object in which the directive appears. The testacl ACL can appear in any ACL file referenced in magnus.conf.

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.