Sun Java System Web Server 7.0 Administrator's Guide

Chapter 7 Controlling Access to Your Server

You can protect resources that reside on your web server through several security services and mechanisms, including authentication, authorization, and access control. This chapter describes some of the supported mechanisms for controlling access to your Sun Java System Web Server 7.0.

What is Access Control

Authentication is the process of confirming an identity. Authorization means granting access to a restricted resource to an identity, and access control mechanisms enforce these restrictions. Authentication and authorization can be enforced by a number of security models (Web application security, htaccess, Authentication Realm and more) and services.

Access control allows you to determine:

You can control access to the entire server or to parts of the server, or the files or directories on your web site. You create a hierarchy of rules called access control entries (ACEs) to allow or deny access. 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 the virtual server to use for an incoming request, 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 server evaluates their ACEs to determine whether access should be granted or denied.

You allow or deny access based on:

How Access Control Works

When the server gets 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 the LDAP directory.

Note –

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

Sun Java System Web Server 7.0

The above figure depicts how access control works in Web Server 7.0. The user agent (client) accesses the Web Server. The Web Server executes PathCheck directives in obj.conf file. The Web Server returns an HTTP 401 (unauthorized) to the client. The client prompts the user for authentication. In case if the client is a browser, it pops up a login dialog box. The user enter the login information. The Web Server executes an internal check-acl function. The Web Server validates the user credentials and processes the request.

Setting Up Access Control for User-Group

You can limit 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 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 changing the method to SSL.

User-Group authentication is performed by Web Server by reading entries in the user group database. 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 are:

User-Group authentication requires users to authenticate themselves before getting access to the server, or the files and directories on your web site. With authentication, users verify their identity by entering a username and password, using a client certificate. Client certificates are required only for SSL communication.

Default Authentication

Default authentication is the preferred method. The Default setting uses the default method in the server.xml file, or “Basic” if there is no setting in server.xml. If you check Default, 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.

Basic Authentication

Basic authentication requires users to enter a username and password to access your web server or web site. It is the default setting. 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 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 this information encrypted or unencrypted, depending on whether encryption is turned on for your server.

Note –

Using Basic Authentication without SSL encryption, sends the username and password in un-encrypted text across the network. The network packets could be intercepted, and the username and password could be pirated. Basic authentication is most effective when combined with SSL encryption, Host-IP authentication, or both. Using Digest Authentication avoids this problem.

SSL Authentication

The server can confirm users’ identities with security certificates in two ways:

When you set 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 will need to:

When you require client authentication with access control, you need to have SSL ciphers enabled for your web server.

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.

Note –

Only the SSL authentication method requires modification to 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 server can be configured to perform digest authentication using either an LDAP-based or a file-based directory service.

Digest authentication allows the user to authenticate 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 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. In order for this to work, your directory server needs access to the user’s password in cleartext. 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 the server. To configure your web server to process digest authentication, set the digestauth property of the database definition in dbswitch.conf.

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

Setting Access Control for Host-IP

You can limit access to the Administration Server, or the files and directories on your web site by making them available only to clients using specific computers. You specify host names 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 seamless to the user. Users can access the files and directories immediately without entering a username or password.

Since more than one person may use a particular computer, Host-IP authentication is more effective when combined with User-Group authentication. If both methods of authentication are used, a username and password will be 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 in 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 the server since the server is forced to do DNS look ups. To reduce the effects 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 your obj.conf file:

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

Configuring the ACL User Cache

By default, the 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 server every time you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the 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 of 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 make new entries when the cache reaches its maximum size.

You can also set the maximum number of group memberships that can be cached per user entry using the magnus.conf parameter, ACLGroupCacheSize. The default value for this parameter is 4. 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 NSAPI Developer’s Guide.

Setting ACL Cache Properties

For setting ACL cache properties through CLI, execute the following command.

wadm> set-acl-cache-prop --user=admin --password-file=admin.pwd --host=serverhost 
--port=8989 --config=config1 property=value

See CLI Reference, set-acl-cache-prop(1).

The valid properties you can set are:

Configuring Access Control

The server supports authentication and authorization through the use of locally stored access control lists (ACLs), which describe what access rights a user has for a resource. For example, an entry in an ACL can grant a user named John read permission to a particular folder, misc.

This section describes the process of restricting access to the files or directories on your web site. You can set global access control rules for all servers, and also individually for specific servers. For instance, a human resources department might create ACLs allowing all authenticated users to view their own payroll data, but restrict access to updating data to only human resource personnel responsible for payroll.

The core ACLs supported by the server are three types of authentication: basic, SSL, and digest.

For editing access control settings, perform the following tasks:

  1. Click Configurations tab and select the configuration.

  2. Click Security sub tab > Access Control sub tab.

  3. Click Add ACL button to add a new ACL or click existing ACL to edit the settings.

Adding an Access Control List (ACL)

The following section describes the process of adding a new ACL to the configuration.

  1. Click Configurations tab and select the configuration.

  2. Click Access Control sub tab > Access Control Lists sub tab.

  3. Click New button to add a new ACL.

Configure the following parameters:

Table 7–2 ACL Parameters




Named/URI/Path. Select the type of resource you need to set access restriction and specify the value. Example for URI resource — “/sales”. Example for Path resource — “/usr/sun/server4/docs/cgi-bin/*”. 

Authentication DB

Authentication Database lets you select a database the server will use to authenticate users.

The default is keyfile

Authentication Method

  1. Basic — uses the HTTP Basic method to get authentication information from the client. The username and password are only encrypted over the network if SSL is turned on for the server.

  2. SSL — uses the client certificate to authenticate the user. To use this method, SSL must be turned on for the server. When encryption is on, you can combine Basic and SSL methods.

  3. Digest — uses an authentication mechanism that provides a way for a browser to authenticate based on username and password without sending the username and password as clear text. The browser uses the MD5 algorithm to create a digest value using the user’s password and some information provided by the Web Server. Note that in order to use Digest the underlying auth-db must support digest as well. This means either a File auth-db using digestfile or an LDAP auth-db only if the Digest Authentication Plug-in has been installed

  4. Other — uses a custom method created using the access control API.

Prompt for Authentication

Prompt for Authentication option allows 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 browser, the user will see about the first 40 characters of the prompt.

Web browsers typically cache the username and password, and associate them with the prompt text. When the user accesses files and directories of the server having the same prompt, the usernames and passwords won’t need to be entered again. If you want users to authenticate again for specific files and directories, you simply need to change the prompt for the ACL on that resource. 

Denied Access Response

Specify the response action when an access to a resource is denied. 

1. Respond with default message — Select this option for displaying the standard access denied message from the server. 

2. Respond with URL — Select this option for forwarding the request to any other external URL or error page. 

Note –

Using CLI

For adding an ACL through CLI, execute the following command.

wadm> set-acl --user=admin --password-file=admin.pwd 
--host=serverhost --port=8989 --vs=config1_vs_1 --config=config1 

See CLI Reference, set-acl(1).

Adding an Access Control Entry (ACE)

The section describes the process of adding a new Access Control Entry (ACE) for the selected configuration.

  1. Click Configurations tab and select the configuration.

  2. Click Access Control sub tab > Access Control List sub tab.

  3. Click New button.

  4. Click New button under Access Control Entry.

Configure the following ACE parameters:

Table 7–3 ACE parameters




  • Allow means users or systems can access the requested resource

  • Deny means users or systems cannot access the resource

    The server goes through the list of access control expressions (ACEs) to determine the access permissions.


1. Anyone — No authentication. Grants access to everyone.

2. All in the Auth DB — Grants access to all users specified in the authentication database.

3. Only the following in the Auth DB — Restrict access to selected users from the authentication DB.

You can query the authentication DB based on common attributes like First name, Last name and Email address. 


With group authentication, users are prompted to enter a username and password before they can access the resource specified in the access control rule. 

Use this option to restrict access to specific groups. 

From Host

You can restrict access to the Administration Server or your web site based on which computer the request comes from. 

You can restrict access to the Administration Server or your web site based on which computer the request comes from. 

  • Anyplace allows access to all users and systems

  • Only from allows 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 will enter a wildcard pattern that matches all hosts from that domain, such as * You can set different hostnames and IP addresses for superusers accessing the Administration Server.

For hostnames, the * must replace an entire component of the name. That is, * is acceptable, but * is not. When the * appears in a hostname, it must be the left-most character.

For example, * is acceptable, but users.*.com is not. For the IP address, the * must replace an entire byte in the address. For example, 198.95.251.* is acceptable, but* is not. When the * appears in an IP address, it must be the right-most character. For example, 198.* is acceptable, but not 198.*.251.30.


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 allow users read-only access rights to your files, so they can view the information, but not change the files. 

  • All Access Rights is the default and will allow or deny all rights

  • Only the following rights allow you to select a combination of rights to be allowed or denied:

    • Read allows users to view files, including includes the HTTP methods GET, HEAD, POST, and INDEX

    • Write allows 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

    • Execute allows users to execute server-side applications, such as CGI programs, Java applets, and agents

    • Delete allows users who also have write privileges to delete files or directories.

    • List allows users to access lists of the files in directories that do not contain an index.html file.

    • Info allows users to receive information about the URI, for example http_head.


The server goes through the list of access control expressions (ACEs) to determine the access permissions. For example, the first ACE is usually to deny everyone. If the first ACE is set to “continue,” the server checks the second ACE in the list, and if it matches, the next ACE is used. 

If continue is not checked, everyone will be denied access to the resource. The server continues down the list until it reaches either an ACE that doesn’t match, or that matches but is set to not continue. The last matching ACE determines if access is allowed or denied.

Using .htaccess File

The server supports.htaccess dynamic configuration files. You can enable .htaccess files either through the user interface or by manually changing the configuration files.

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. Do not require user authentication with both standard and .htaccess access control when user-group authentication is ”Basic’ You could use SSL client authentication via the standard server access control, and also require HTTP ”Basic’ authentication via an .htaccess file.

If you enable .htaccess files, the server checks for .htaccess files before serving resources. The server looks for .htaccess files in the same directory as the resource and in that directory's parent directories, up to and including the document root. For example, if the Primary Document Directory is set to /sun/server/docs and a client requests /sun/server/docs/reports/index.html, the server will check for .htaccess files at /sun/server/docs/reports/.htaccess and /sun/server/docs/.htaccess.

Note that the Server's Additional Document Directories and CGI Directory functionality allows an administrator to define alternate document roots. The existence of alternate document roots affects .htaccess file processing. For example, consider a server with the Primary Document Directory set to /sun/server/docs and a CGI program at /sun/server/docs/cgi-bin/program.cgi. If you enable CGI as a File Type, the server will evaluate the contents of both /sun/server/docs/.htaccess and /sun/server/docs/cgi-bin/.htaccess when a client issues a request for the CGI program. However, if you instead configure a CGI Directory at /sun/server/docs/cgi-bin, the server will inspect /sun/server/docs/cgi-bin/.htaccess but not /sun/server/docs/.htaccess. This occurs because specifying /sun/server/docs/cgi-bin as a CGI Directory marks it as an alternate document root.

Preventing Your Server from Denial-of-Service attack

Denial-of-Service (DoS) attack is an explicit attempt to prevent legitimate users from using a service by some malicious users of the Server. Such an attack can be launched by:

Sun Java System Web Server can detect DoS attack by monitoring frequently accessed URI and denying request, if the request frequency is considerably high.

The following sections describes how you can prevent DoS attacks at the virtual server level.

Limiting Requests to The Server

You can now tweak the server to prevent Denial-Of-Service attacks by configuring request limits and monitoring maximum number of connections per virtual server. Configuring some of these values may affect the Server's performance.

For configuring request limits for the server, click Configuration > Virtual Servers > Server Settings > Request Limits. Configure the parameters listed in the following table.

Table 7–4 Configuring Request Limit



Request Limits

Enable/Disable request limits for this virtual server. Request limits option is disabled by default. 

Maximum Connections

Maximum number of concurrent connections allowed for this virtual server. 

Maximum RPS

Maximum number of requests allowed from a client per second. 

RPS Compute Interval

The time interval in which the average request per second (RPS) is calculated. Default values is 30 seconds. 

Continue Condition

Determines what condition must be met in order for a blocked request type to become available again for servicing. 

silence — Refused requests must fall to zero (over a subsequent interval) for service to resume.

threshold — Refused request rate must fall below RPS threshold for service to resume.

The default values is threshold. 

Error Code

The HTTP status code to use for blocked requests. The default code is HTTP 503 — Service Unavailable. 

Monitor Attribute

An optional request attribute to monitor. 

Note –

Using CLI

To limit the requests to the server through CLI, execute the following command.

wadm> enable-request-limits --user=admin --password-file=admin.pwd 
--host=serverhost --port=8989 --config=config1 --vs=config1_vs_1

See CLI Reference, enable-request-limits(1).

ProcedureTo Limit the Maximum Number of Connections

You can limit the maximum number of concurrent connections. If a matching request is received while there are at least the specified number of requests being processed, the request is rejected. Note that the rejection of request is only for that particular time. As soon as concurrent requests drops below this limit new requests will be processed.

  1. Click Configuration tab.

  2. Select your configuration from the list.

  3. Select your virtual server under the Virtual Server tab.

  4. Click Server Settings > Request Limits.

  5. Enter a value for Maximum Connections section.