Sun ONE Application Server 7 Administrator's Guide to Security |
Administering HTTP Server Access ControlThis section provides information on the mechanisms and procedures used for controlling access to HTTP server resources.
This section addresses the following topics:
- About HTTP Server Access Control
- Implementing Digest Authentication
- Implementing Host-IP Authentication
- Working With ACL Files
- Setting Up Client Authentication
- ACL/ACE Settings
- Referencing ACL Files in the obj.conf File
- Configuring the ACL User Cache
- Setting Access Control for a Server Instance
- Restricting Access to Areas of Your Server
- Turning Off Access Control
- Responding When Access is Denied
- Controlling Access for Virtual Servers
- Using htaccess Files
About HTTP Server Access Control
Access control is the means of securing your Sun ONE Application Server by controlling who and what has access to it. For example, you can specify who has full control of all the servers installed on a machine and who has partial control of one or more servers.
Access is allowed or denied based on:
- Who is making the request
- Where the request is coming from
- When the request is happening (for example, time of day)
- What type of connection is being used (such as SSL)
The security mechanisms that control access to your HTTP server include various authentication restrictions and ACL files.
This section addresses the following topics:
- HTTP Server User-Group Authentication
- Host-IP Authentication
- Access Control List (ACL) Files
- Client Authentication
HTTP Server User-Group Authentication
User-Group authentication requires that users authenticate themselves before access can be granted. This is done by entering a user name and password, using a client certificate, or a using the digest authentication plug-in. The Sun ONE Application Server receives this information encrypted or unencrypted, depending on whether encryption is turned on for your server.
The default authentication used is the default method you specify in the obj.conf file, or Basic authentication if there is no setting in the obj.conf file.
If you select Default as your authentication method, the ACL rule doesn't specify a method in the ACL file. Choosing Default allows you to easily change the methods for all ACLs by editing one line in the obj.conf file.
Using the default is the preferred method.
There are three User-Group authentication methods, all of which require a directory server:
- Basic Authentication
- SSL Authentication
- Digest Authentication
Note If you want to require client authentication on your Admin Server, you must manually edit the ACL files in the obj.conf file, changing the method to SSL. For further information on client authentication, refer to "Setting Up Client Authentication".
Basic Authentication
Basic authentication requires a user to enter a user name and password to access your Sun ONE Application Server or web site. You must first create and store a list of users and groups in an LDAP database, such as the Sun ONE Directory Server. The directory server must be installed on a different server root than your Sun ONE Application Server, or on a directory server installed on a remote machine.
Basic authentication is the default setting.
SSL Authentication
SSL authentication requires that the Sun ONE Application Server confirm user identities using the users' security certificates. This can happen in two ways:
- Using the information in the client certificate as proof of identity
- Verifying a client certificate published in an directory (additional)
When you set the server to use certificate information for authenticating the client, the Sun ONE Application Server does the following:
- Verifies that the certificate is from a trusted authority (CA). If not, the authentication fails and the transaction ends.
- If the certificate is from a trusted certificate CA, maps the certificate to a user's entry using the certmap.conf file. To learn how to set up the certificate mapping file see "Working with the certmap.conf File".
- If the certificate maps correctly, checks the ACL rules specified for that user.
Note Even if the certificate maps correctly, ACL rules may deny access to the user.
User-Group SSL Authentication
If you set the server's access control to use the User-Group SSL authentication method, the following must be true:
- A valid certificate issued by a trusted CA is presented.
- The certificate is mapped to a valid user in the directory database.
- The access control list (ACL) evaluates properly
Client SSL Authentication to Specific Resources
Requiring client authentication for controlling access to specific resources differs from requiring client authentication for all connections to the server. If you set the server to require client authentication for all connections, the client only needs to present a valid certificate issued by a trusted CA. To learn how to turn on client authentication, see "Setting Up Client Authentication".
When you require client SSL authentication, you need to have SSL ciphers enabled for your server. Refer to "Enabling SSL and TLS" for further information.
To successfully gain access to an SSL-authenticated resource, the client certificate must be from a CA trusted by the server. The client certificate needs to be published in a directory server if the server's certmap.conf file is configured to compare the client's certificate in the browser with the client certificate in the directory server. However, the certmap.conf file can be configured to compare only selected information from the certificate to the directory server entry. For example, you could configure the certmap.conf file to compare only the user ID and email address in the browser certificate with the directory server entry. To learn more about the certmap.conf file and certificate mapping, see "Working with the certmap.conf File".
Digest Authentication
Digest authentication allows the user to authenticate based on user name and password without sending the user name and password as cleartext. The browser uses the MD5 algorithm to create a digest value using the user's password and some information provided. This digest value is also computed on the server side using the Digest authentication plug-in, and compared against the digest value provided by the client. If the digest values match, the user is authenticated.
For this to work, your directory server needs access to the user's password in cleartext. The Sun ONE Directory Server includes a reversible password plug-in that uses a symmetric encryption algorithm to store data in an encrypted form. Later the data can be decrypted to its original form. Only the Sun ONE Directory Server holds the key to the data.
When processing an ACL with method=digest, the server attempts to authenticate using the following process:
- Checking for authorization request headerIf not found, an error is generated with a Digest challenge, and the process stops.
- Checking for authorization typeIf Authentication type is Digest, the server does the following:
Checks nonceIf this is not a valid, fresh nonce is generated by this server, an error is generated, and the process stops. If stale, an error is generated with stale=true, and the process stops.
Checks realmIf it does not match, an error is generated, and the process stops.
Checks existence of user in LDAP directoryIf not found, an error is generated, and the process stops.
Gets request-digest value from directory server and checks for match to client's request-digestIf it does not match, an error is generated, and the process stops.
Constructs Authorization-Info header and inserts into server headers.
The server tries to authenticate against the directory database based on the ACL method as specified in the following table.
For more information, refer to "Implementing Host-IP Authentication".
Host-IP Authentication
Host-IP access control is a method of limiting access to the Admin Server, or the files and directories on your web site by making them available only to clients using specific computers. You do this by specifying the hostnames or IP addresses for the computers that you want to allow or deny access to. You can use wildcard patterns to specify multiple computers or entire networks.
Host-IP authentication appears seamless to users, who can access the files and directories immediately without entering a user name or password. Further information can be found in "Implementing Host-IP Authentication".
Access Control List (ACL) Files
ACL files are text files that contain lists identifying who can access the resources stored on your Sun ONE Application Server. By creating a hierarchy of rules called access control entries (ACEs) you can allow or deny access to individuals, groups, or other entities such as particular servers or applications. Each ACE specifies whether or not the server should check the next ACE in the hierarchy. The collection of ACEs you create is called an access control list (ACL).
By default, the Sun ONE Application Server uses a single ACL file that contains all the lists for accessing your server. As an alternative to this default, you can create multiple ACL files and reference them in the obj.conf file.
When the Sun ONE Application Server receives a request for a page, the server uses the rules in the ACL file to determine if it should grant access or not. The rules can reference the hostname or IP address of the computer sending the request. The rules can also reference users and groups stored in an LDAP directory such as the Sun ONE Directory Server.
After determining which virtual server to use for an incoming request, the Sun ONE Application Server determines if any ACLs are configured for that virtual server. If ACLs are found that apply to the current request, the Sun ONE Application Server evaluates their ACEs to determine whether access should be allowed (granted) or denied (refused).
Information on using ACLs is contained in "Working With ACL Files".
Client Authentication
When client authentication is enabled, the client's certificate is required before the server will send a response to a query. The Sun ONE Application Server supports authenticating client certificates by matching the CA in the client certificate with a CA trusted for signing client certificates.
When the Sun ONE Application Server receives a request from a client, it asks for the client's certificate before proceeding. Some clients send the client certificate to the server along with the request.
Note Before mapping client certificates to LDAP, you need to set up the required ACLs. More information on access control can be found in "Working With ACL Files".
- The Sun ONE Application Server tries to match the CA to the list of trusted CAs in the Admin Server.
If there isn't a match, the Sun ONE Application Server ends the connection.
- If there is a match, the server continues processing the request.
- After verifying the certificate is from a trusted CA, the server maps the certificate to an LDAP entry by:
Mapping the issuer and subject DN from the client certificate to a branch point in the LDAP directory.
Searching the LDAP directory for an entry that matches the information about the subject (end-user) of the client certificate.
The server uses a certificate mapping file called certmap.conf to determine how to do the LDAP search. The mapping file tells the server what values to take from the client certificate (such as the user's name, email address, and so on). The server uses these values to search for a user entry in the LDAP directory, but first the server needs to determine where in the LDAP directory it needs to start its search. The certificate mapping file tells the server where to start.
(Optional) Verifying the client certificate with one in the LDAP entry that corresponds to the DN.
- Once the server knows where to start its search and what it needs to search for, it performs the search in the LDAP directory. If it finds no matching entry or more than one matching entry, and the mapping is not set to verify the certificate, the search fails.
You can specify the expected behavior in the ACL. For example, you can specify that Sun ONE Application Server accepts only you if the certificate match fails. For more information regarding how to set the ACL preferences, see .
- After the server finds a matching entry and certificate in the LDAP directory, it can use that information to process the transaction. For example, some servers use certificate-to-LDAP mapping to determine access to a server.
Information on implementation is contained in "Setting Up Client Authentication".
Implementing Digest Authentication
If you are unfamiliar with how Digest authentication works, refer to "Digest Authentication".
For Digest authentication, you need to enable the reversible password plug-in and the digestauth-specific plug-in included with the Sun ONE Application Server. To configure your server to process Digest authentication, you will need to set the digestauth property of the database definition in the dbswitch.conf file.
The tasks required for implementing User-Group Digest authentication are addressed in the following sections:
- Installing the Digest Authentication Plug-in
- Setting the Sun ONE Directory Server to Use the DES Algorithm
Installing the Digest Authentication Plug-in
The Digest authentication plug-in consists of a shared library found in both libdigest-plugin.lib and libdigest-plugin.ldif.
Digest Authentication on UNIX
To install the Digest authentication plug-in on UNIX, perform the following steps:
- Make sure this shared library resides on the same server machine that the Sun ONE Directory Server is installed on.
- Make sure you know the Directory Manager password.
- Modify the libdigest-plugin.ldif file changing all references to /path/to to the location where you installed the Digest plug-in shared library.
- To install the plug-in, enter the following command:
% ldapmodify -D "cn=Directory Manager" -w password -a < libdigest-plugin.ldif
Digest Authentication on Windows
To install the Digest authentication plug-in on Windows, perform the following steps:
- Access the shared libraries in the Sun ONE Application Server installation in:
install_dir\bin
- Copy the files:
- Paste them into either:
Setting the Sun ONE Directory Server to Use the DES Algorithm
The DES algorithm is needed to encrypt the attribute where the Digest password is stored. To set the Sun ONE Directory Server to use the DES algorithm, perform the following steps:
- Launch the Sun ONE Directory Server Console.
- Open your Sun ONE Directory Server instance.
- Select the Configuration tab.
- Click the + sign next to plug-ins.
- Select the DES plug-in.
- To add a new attribute, choose Add.
- Enter iplanetReversiblePassword.
- Click Save.
- Stop and start the server for changes to take effect.
.
Note In order to set a digest authentication password in the iplanetReversiblePassword attribute for a user, your entry must include the iplanetReversiblePasswordobject object.
Implementing Host-IP Authentication
Since more than one person may use a particular computer, Host-IP authentication is more effective when combined with User-Group authentication. If both User-Group and Host-IP authentication are used, a user name and password is required for access.
Host-IP authentication does not require DNS to be configured on your Sun ONE Application Server, but you must have DNS running in your network and your Sun ONE Application Server must be configured to use it.
Note You can enable DNS on the HTTP Server->Tuning page of the Administration interface.
Enabling DNS degrades the performance of the Sun ONE Application Server because the server is required to do DNS look-ups. To reduce the impact of DNS look-ups on your Sun ONE Application Server performance, resolve IP addresses only for access control and CGI instead of resolving IP addresses for every request. To minimize DNS impact, append iponly=1 to AddLog fn="flex-log" name="access" in your obj.conf file:
AddLog fn="flex-log" name="access" iponly=1
Working With ACL Files
The main ACL file name is generated.server-id.acl; the temporary working file is called genwork.server-id.acl. If you use the Admin Server to configure access, these two files will exist. However, if you want more complex restrictions, you can create multiple files, and reference them from the server.xml file. There are also a few features available only by editing the files, such as restricting access to the server based on the time of day or day of the week.
Access control files are stored in the directory instance_dir/config where instance_dir is the name of the instance. For example, the access control files for the initial server instance are stored in the install_dir/domains/domain1/server1/config directory.
The following topics are addressed in this section:
- ACL File Syntax
- Type Statement
- Authentication Statement
- Authorization Statement
- Sample ACL File
- Writing Customized ACL Expressions
ACL File Syntax
ACL files must follow a specific format and syntax. A typical ACL definition in the ACL list is made up of a number of statements about type, the authentication method, and the authorization method.
A snippet from an ACL file might look like this:
version 3.0;
# The "default" rules apply to the entire document
acl "default";
authenticate (user,group) {
database = "default";
method = "basic";
};
deny (all)
user = "anyone");
allow (read,execute,list,info)
(user = "all");
};The components of this snippet include:
- Version LineAll ACL files begin with a line specifying the version number. There can be only one version line in an ACL file. For example:
version 3.0;
- Type statementIdentifies the type of ACL the definition is for. For example:
acl "default";
- Authentication statementOptionally specifies the authentication method. For example:
authenticate (user,group) {
database = "default";
method = "basic";
- Authorization statementSpecifies who is allowed or denied access to a server resource. For example:
deny (all)
(user = "anyone");
allow (read,execute,list,info)
(user = "all");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 must use double quotation marks (") around the characters.
- A single statement is placed on its own line and is terminated with a semicolon.
- Multiple statements are placed within braces.
- In a list of items, the items must be separated from each other with commas, and the list must be enclosed in double quotation (") marks.
Type Statement
Each ACL definition in the file contains a statement that identifies what type of ACL it is. This type can be one of the following:
- Path ACLSpecifies an absolute path to the resource it affects.
- URI (Uniform Resource Indicator) ACLSpecifies a directory or file relative to the server's document root.
- Named ACLSpecifies 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 Application Server, you must manually reference the named ACLs with resources in the obj.conf file.
A type line begins with the letters acl, followed by the type information in double quotation marks, ended by a semicolon. The type information for each ACL must be a unique nameeven 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/";Path and URI ACLs can include wildcards at the end of the entry. For example: /a/b/*. Wildcards placed anywhere except at the end of the entry will not work.
Authentication Statement
Optionally, ACLs can specify the authentication method the Sun ONE Application Server must use when processing the ACL. There are three general methods:
- Basic authentication(Default) Requires the user to enter a user name and password before accessing a resource.
By default, the Sun ONE Application Server uses the Basic method for any ACL that doesn't specify a method.
- SSL authenticationRequires the user to have a client certificate. The Sun ONE Application Server must have encryption turned on, and the user's certificate issuer must be in the list of trusted CAs.
- Digest authenticationRequires the user to enter a user name and password before accessing a resource.
Note
Each authentication statement specifies what attributes (users, groups, or both users and groups) the Sun ONE Application Server must authenticate.
Examples
Specifies Basic authentication with users matched to individual users in the database or directory:
authenticate (user) {
method = "basic";
};Specifies the User-Group SSL authentication method:
authenticate (user, group) {
method = "ssl";
};Allows access to any user whose user name begins with the letters sales:
authenticate (user) {
allow (all)
user = sales*
};
If the last line were changed to group=sales, the ACL would fail because the authenticate line specifies user, not group.
Authorization Statement
An authorization statement specifies who is allowed or denied access to a server resource. Each ACL entry can include one or more authorization statements. Use the following syntax when writing authorization statements:
allow|deny [absolute] (right[,right...]) attribute expression;
Each line starts with the keyword allow or deny.
Because of the hierarchy of rules, it is usually a good idea to deny access to everyone in the top-level rule, then specifically allow access for users, groups, or computers in subsequent rules.
Scenario
If you allow full access to a directory called /my_stuff, then you want a subdirectory called /my_stuff/personal that will allow access to only a few users, the access control on the subdirectory won't workeveryone allowed access to the /my_stuff directory will also be allowed access to the /my_stuff/personal directory. To prevent this, first create a rule for /my_stuff/personal that denies access to everyone, then allow access for the few users you specify.
Note In some cases, if you set the default ACL to deny access to everyone, then your other ACL rules won't need a deny all rule.
The following authorization statement denies access to everyone:
deny (all)
user = "anyone";The following sections are association with authorization statements:
Hierarchy of Authorization Statements
ACLs have a hierarchy based on the resource. For example, if the Sun ONE Application 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.
- First the Sun ONE Application Server adds ACLs listed in the check-acl statements of the server's obj.conf file.
- Then the server appends matching URI and PATH ACLs.
All statements are evaluated in order, unless absolute ACL statements are present. If an absolute allow or absolute deny statement evaluates to true, the server stops processing and accepts this result.
If there are multiple ACLs that match, the Sun ONE Application 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 Sun ONE Application Server uses the first one in the file and stops looking for other resources that match.
The following example stops searching when it reaches the absolute "joe", even if there might be additional users named joe:
version 3.0;
acl "default";
authenticate (user,group) {
prompt="Sun ONE Application 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
An attribute expression defines who is allowed or denied access based on their user name, group name, host name, or IP address. The following are examples of how access is given 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"
timeofday = <0800 or timeofday=1700
dayofweek = "Sat,Sun"
You can also restrict access to your server by time of day (based on the local time on the server) using the timeofday attribute. Refer to "Restricting Access Based on Time of Day" for additional information.
For example, the timeofday attribute can 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.
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 using the dayofweek attribute with the following three-letter abbreviations to specify days of the week: Sun, Mon, Tue, Wed, Thu, Fri, Sat.
Example
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
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 the timeofday and dayofweek attributes, you can use:
- > greater than
- < less than
- >= greater than or equal to
- <= less than or equal to
Sample ACL File
The following sample ACL file contains the two default entries for the Admin Server (admin-server), plus an additional entry that allows users in the admin-reduced group to access the Admin Server.
Example
If a user requests: http://server_name/my_stuff/web/presentation.html, the Sun ONE Application Server first checks access control for the entire server. If the ACL for the entire server was set to continue, the server would check for an ACL for the directory my_stuff. If an ACL exists, the server checks the ACEs within the ACL, then moves on to the next directory. This process continues until an ACL is found that denies access, or until the final ACL for the requested URL (in this case, the file presentation.html) is reached.
Writing Customized ACL Expressions
You can enter custom expressions for an ACL. There are a few features that are available only by editing the ACL file or by creating custom expressions. For example, you can restrict access to your server depending on the time of day, day of the week, or both.
Note Only select this option if you are familiar with the syntax and structure of ACL files.
The following customized expression shows how you could restrict access by time of day and day of the week. This example assumes you have two groups in your LDAP directory: the regular group is allowed access Monday through Friday, 8:00am to 5:00pm. The critical group is allowed access all the time.
allow (read)
{
(group=regular and dayofweek="mon,tue,wed,thu,fri");
(group=regular and (timeofday>=0800 and timeofday<=1700));
(group=critical)
}Setting Up Client Authentication
You can set up client authentication for the Admin Server or for a server instance.Instructions are contained in the following sections:
- Setting Client Authentication for the Admin Server
- Setting Client Authentication for a Server Instance
- Working with the certmap.conf File
Setting Client Authentication for the Admin Server
To set up client authentication at the Admin Server level:
- Access the Admin Server and select the HTTP Listener tab in the right pane.
The Admin Server HTTP Listener page is displayed.
   HTTP Listener Page for the Admin Server
- Click SSL/TLS Enabled to turn security on (default is off).
- Click Client Authentication Enabled to turn client authentication on (default is off).
- Click Save.
- Select the Control tab on the right pane and click Apply Changes.
   Admin Server Control Page
- Stop and start the server for changes to take effect.
To start the Admin Server, go to install_dir/domains/domain1/admin-server/bin/startserv
Setting Client Authentication for a Server Instance
To set up client authentication at the Server Instance level:
- Access the App Server Instance and select the server instance in the left pane.
- Expand HTTP Server in the left pane and click HTTP Listeners.
The HTTP Listener page is displayed, listing the listener instances.
- Select the instance you want.
The HTTP Listener page for that instance is displayed.
   HTTP Listeners for an App Server Instance Page
- Click the SSL/TLS Enabled checkbox to turn security on (default is off).
- Click the Client Authentication Enabled checkbox to turn it on (default is off).
- Click Save.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
.
Working with the certmap.conf File
Certificate mapping is the mechanism by which a server looks up a user entry in the LDAP directory. You can use the certmap.conf file to configure how a certificate, designated by name, is mapped to an LDAP entry. You edit this file and add entries to match the organization of your LDAP directory and to list the certificates you want your users to have. Users can be authenticated based on user ID, email, or any other value used in the subjectDN. Specifically, the mapping file provides the following information:
- Where in the LDAP tree the server should begin its search
- What certificate attributes the server should use as search criteria when searching for the entry in the LDAP directory
- Whether or not the server goes through an additional verification process
The certificate mapping file is located here:
/instance_dir/config/certmap.conf
The file contains one or more named mappings, each applying to a different CA. A mapping has the following syntax:
certmap <name> <issuerDN>
<name>:<property> [<value>]The first line specifies a name for the entry and the attributes that form the DN found in the CA certificate. The name is arbitrary; you can define it to be whatever you want. However, issuerDN must exactly match the issuer DN of the CA who issued the client certificate. For example, the following two issuerDN lines differ only in the spaces separating the attributes, but the server treats these two entries as different:
The following topics address the certmap.conf file:
Default Properties
The second and subsequent lines in the named mapping match properties with values. The certmap.conf file has six default properties (you can use the certificate API to customize your own properties):
- DNCompsA list of comma-separated attributes used to determine where in the LDAP directory the Sun ONE Application Server should start searching for entries that match the user's information (that is, the owner of the client certificate). The server gathers values for these attributes from the client certificate and uses the values to form an LDAP DN, which then determines where the server starts its search in the LDAP directory. For example, if you set DNComps to use the o and c attributes of the DN, the server starts the search from the o=<org>, c=<country> entry in the LDAP directory, where <org> and <country> are replaced with values from the DN in the certificate.
Note the following situations:
If there isn't a DNComps entry in the mapping, the server uses either the CmapLdapAttr setting or the entire subject DN in the client certificate (that is, the user's information).
If the DNComps entry is present but has no value, the server searches the entire LDAP tree for entries matching the filter.
- FilterCompsA list of comma-separated attributes used to create a filter by gathering information from the user's DN in the client certificate. The server uses the values for these attributes to form the search criteria used to match entries in the LDAP directory. If the server finds one or more entries in the LDAP directory that match the user's information gathered from the certificate, the search is successful and the server optionally performs a verification.
For example, if FilterComps is set to use the email and user ID attributes (FilterComps=e,uid), the server searches the directory for an entry whose values for email and user ID match the end user's information gathered from the client certificate. Email addresses and user IDs are good filters because they are usually unique entries in the directory. The filter needs to be specific enough to match one and only one entry in the LDAP database.
The following table contains a list of the x509v3 certificate attributes.
   Attributes for x509v3 Certificates
Attribute
Description
c
Country
o
Organization
cn
Common name
l
Location
st
State
ou
Organizational unit
uid
UNIX userid
email address
- verifycertTells the server whether it should compare the client's certificate with the certificate found in the LDAP directory. It takes two values: on, and off. You should only use this property if your LDAP directory contains certificates. This feature is useful to ensure that your users have a valid, unrevoked certificate.
- CmapLdapAttrA name for the attribute in the LDAP directory that contains subject DNs from all certificates belonging to the user. The default for this property is certSubjectDN. This attribute isn't a standard LDAP attribute, so to use this property, you have to extend the LDAP schema.
If this property exists in the certmap.conf file, the server searches the entire LDAP directory for an entry whose attribute (named with this property) matches the subject's full DN (taken from the certificate). If the search doesn't find any entries, the server retries the search using the DNComps and FilterComps mappings.
This approach to matching a certificate to an LDAP entry is useful when it's difficult to match entries using DNComps and FilterComps.
- LibraryA property whose value is a pathname to a shared library or DLL. Use this property only if you create your own properties using the certificate API. For more information, see the Sun ONE Application Server Developer's Guide to NSAPI.
- InitFnA property whose value is the name of an init function from a custom library. Use this property only if you create your own properties using the certificate API.
For more information on these properties, refer to the examples described in .
Creating Custom Properties
You can use the client certificate API to create your own properties. For information on programming and using the client certificate API, see the Sun ONE Application Server Developer's Guide to NSAPI.
Once you have a custom mapping, reference the mapping as follows:
<name>:library <path_to_shared_library>
<name>:InitFn <name_of_init_functionFor example:
certmap default1 o=Netscape Communications, c=US
default1:library /usr/netscape/enterprise/auth-db/plugin.so
default1:InitFn plugin_init_fn
default1:DNComps ou o c
default1:FilterComps l
default1:verifycert onSample Mappings
The certmap.conf file should have at least one entry. The following examples illustrate the different ways you can use the certmap.conf file.
Example 1
This example represents a certmap.conf file with only one default mapping:
certmap default default
default:DNComps ou, o, c
default:FilterComps e, uid
default:verifycert onUsing this example, the server starts its search at the LDAP branch point containing the entry ou=<orgunit>, o=<org>, c=<country> where the text in <> is replaced with the values from the subject's DN in the client certificate.
The server then uses the values for the email address and user ID from the certificate to search for a match in the LDAP directory. When it finds an entry, the server verifies the certificate by comparing the one the client sent to the one stored in the directory.
Example 2
This example file has two mappings, one for default and another for the US Postal Service:
certmap default default
default:DNComps
default:FilterComps e, uidcertmap usps ou=United States Postal Service, o=usps, c=US
usps:DNComps ou,o,c
usps:FilterComps e
usps:verifycert onWhen the server gets a certificate from anyone other than the US Postal Service, it uses the default mapping, which starts at the top of the LDAP tree and searches for an entry matching the client's email and user ID. If the certificate is from the US Postal Service, the server starts its search at the LDAP branch containing the organizational unit and searches for matching email addresses. If the certificate is from the USPS, the server verifies the certificate; other certificates are not verified.
Example 3
The following example uses the CmapLdapAttr property to search the LDAP database for an attribute called certSubjectDN whose value exactly matches the entire subject DN taken from the client certificate.
certmap myco ou=My Company Inc, o=myco, c=US
myco:CmapLdapAttr certSubjectDN
myco:DNComps o, c
myco:FilterComps mail, uid
myco:verifycert onIf the client certificate subject is:
uid=Walt Whitman, o=LeavesOfGrass Inc, c=US
the server first searches for entries that contain the following information:
certSubjectDN=uid=Walt Whitman, o=LeavesOfGrass Inc, c=US
If one or more matching entries are found, the server proceeds to verify the entries. If no matching entries are found, the server uses DNComps and FilterComps to search for matching entries.
In this example, the server would search for uid=Walt Whitman in all entries under o=LeavesOfGrass Inc, c=US.
Note This example assumes the LDAP directory contains entries with the attribute certSubjectDN.
ACL/ACE Settings
The following topics are addressed in this section:
- Setting to Allow or Deny
- Setting for User-Group Authentication
- Specifying the From Host
- Setting Access Rights
Setting to Allow or Deny
You can specify the action the server takes when a request matches the access control rule.
- AllowUsers or systems can access the requested resource.
- DenyUsers or systems cannot access the resource.
The server goes through the list of ACEs to determine access permission. For example, the first ACE is usually to deny access to everyone. If continue is not checked, everyone is denied access to the resource.
If the first ACE is set to continue, the server checks the second ACE in the list, and if it matches, goes to the next ACE. The server continues down the list until it reaches either an ACE that doesn't match, or an ACE that matches but is set to not continue. The last matching ACE determines if access is allowed or denied.
Setting for User-Group Authentication
With User-Group authentication, users are prompted to enter a user name and password before they can access the resource specified in the access control rule. The Sun ONE Application Server checks the lists of users and groups stored in your LDAP server.
You can allow or deny access to everyone in the database, you can allow or deny specific people by using wildcard patterns, or you can select who to allow or deny from lists of users and groups.
- Anyone(Default) No authentication is required. Anyone can access the resource without having to enter a user name or password. However, the user might be denied access based on other settings, such as host name or IP address.
- Authenticated people only
All in the authentication databaseAllows a match for any user who has an entry in the database.
Only the following peopleAllows you to specify which users and groups to match. You can list users or groups of users individually by separating the entries with commas, or with a wildcard pattern, or you can select from the lists of users and groups stored in the database. Group matches all users in the groups you specify. User matches the individual users you specify.
- Prompt for authenticationAllows you to enter message text that appears in the authentication dialog box. You can use this text to describe what the user needs to enter. Depending on the operating system, the user will see about the first 40 characters of the prompt. The user name and password are associated them with the prompt text. When the user accesses files and directories of the server having the same prompt, the user names and passwords won't need to be entered again. If you want users to authenticate again for specific files and directories, change the prompt for the ACL on that resource.
- Authentication methodsSpecifies the method the server uses for getting authentication information from the client. Uses the default method you specify in the obj.conf file, or Basic if there is no setting in the obj.conf file.
Basic(Default) Uses the HTTP method to get authentication information from the client. The user name and password are only encrypted if encryption is turned on for the Sun ONE Application Server. Refer to "Basic Authentication" for additional information.
Note The Admin Server offers only the Basic method of authentication.
SSLUses the client certificate to authenticate the user. To use this method, SSL must be turned on for the Sun ONE Application Server. When encryption is on, you can combine Basic and SSL methods. Refer to "SSL Authentication" for additional information.
DigestUses the user name and password without sending the user name and password as cleartext. The browser uses the MD5 algorithm to create a digest value using the user's password and some information provided. Refer to "Digest Authentication" and "Implementing Host-IP Authentication" for additional information.
- Authentication databaseAllows you to select a database the Sun ONE Application Server will use to authenticate users. If you choose Default, the server looks for users and groups in an LDAP directory.
If you want to configure individual ACLs to use different databases, select Other as the authentication method, and choose the database from the drop-down list. Non-default databases and LDAP directories need to have already been specified in the instance_dir/config/dbswitch.conf file.
Specifying the From Host
You can restrict access to the Admin Server or your web site based on which computer the request comes from.
- AnyplaceAllows access to all users and systems.
- Only fromAllows you to restrict access to specific host names or IP addresses.
If you select the Only from option, enter a wildcard pattern or a comma-separated list in the Host Names or IP Addresses fields. Restricting by hostname is more flexible than by IP address: if a user's IP address changes, you won't need to update this list. Restricting by IP address, however, is more reliable: if a DNS lookup fails for a connected client, hostname restriction cannot be used.
You can only use the * wildcard notation for wildcard patterns that match the computers' host names or IP addresses. For example, to allow or deny all computers in a specific domain, you would enter a wildcard pattern that matches all hosts from that domain, such as *.sun.com. You can set different hostnames and IP addresses for superusers accessing the Admin Server.
For more information, refer to "Implementing Host-IP Authentication".
Setting Access Rights
Access rights restrict access to files and directories on your web site. In addition to allowing or denying all access rights, you can specify a rule that allows or denies partial access rights. For example, you can allow users read-only access to your files, so they can view the information, but deny them write access, so they cannot change the files.
- All Access Rights(Default) Allows or denies all rights.
- Only the following rightsAllows you to select a particular combination of rights the following rights to be allowed or denied:
ReadAllows users to view files, including includes the HTTP methods GET, HEAD, POST, and INDEX.
WriteAllows users to change or delete files, including the HTTP methods PUT, DELETE, MKDIR, RMDIR, and MOVE. To delete a file, a user must have both write and delete rights.
ExecuteAllows users to execute server-side applications, such as CGI programs, Java applets, and agents.
DeleteAllows users who also have write privileges to delete files or directories.
ListAllows users to uses INDEX method to access lists of the files in directories.
InfoAllows users to receive information about the URI, for example HEAD.
Referencing ACL Files in the obj.conf File
If you have named ACLs or created separate ACL files, you can reference them in the obj.conf file. 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 the 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"
</ObjectIn 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 ACL name (testacl) to the object in which the directive appears.
The testacl ACL can appear in any ACL file referenced in the init.conf file.
Configuring the ACL User Cache
By default, the Sun ONE Application Server caches user and group authentication results in the ACL user cache. This section describes the ACL user cache directives that are contained in the init.conf file:
ACLCacheLifetime
ACLCacheLifetime determines the number of seconds before cache entries expire. Each time an entry in the cache is referenced, its age is calculated and checked against ACLCacheLifetime. The entry is not used if its age is greater than or equal to the ACLCacheLifetime. If this value is set to 0, the cache is turned off.
If you use a large number for this value, you may need to restart the Sun ONE Application Server when you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the Sun ONE Application Server might be out of sync with the LDAP server for as long as two minutes. If your LDAP is not likely to change often, use a large number. Default value is 120.
ACLUserCacheSize
ACLUserCacheSize determines the number of users in the User Cache. New entries are added to the head of the list; entries at the end of this list are recycled to make new entries when the cache reaches its maximum size.
Default value is 200.
ACLGroupCacheSize
ACLGroupCacheSize determines how many group IDs can be cached for a single UID/cache entry. Unfortunately non-membership of a user in a group is not cached, and will result in several LDAP directory accesses on every request. Default value is 4.
For more information on ACL file directives, see the Sun ONE Application Server Administrator's Configuration File Reference.
Setting Access Control for a Server Instance
You can create, edit, or delete access control for a specific server instance.
To create access control for a server instance, perform the following steps:
- Access App Server Instance and HTTP Server.
- Select ACLs.
The ACLs page displays the existing ACLs.
- Click the ACL File to edit.
The Edit ACL file page is displayed.
   ACL File Page
- Click the Edit ACL File button.
The Access Control List Management page is displayed.
   ACL List Management Page
- Under the Option column choose one:
The Access Control List Management page offers three options.
- Select one of the following:
Pick a resourceTo specify a wildcard pattern for files or directories (such as *.html), choose a directory or a file name to restrict, or browse for a file or directory.
Pick an existing ACLTo select from a list of all the ACLs you have enabled. Existing ACLs you have not enabled will not appear in this list.
Type in the ACL nameTo specify the named ACL.
Note Use this option only if you're familiar with ACL files. You'll need to manually edit the obj.conf file if you want to apply named ACLs to resources.
The following table lists the resource wildcards you can use. The left column lists the resource wildcard and the right column describes its functionality.
- Click Edit Access Control.
The Access Control Rules for: (server instance) appears.
   Access Control Rules
- Verify Access control is on, if not already selected.
- To create or edit the ACL for this server instance, click Deny in the Action column.
- Select Allow, if it isn't already selected as the default, and click Update.
- Click anyone in the Users/Groups column.
The User/Group page appears.
   Access Control User/Group Rules
- Select which users and groups you will allow access to, and click Update.
Clicking List for Group and User will provide lists for you to choose from.
- Click anyplace in the From Host column.
   Access Control From Host Rules
- Enter Host Names and IP Addresses allowed access, and click Update.
- Click on all in the Rights column.
   Access Control Rights Rules
- Select one of the following and then click Update:
- (Optional) Click the x under the Extra column to add a customized ACL expression.
- Put a check in the Continue column, if it isn't already selected as the default.
The server will evaluate the next line before determining if the user is allowed access. When creating multiple lines, work from the most general restrictions to the most specific ones.
- (Optional) Click Response when denied.
Respond with the default file (redirection off)
Respond with the following URL or URI: (redirection on)
- Enter the path to the absolute URL or a relative URI and click update.
- Click Submit to store the new access control rules in the ACL file.
Note Clicking Revert will remove all of the settings you've just created.
- Repeat all steps above for each server instance you want to establish access control for.
- When finished, click Apply.
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
ACL settings can also be enabled on a per virtual server basis. To learn how this is done, see "Editing Access Control Lists for Virtual Servers".
Restricting Access to Areas of Your Server
After you have completed the steps described in "Setting Access Control for a Server Instance", you can take additional measures to restrict areas of your server as described in the following topics:
- Restricting Access to the Entire Server
- Restricting Access to a Directory (Path)
- Restricting Access to a URI (Path)
- Restricting Access to a File Type
- Restricting Access Based on Time of Day
- Restricting Access Based on Security
Restricting Access to the Entire Server
You may want to allow access to users in a group who access the server from a specific subdomain of your network.
To restrict access to the entire server (using the steps described for setting access control for a server instance), perform the following steps:
- Access App Server Instance and HTTP Server.
- Select ACLs.
The ACLs page displays the existing ACLs.
- Click the ACL File to edit.
- Click the Edit ACL File button.
The Access Control List Management page is displayed.
- Pick the entire server resource, and click Edit Access Control.
- Add a new rule to deny access to all.
- Add another new rule to allow access to a specific group.
- Enter a wildcard pattern for the host names of the computers to be allowed.
For example, *.employee.sun.com
- Unselect Continue.
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
Restricting Access to a Directory (Path)
You can allow users in a group to read or run applications in directories, and its subdirectories and files, that are controlled by an owner of the group. For example, a project manager might update status information for a project team to review.
To restrict access to a directory on the server (using the steps described for setting access control for a server instance), perform the following steps:
- Access App Server Instance and HTTP Server.
- Select ACLs.
The ACLs page displays the existing ACLs.
- Click the ACL file to edit.
- Click the Edit ACL File button.
The Access Control List Management page is displayed.
- Browse the Pick a Resource section and select the directory you want to restrict.
The directories in the server's document root are displayed. Once selected, the Editing drop-down list displays the absolute path to the directory.
Note If you want to view all files in your server root, click Options, then check List files as well as directories.
- Click Edit Access Control.
- Create a new rule and leave the defaults to deny access to everyone from everywhere.
- Create another new rule allowing users in a specific group to have read and execute rights only.
- Create a third line to allow a specific user to have all rights.
- Unselect Continue for the second and third lines and click Update.
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
An absolute path to the file or directory is created in the docroot directory. An entry similar to the following would appear in the ACL file: acl "path=d:/Sun/suitespot/docroot1/sales/";
Restricting Access to a URI (Path)
You can use a URI to control access to a single user's content on the server. URIs are paths and files relative to the server's document root directory. Using URIs is an easy way to manage your server's content if you frequently rename or move all or part of it (for example, for disk space). It's also a good way to handle access control if you have additional document roots.
To limit access to a URI (using the steps described for setting access control for a server instance), perform the following steps:
- Access App Server Instance and HTTP Server.
- Select ACLs.
The ACLs page displays the existing ACLs.
- Click the ACL file to edit.
- Click the Edit ACL File button.
The Access Control List Management page is displayed.
- Enter the URI you want to restrict in the Type in the ACL name section.
For example: uri=/my_directory.
- Click Edit Access Control.
- Create a new rule to allows all users read access.
- Create another new rule to allow access for the owner of the directory.
- Uncheck Continue for both the first and second rules.
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
A path for the URI is created relative to the document root. The entry in the ACL file would appear as follows: acl "uri=/my_directory";
Restricting Access to a File Type
You can limit access to file types on your server or web site. For example, you might want to allow only specific users to create programs that run on your server. Anyone would be able to run the programs, but only specified users in the group would be able create or delete them.
To limit access to a file type (using the steps described for setting access control for a server instance), perform the following steps:
- Access App Server Instance and HTTP Server.
- Select ACLs.
The ACLs page displays the existing ACLs.
- Click the ACL file to edit.
- Click the Edit ACL File button.
The Access Control List Management page is displayed.
- Click Wildcard in the Pick a resource section and enter a wildcard pattern.
For example, *.cgi.
- Click Edit Access Control.
- Create a new rule to allow read access to all users.
- Create another rule that allows write and delete access only to a specified group.
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
For file type restriction, you would leave both continue boxes checked. If a request for a file comes in, the server will then check the ACL for the file type first.
A Pathcheck function is created in the obj.conf file that may include wildcard patterns for files or directories. The entry in the ACL file would appear as follows: acl "*.cgi";
Restricting Access Based on Time of Day
You can restrict write and delete access to the server or during specified hours or on specified days. You might use this to prevent people from publishing documents during working hours when people might be accessing the files.
To limit access based on time of day (using the steps described for setting access control for a server instance), perform the following steps:
- Access App Server Instance and HTTP Server.
- Select ACLs.
The ACLs page displays the existing ACLs.
- Click the ACL file to edit.
- Click the Edit ACL File button.
The Access Control List Management page is displayed.
- Select the entire server from the drop-down list in Pick a Resource and click Edit Access Control.
- Create a new rule allowing read and execute rights to all.
This means that if a user wants to add, update, or delete a file or directory, this rule won't apply and the server will search for another rule that matches.
- Create another new rule denying write and delete rights to all.
- Click X link to create a customized expression.
- Enter the days of the week and the times of day to be allowed. For example:
user = "anyone" and
dayofweek = "sat,sun" or
(timeofday >= 1800 and
timeofday <= 600)
The Unrecognized Expressions message will be displayed in the Users/Groups and From Host fields when you create a custom expression.
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
Any errors in the custom expression will generate an error message. Make corrections and submit again.
Restricting Access Based on Security
You can configure SSL and non-SSL HTTP Listeners for the same server instance. Restricting access based on security allows you to create protection for resources that should only be transmitted over a secure channel.
To limit access based on security (using the steps described for setting access control for a server instance), perform the following steps:
- Access App Server Instance and HTTP Server.
- Select ACLs.
The ACLs page displays the existing ACLs.
- Click the ACL file to edit.
- Click the Edit ACL File button.
The Access Control List Management page is displayed.
- Select the entire server from the drop-down list in Pick a Resource and click Edit Access Control.
- Create a new rule allowing read and execute rights to all.
This means that if a user wants to add, update, or delete a file or directory, this rule won't apply and the server will search for another rule that matches.
- Create another new rule denying write and delete rights to all.
- Click X link to create a customized expression.
- Enter ssl="on". For example:
user = "anyone" and ssl="on"
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
Any errors in the custom expression will generate an error message. Make corrections and submit again.
Turning Off Access Control
When you uncheck the option labeled Access Control Is On, you'll receive a prompt asking if you want to erase records in the ACL. When you click OK, the server deletes the ACL entry for that resource from the ACL file.
If you want to deactivate an ACL, you can comment out the ACL lines in the generated-server-id.acl file by putting a # sign at the beginning of each line.
Responding When Access is Denied
The Sun ONE Application Server provides the following default message when access is denied:
FORBIDDEN. Your client is not allowed access to the restricted object.
You can choose a different response, or you can create a different message for each access control object.
To change the message sent for a particular ACL, perform the following steps:
- In the ACL page, click the Response when denied link
- In the lower frame, check Respond with the following file.
- Enter the path to the absolute URL or a relative URI and click update.
Make sure users have access to the URL or URI they are redirected to.
- Click Update.
- Click Submit in the top frame to submit the access control rule.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
Controlling Access for Virtual Servers
Access control information in Sun ONE Application Server can come from a per-virtual server ACL file and htaccess files in the document directories.
Your server.xml file can contain one or more acl tags which define an ID associated to a particular standard ACL file. For example:
<acl id="standard" file="standard.acl">
For virtual servers to use access control, you must create a reference to one or more ACL file IDs in their acls attribute. Example:
<virtual-server acls="standard">
This configuration allows multiple virtual servers to share the same ACL file. If you want to require user-group authentication for a virtual server, you must add one or more auth-db tags to its definition. These auth-db tags create a connection between the database names in your ACL file and the actual databases found in dbswitch.conf.
The following example maps the ACLs with no `database' attribute to the `default' database in dbswitch.conf file.
<virtual-server>
<auth-db id="default" database="default"/>
</virtual-server>The following topics address virtual server access:
Accessing Databases from Virtual Servers
You can globally define user authentication databases in the dbswitch.conf file, which is only read at server startup. The baseDN of the LDAP URL in the dbswitch.conf file defines the global root of all accesses to the database. This maintains backward compatibility. For most new installations, the baseDN is empty. You can also use the Administration interface to set up authentication databases for your virtual servers.
Note When you use the App Server Instance->Security->Configure Directory Service page in Administration interface to configure the directory, the dbswitch.conf file is updated.
The following sections provide instructions:
- Using the dbswitch.conf File
- Creating a New Authentication Database
- Specifying Databases in the User Interface
Using the dbswitch.conf File
The dcsuffix attribute for LDAP databases in dbswitch.conf defines the root of the DC tree according to the Sun ONE Directory Server schema. It is relative to the baseDN in the LDAP URL. When the dcsuffix attribute is present, the LDAP database is Sun ONE Directory Server schema compliant, and the behavior of some operations changes. For more information about the Sun ONE Directory Server schema, and an example, see the Sun ONE Application Server Developer's Guide to NSAPI.
For every virtual server, you can define one or more auth-db blocks that point to one of the directories, and you can define additional information. The auth-db blocks ID can be referenced in the database parameter of the ACL. If a virtual server has no auth-db blocks, user or group-based ACLs will fail.
auth-db tags define an additional layer of indirection between the database attribute of an ACL and the dbswitch.conf file. This layer of indirection adds the necessary protection for the server administrator to have full control over which databases the virtual server administrators have access to.
For more information on auth-db, see the Sun ONE Application Server Developer's Guide to NSAPI.
Creating a New Authentication Database
To create a new authentication database in the Administration interface, perform the following steps:
- Access App Server Instances and HTTP Server in the left pane.
- Access Virtual Servers and open the virtual server you want (expand the node).
- Under the virtual server in the left pane, click Authentication Databases.
The Authentication Databases page lists the current databases.
- To create a new authentication database, click New.
The Authentication Databases New page is displayed.
- Enter the information as described in the online help.
- Click OK.
- Access App Server Instances and your server instance in the left pane, and click Apply Changes.
- Stop and start the server for changes to take effect.
Specifying Databases in the User Interface
After you have created one or more user authentication databases in the dbswitch.conf file, or using the Administration interface, you can use the Administration interface to configure which databases each of your virtual servers will use for authentication. You can also use the Administration interface to add a newly-created database definition from the dbswitch.conf file for the virtual server to authenticate against. This is done by associating the newly-created authentication database with an ACL and using the ACL with the virtual server.
Editing Access Control Lists for Virtual Servers
ACLs for virtual servers are created for the server instance that the virtual server resides in. Virtual server ACL settings default to those created for the server instance. However, you can choose to define a new ACL or edit an existing one.
To edit an existing ACL for a virtual server, perform the following steps:
- Access App Server Instances and HTTP Server in the left pane.
- Select ACLs and click the ACL you want to edit.
- Click Edit ACL File
- Under A. Pick a Resource, click Edit Access Control.
The Access Control Rules table is displayed.
- Edit the information as described in the online help.
- Access App Server Instances and HTTP Server.
- Select Virtual Server and click the server instance.
- On the edit page, under the section where the ACLs are listed, choose whichever ACL you want to associate with the virtual server.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
Using htaccess Files
Server content is seldom managed entirely by one person. You may need to allow end users to access a subset of configuration options so that they can configure what they need to, without giving them access to the Sun ONE Application Server. The subset of configuration options is stored in dynamic configuration files.
The Sun ONE Application Server supports htaccess dynamic configuration files. You can enable htaccess files either through the user interface or by manually changing the configuration files. The htaccess plug-in is in the install_dir/lib directory.
You can use htaccess files in combination with the server's standard access control. The standard access controls are always applied before any htaccess access control, regardless of the ordering of PathCheck directives.
This section addresses the following topics:
- Enabling htaccess from the User Interface
- Enabling htaccess from init.conf
- Using htaccess-register
- Supported htaccess Directives
Enabling htaccess from the User Interface
To configure your Sun ONE Application Server to use htaccess, perform the following steps:
- Under your App Server Instance, Access HTTP Server and Virtual Servers.
- Select a virtual server instance.
- Select the Doc Directories tab.
The Additional Documentation Directories page is displayed.
   Virtual Server Doc Directories Page
- Click the htaccess Configuration link.
The htaccess Configuration page is displayed.
   Virtual Server htaccess Configuration Page
- Select the server to edit by:
Choosing the entire server or a specific server from the drop-down list
Choosing the directory and files to edit by clicking Browse
Choosing a wildcard pattern to edit by clicking Wildcard
- Select Yes to activate.htaccess.
- Enter the file name where you want the htaccess configuration to be added.
- Click OK.
- Access App Server Instances and your server instance in the left pane, then click Apply Changes.
- Stop and start the server for changes to take effect.
Enabling htaccess from init.conf
To manually enable your server to use the .htaccess, you need to first modify the server's init.conf file to load, initialize, and activate the plug-in.
- Open init.conf in the instance_dir/config directory.
- After the other initialization directives, add the following lines:
For UNIX:
Init fn="load-modules" funcs="htaccess-init,htaccess-find,htaccess-register"
shlib="install_dir/lib/htaccess.so" NativeThread="no"
Init fn="htaccess-init"For Windows:
Init fn="load-modules" funcs="htaccess-init,htaccess-find,htaccess-register"
NativeThread="no"
Init fn="htaccess-init"
- (Optional) Edit the final line to read:
Init fn="htaccess-init"[groups-with-users=yes]
- Click File/Save.
- Open obj.conf file.
- Add the PathCheck directive as the last directive in the object.
To activate htaccess file processing for all directories managed by a virtual server, add the PathCheck directive to the default object in the obj.conf file:
<Object name="default">
...
PathCheck fn="htaccess-find"
</Object>
htaccess processing should be the last PathCheck directive in the object.
To activate htaccess processing for particular server directories, place the PathCheck directive in the corresponding definition in init.conf.
- To name your htaccess files something other than htaccess, you must specify the file name in the PathCheck directive using the following format:
Subsequent access to the server will be subject to htaccess access control in the specified directories. For example, to restrict write access to htaccess files, create a configuration style for them, and apply access control to that configuration style. For more information, see Applying Configuration Styles.
Using htaccess-register
The htaccess-register allows you to create your own authentication methods. Like Apache, you can create external authentication modules and plug them into the htaccess module using htaccess-register.
You can use external modules to create one or more new directives. For example, you might specify the user database for authentication. The directives may not appear within <Limit> or <LimitExcept> tags.
The following example shows an htaccess file:
<Limit> GET POST
order deny,allow
deny from all
allow from all
</Limit>
<Limit> PUT DELETE
order deny,allow
deny from all
</Limit>
AuthName mxyzptlk.kawaii.com
AuthUserFile /server_root/mxyz-docs/service.pwd
AuthGroupFile /server_root/mxyz-docs/service.grpSupported htaccess Directives
The following topics address the htaccess directives that are supported by the Sun ONE Application Server:
allow
Allows access to the specified hosts. Normally appears inside a <Limit> range.
Syntax
allow from_host
where:
from_hostis all, to allow access from all client hosts
from_hostis all or the last part of a DNS host name
from_hostis a full or partial IP address
Does not need to be enclosed within a <Limit> or <LimitExcept> range but usually is.
deny
Denies access to the specified host(s). Normally appears inside a <Limit> range.
Syntax
deny from_host
where:
from_host is all, to deny access from all client hosts
from_host is all or the last part of a DNS host name
from_host is a full or partial IP address
Does not need to be enclosed in a <Limit> <LimitExcept> range but usually is.
AuthGroupFile
Specifies that the named group file to be used for any group definitions referenced in a require group directive. If the file name specified in an AuthGroupFile directive is the same as the file name in an AuthUserFile directive, the file is assumed to contain users and groups in the format:
username:DES-encrypted-password:comma-separated-list-of-groups
Syntax
AuthGroupFile file_name
where:
file_name is the name of file containing group definitions in this form: groupname: user user
Must not appear within a <Limit> or <LimitExcept> range.
AuthUserFile
Specifies that the named user file is to be used for any user names referenced in a require user or require valid-user directive.
Note that the use of groups-with-users=yes in the Init fn=htaccess-init directive in obj.conf, or specifying an AuthGroupFile directive with the same file name, causes that file to be assumed to be in the format:
username:DES-encrypted-password:comma-separated-list-of-groups
Syntax
AuthUserFile filename
where:
filename is the name of file containing user definitions in this form: username:password
where:
username is a user login name, and password is the DES-encrypted password.
Must not appear within a <Limit> or <LimitExcept> range.
AuthName
The authentication realm string typically appears in the prompt for user name and password on the client side. It may affect caching of user name and password on the client.
Syntax
AuthName authentication_realm
where
authentication_realm is a string identifying an authorization realm to be associated with any request for user authentication.
Must not appear within a <Limit> or <LimitExcept> range.
AuthType
Specifies the user authentication method as HTTP Basic Authentication, the only method currently supported.
Syntax
AuthType Basic
Must not appear within a <Limit> or <LimitExcept> range.
<Limit>
Applies the enclosed directives only for requests using the specified HTTP methods.
Syntax
<Limit method method ...>
allow, deny, order, or require directives
</Limit>
where
method is an HTTP method such as GET, POST, or PUT. Any method that the web server understands can be used here.
<LimitExcept>
Applies the enclosed directives only for requests types not matching the specified HTTP methods.
Syntax
<LimitExcept method method ...>
allow, deny, order, or require directives
</LimitExcept>
where
method is an HTTP method such as GET, POST, or PUT. Any method that the web server understands can be used here.
order
- Allows, denies, evaluates allow directives, and then deny directives.
- Denies, allows, evaluates deny directives, and then allow directives.
- Mutual-failure denies access for a host listed in both allow and deny directives, regardless of their ordering.
Syntax
order ordering
where
Does not need to be enclosed within a <Limit> or <LimitExcept> range, but usually is.
require
- Requires group requires the authenticated user to be a member of one of the specified groups.
- Requires user requires the authenticated user to be one of the specified users.
- Requires valid-user requires an authenticated user
Syntax
requires group groupname groupname
requires user username username
requires valid-user
Does not need to be enclosed within a <Limit> or <LimitExcept> range, but usually is.