Sun Java System Web Server 6.1 SP9 Administrator's Guide

What Is Access Control?

Access control allows you to determine:

You can control access to the entire server or to parts of the server, or to files and directories on your web site. You create a hierarchy of rules called access control entries (ACEs) to allow or deny access. 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 server has one ACL file that contains multiple ACLs. After determining which virtual server to use for an incoming request, the Sun Java System Web Server checks if any ACLs are configured for that virtual server. If ACLs are found that apply for the current request, the Sun Java System Web Server evaluates their ACEs to determine whether access should be granted or denied.

Note –

If there are more than one ACLs that match, the server uses the last statement that matches. The defaultACL is bypassed since the uri ACL is the last statement that matches.

You allow or deny access based on:

Setting Access Control for User-Group

You can limit the access to your web server to certain users or groups. User-Group access control requires users to enter a username and password before gaining access to the server. The server compares the information in a client certificate, or the client certificate itself with a directory server entry.

The Administration Server uses only the basic authentication. If you wish to require client authentication on your Administration Server, you must manually edit the ACL files in obj.conf changing the method to SSL.

User-Group authentication is performed by the directory service configured for a server. For more details, see the section Configuring a Directory Service. The information that a directory service uses to implement access control can come from either of the following sources:

When the server uses an external LDAP-based directory service, it supports the following types of User-Group authentication methods for server instances:

When the server uses an internal file-based directory service, the User-Group authentication methods for server instances it supports include:

User-Group authentication requires users to verify their identity before they are able access to the Administration Server, or files and directories on the web site. During authentication, users enter username and password, using a client certificate, or digest authentication plug-in. To use a client certificate you require encryption. For information on encryption and using client certificates, see Chapter 5, J2SE-based Security for Web Container and Web Applications.

Default Authentication

Default authentication is the preferred authentication method. The Default setting uses the default method in the obj.conf file, or “Basic” if there is no setting in the obj.conf file. If you select Default, the ACL rule does not 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.

Basic Authentication

Basic authentication is selected by default and requires users to enter a username and password to access the web server or web site. You must create and store a list of users and groups in an LDAP database, such as the Sun Java System Directory Server, or in a file. You must use either a directory server installed on a different server root than your web server, or a directory server installed on a remote machine.

When users attempt to access a resource that has User-Group authentication in the Administration Server or on your web site, the web browser displays a dialog box asking the user to enter a username and password. The server receives the information either encrypted or unencrypted, depending on whether encryption is turned on for the server.

Note –

If you use the Basic Authentication setting without SSL encryption, the username and password are sent as unencrypted text across the network. The network packets could be intercepted, and the username and password could be misused. Basic authentication is most effective when combined with SSL encryption, Host-IP authentication, or both. Use Digest Authentication to avoids this problem.

The following dialog appears when users authenticate their identity:

Figure 9–1 Example of Username and Password Prompt

Example of Username and Password Prompt

After you click OK, the following process is followed:

You can customize the access denied message received by unauthorized users using the Access Denied Response page.

SSL Authentication

The server can confirm users’ identities using security certificates in the following ways:

When you configure the server to use certificate information for authenticating the client, the server:

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. If you set the server’s access control to use the SSL method for authentication of users and groups, the client needs to:

When you require client authentication with access control, you need to have SSL ciphers enabled for your web server. See Chapter 7, Using Certificates and Keys to learn how to enable SSL.

In order to successfully gain access to an SSL authenticated resource, the client certificate must be from a CA trusted by the web server. The client certificate needs to be published in a directory server if the web 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 only compare selected information from the certificate to the directory server entry. For example, you could configure the certmap.conf file to only compare 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 Chapter 7, Using Certificates and Keys.

Note –

Only the SSL authentication method requires you to modify the certmap.conf file, because the certificate is checked against the LDAP directory. Requiring client authentication for all connections to the server does not. If you choose to use client certificates, you should increase the value of the AcceptTimeout directive in magnus.conf.

Digest Authentication

The Sun Java System Web Server 6.1 can be configured to perform digest authentication using either an LDAP-based or a file-based directory service.

Digest authentication allows the user to verify identity based on username and password without sending the username and password as cleartext. The browser uses the MD5 algorithm to create a digest value using the user’s password and some information provided by the Web Server.

When the server uses an LDAP-based directory service to perform digest authentication, this value is also computed on the server using the Digest Authentication plug-in, and is there compared against the digest value provided by the client. If the digest values match, the user is authenticated. In order for this process to work, the directory server needs access to the user’s password in cleartext. The Sun Java System Directory Server includes a reversible password plug-in using a symmetric encryption algorithm to store data in an encrypted form, that can later be decrypted to its original form. Only the Directory Server holds the key to the data.

For LDAP-based digest authentication, you need to enable the reversible password plug-in and the digestauth-specific plug-in included with Sun Java System Web Server 6.1. To configure the web server to process digest authentication, set the digestauth property of the database definition in dbswitch.conf.

The server tries to authenticate against the LDAP database based upon the ACL method specified, as shown in Digest Authentication. If you do not specify an ACL method, the server will use either digest or basic when authentication is required, or basic if authentication is not required. This is the preferred method.

Table 9–1 Digest Authentication Challenge Generation

ACL Method  

Digest Authentication Supported by Authentication Database  

Digest Authentication Not Supported by Authentication Database  


none specified 

digest and basic 








When processing an ACL with method = digest, the server attempts to authenticate by:

Installing the Digest Authentication Plug-in

For digest authentication using an LDAP-based directory service, you need to install the digest authentication plug-in. This plug-in computes a digest value on the server side, and compares this against the digest value provided by the client. If the digest values match, the user is authenticated.

If you’re using a file-based authentication database, you don’t need to install the digest authentication plug-in.

Installing the Digest Authentication Plug-in on UNIX

The Digest Authentication plug-in consists of a shared library found in the following files:

ProcedureTo install the Digest Authentication plug-in on UNIX

  1. Make sure this shared library resides on the same server machine that the Sun Java System Directory Server is installed on.

  2. Make sure you know the Directory Manager password.

  3. Modify the libdigest-plugin.ldif file changing all references to the /path/to to the location where you installed the digest plug-in shared library.

    Note –

    libdigest-plugin.ldif is available at server-root/plugins/digest/libdigest-plugin.ldif.

  4. To install the plug-in, enter the following command:

    % ldapmodify -D "cn=Directory Manager" -w password -a < libdigest-plugin.ldif

Installing the Digest Authentication Plug-in on Windows

You need to copy several .dll files from the Sun Java System Web Server installation to your Sun Java System Directory Server server machine in order for Sun Java System Directory Server to start properly with the Digest plug-in.

ProcedureTo install the Digest Authentication plug-in on Windows

  1. Access the shared libraries on the Sun Java System Web Server installation in:


  2. Copy the following files:

    • The nsldap32v50.dll file

      • The libspnr4.dll file

      • The libplds4.dll file

  3. Paste them into either:

    • \Winnt\system32

      • Sun Java System Directory Server install directory: [server_root]\bin\sldap\server

Setting the Sun Java System Directory Server to Use the DES Algorithm

The DES algorithm is needed to encrypt the attribute that stores the digest password.

ProcedureTo configure the Sun Java System Directory Server to use the DES algorithm

  1. Launch the Sun Java System Directory Server Console.

  2. Open your iDS 5.0 instance.

  3. Select the Configuration tab.

  4. Click on the + sign next to plug-ins.

  5. Select the DES plug-in.

  6. Choose Add to add a new attribute.

  7. Enter iplanetReversiblePassword.

  8. Click Save.

  9. Restart your Sun Java System Directory Server instance.

    Note –

    The iplanetReversiblePasswordobject attribute stores the password for digest authentication. To set a digest authentication password in the iplanetReversiblePassword attribute for a user, your entry must include the iplanetReversiblePasswordobject object.

Other Authentication

You can create a custom authentication method using the access control API.

Setting Access Control for Host-IP

You can limit access to the Administration Server files, and directories on your web site by making them available only to clients using specific computers. You specify hostnames or IP addresses for the computers that you want to allow or deny. You can use wildcard patterns to specify multiple computers or entire networks. Access to a file or directory using Host-IP authentication appears easier to the user. Users can access the files and directories immediately without entering a username or password.

Since more than one person might use a specific computer, Host-IP authentication is more effective when combined with User-Group authentication. If both methods of authentication are used, a username and password are required for access.

Host-IP authentication does not require DNS to be configured on your server. If you choose to use Host-IP authentication, you must have DNS running on your network and your server must be configured to use it. You can enable DNS on your server through the Performance Tuning page in the Preferences tab on your Server Manager.

Enabling DNS degrades the performance of Sun Java System Web Server since the server is forced to perform DNS look-ups. To reduce the effect of DNS look-ups on your server’s performance, resolve IP addresses only for access control and CGI instead of resolving the IP address for every request. To do this, iponly=1 to AddLog fn="flex-log" name="access" in the obj.conf file:

AddLog fn="flex-log" name="access" iponly=1

Using Access Control Files

When you use access control on the Administration Server or the files or directories on your web site, the settings are stored in a file with a .acl extension. Access control files are stored in the directory install_dir/httpacl directory with install_dir being the location where the server is installed. For example, if you installed the server in /usr/Sun/Servers, the ACL files for both the Administration Server and each server instance configured on your server would be located in /usr/Sun/Servers/httpacl/.

The main ACL file name is generated-https-server-id.acl; the temporary working file is called genwork-https-server-id.acl. These two files are present on your system if you use Sun Java System Administration Server to configure access. To create more complex restrictions, create multiple files, and reference these files from the server.xml file. Some features becomes available when you edit the files such as restricting access to the server based on the time of day or day of the week.

You can also manually create and edit .acl files to customize access control using APIs. For more information on using access control APIs, see the Sun Java System Web Server 6.1 SP9 Programmer’s Guide.

For more information on access control files and their syntax, see Appendix C, ACL File Syntax.

Configuring the ACL User Cache

By default, the Sun Java System Web Server caches user and group authentication results in the ACL user cache. You can control the amount of time that ACL user cache is valid by using the ACLCacheLifetime directive in the magnus.conf file. 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. The default value is 120 seconds. Setting the value to 0 (zero) turns the cache off. If you use a large number for this value, you may need to restart the Sun Java System Web Server every time you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the Sun Java System Web Server might be out of sync with the LDAP directory for as long as two minutes. Only set a large value if your LDAP directory is not likely to change often.

Using the magnus.conf parameter for the ACLUserCacheSize, you can configure the maximum number of entries that can be held in the cache. The default value for this parameter is 200. New entries are added to the head of the list, and entries at the end of this list are recycled to accommodate new entries when the cache reaches its maximum size.

You can also set the maximum number of group memberships that can be cached for each user entry using the magnus.conf parameter, ACLGroupCacheSize. The default value for this parameter is four. Unfortunately non-membership of a user in a group is not cached, and will result in several LDAP directory accesses on every request.

For more information on ACL file directives, see the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide.