Sun Java System Web Server 6.1 SP9 Administrator's Guide

Chapter 4 J2SE-based Security for Web Container and Web Applications

This chapter describes the basic features of J2SE-based security for the Sun Java System Web Server 6.1 web container and web applications. It begins with a discussion on the two main authentication and authorization models supported by the Web server : the Access Control List (ACL)-based security model and the J2SE/Servlet-based security model. It also discusses new functionality in Sun Java System Web Server 6.1 that allows you to deploy Java web applications which can leverage the benefits of both security systems.

While the rest of this chapter deals with the J2SE/Servlet configuration issues, related security issues are described in the following chapters:

This chapter contains the following sections:

About Sun Java System Web Server Security

You can protect resources that reside on your Web server through several security services and mechanisms, including authentication, authorization, and 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 and services.

Sun Java System Web Server 6.1 supports two security models: the ACL-based security model provided by the HTTP engine and the J2SE Servlet version 2.3 specification -based provided by the web container.

Both models co-exist in the life time of a Sun Java System Web Server 6.1 process. Each model supports both client authentication and authorization security services.

The Sun Java System Web Server 6.1 web container provides client authentication through the Java Authentication and Authorization Service (JAAS)-based realm mechanism, and authorization through the J2SE role-based mechanism. One of the realms provided by Sun Java System Web Server 6.1 is the Native Realm. It provides the bridge between the two security models.

Sun Java System Web Server 6.1 supports both declarative security and programmatic security.

Sun Java System Web Server 6.1 leverages the features of the J2SE platform to define declarative contracts between those who develop and assemble application components and those who configure applications in operational environments. In the context of application security, application providers are required to declare the security requirements of their applications in such a way that these requirements can be satisfied during application configuration. The declarative security mechanisms used in an application are expressed in a declarative syntax in a document called a deployment descriptor. An application deployer then employs container-specific tools to map the application requirements that are in a deployment descriptor to security mechanisms that are implemented by J2SE containers. The deployment descriptor files for web applications in Sun Java System Web Server 6.1 are the web.xml and sun-web.xml files.

Programmatic security refers to security decisions that are made by security-aware applications. Programmatic security is useful when declarative security alone is not sufficient to express the security model of an application. For example, an application might make authorization decisions based on the time of day, the parameters of a call, or the internal state of a web component. Another application might restrict access based on user information stored in a database.

The rest of this chapter runs you through the following key concepts in authentication and authorization supported by Sun Java System Web Server 6.1:

Overview of ACL-based Access Control

ACL-based access control is described at length in Chapter 10, Controlling Access to Your Server. The following section provides a brief overview of the key concepts.

Sun Java System Web Server 6.1 supports authentication and authorization through the use of locally stored access control lists (ACLs), that describes 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.

acl "path=/export/user/990628.1/docs/misc/";
  authenticate (user,group) {
     database = "default";
     method = "basic";
  deny (all) (user=”anyone”);
  allow (read) (user = "John");

The core ACLs in Sun Java System Web Server 6.1 supports three types of authentication: basic, SSL, and digest.

Basic authentication relies on lists of user names and passwords passed as cleartext. The SSL method requires the browser to have a user certificate, which contains the user’s public key and other user information such as name, email, and so on. Digest authentication uses encryption techniques to encrypt the user’s credentials.

The main features of the ACL-based access control model are described below:

In addition, the Sun Java System Web Server 6.1 SSL engine supports external crypto hardware to offload SSL processing and provides optional tamper-resistant key storage.

For more information about access control and the use of external crypto hardware, see Chapter 9, Controlling Access to Your Server.

Overview of J2SE/Servlet-based Access Control

J2SE/Servlet-based access control is described at length in the Sun Java System Web Server 6.1 Programmer’s Guide to Web Applications. The following section provides a brief overview of the key concepts.

Sun Java System Web Server 6.1, apart from providing ACL-based authentication, also leverages the security model defined in the J2SE 1.3 Specification to provide several features that help you develop and deploy secure Java Web applications.

A typical J2SE-based Web application consists of the following parts, access to any or all of which can be restricted:

The J2SE/Servlet-based access control infrastructure relies on the use of security realms. When a user tries to access an access-protected section of an application through a Web browser, the Web container prompts for the user’s credential information, and then passes it for verification to the realm which is currently active in the security service for this particular application.

The main features of the J2SE/Servlet-based access control model are described below:

The following section briefly explains the concept of security realms. For a detailed discussion on the J2SE security model and realm-based authentication, see the Sun Java System Web Server 6.1 SP9 Programmer’s Guide to Web Applications.

Realm-based Security

The J2SE-based security model provides for security realms that identify and authenticate users. The user information is obtained from an underlying security realm. Realm-based security consists of two aspects:

Realm-based User Authentication

The authentication process verifies users through an underlying realm, also known as a security domain. A realm consists of a set of users, optional group mappings, and authentication logic that can validate authentication requests. Once an authentication request is validated by a configured realm and the security context established, this identity is applied to all subsequent authorization decsisions, unless overruled by a run-as condition.

A server instance may have any number of configured realms. The configuration information is present in the AUTHREALM element in the server.xml file.

In Sun Java System Web Server, the authentication service is built using JAAS, which provides pluggable security domains. The Java authentication realms in Sun Java System Web Server 6.1 are compatible with Sun Java System Application Server 7.0 realms.

Sun Java System Web Server 6.1 provides the following realms:

LDAP realm

The ldap realm allows you to use an LDAP database for user security information. An LDAP directory service is a collection of attributes with unique identifiers. The ldap realm is ideal for deployment to production systems.

In order to authenticate users against the ldap realm, you must create the desired user(s) in your LDAP directory. You can do this from the Administration Server’s Users & Groups tab or from your LDAP directory product’s user management console. For more information, see Creating a New User in an LDAP-based Authentication Database.

File realm

The file realm is the default realm when you first install the Sun Java System Web Server. It is easy and simple to set up and provides significant convenience to developers.

The file realm authenticates users against user data stored in a text file. The following authentication databases are supported by the file realm:

For more information about the various file-based authentication databases, see <add>.

The user information file used by the file realm is initially empty. You must add users before you can use the file realm. For more information on how you can do this, see Creating a New User in a Key File Authentication Database.

Solaris realm

The solaris realm allows authentication using Solaris username + password data. This realm is only supported on Solaris 9. An additional step of setting up a separate database is eliminated since this realm uses the user database of the Solaris 9 operating environment.

Certificate realm

The certificate realm supports SSL authentication. The certificate realm sets up the user identity in the Sun Java System Web Server’s security context and populates it with user data from the client certificate. The J2SE containers then handle authorization processing based on each user’s DN from his or her certificate. This realm authenticates users with SSL or TLS client authentication through X.509 certificates.

For details on how to set up the server and client certificates, see Certificate-based Authentication.

Custom Realm

You can build realms for other databases, such as Oracle, to suit your specific needs by using pluggable JAAS login modules and a realm implementation.

Note –

Client-side JAAS login modules are not suitable for use with Sun Java System Web Server.

Refer to the sample realm in Sun Java System Web Server 6.1 as a template.

Native Realm

The Native realm is a special realm that provides a bridge between the core ACL-based authentication model and the J2SE/Servlet authentication model. Use the Native realm for Java web applications to have the ACL subsystem perform the authentication (instead of having the Java web container do so) and yet have this identity available for Java web applications.

When an authentication operation is invoked, the Native realm delegates this authentication to the core authentication subsystem. From the user’s perspective this is essentially equivalent to, for example, the LDAP realm delegating authentication to the configured LDAP server. When group membership queries are processed by the Native realm, they are also delegated to the core authentication subsystem. From the Java web modules and the developers perspective, the Native realm is no different from any of the other Java realms which are available for use with web modules.

Additional configuration is required as the Native realm delegates the authentication to the core, . For more information, see Configuring the Native Realm.

The Sun Java System Web Server 6.1 Programmer’s Guide to Web Applications provides a detailed discussion on J2SE security realms and the configuration parameters you can use to configure security realms.

Role-based Authorization

The Java Servlet 2.3 Specification defines how to establish access control rules to restrict access to the various J2SE application resources.

Mapping Roles to Restricted Areas

J2SE access control is based on roles. To restrict access to specific HTML pages, servlets, JSPs, and so forth, you must define the following:

Users can assume multiple roles. Access is allowed to the corresponding areas on verification that users have been assigned at least one of the roles.

Use the samples located in the webapps/security directory with various access restrictions in Sun Java System Web Server 6.1 as templates. For additional discussion on Servlet role-based security, refer to the Servlet 2.3 specification.

Defining Access Control by Roles

J2SE application roles are abstract ones and apply to specific applications. To run your application in a real-world environment with restricted access to authorized users only, you must map the user names to the roles in the sun-web.xml descriptor. Employ either or both of these ways:

Principal mapping - Map a user name or multiple names directly to a role in sun-web.xml. This method is convenient for testing but does not scale beyond a limited number of users in each role.

Group mapping - Map a user name or multiple ones indirectly through one or multiple groups in sun-web.xml. (For example, group names can be engineers, managers, or staff.) Any authenticated user who belongs to the groups listed is then assigned the application role. Please note that the active realm implementation (or the database that is references) is responsible for determining which users belong to a given group.

When a principal (user) requests a particular Web resource, for example, a servlet or a JSP, the Web container checks the security constraints or permissions associated with the resource in the deployment descriptor files to determine whether the principal is authorized to access it.

Role mapping entries map a role to a user or a group in the module descriptor. Example:


For more information about deployment descriptor files, see the Sun Java System Web Server 6.1 SP9 Programmer’s Guide to Web Applications.

How to Configure a Realm

You can configure realms in one of these ways:

Using the Administration Interface

ProcedureTo configure a realm using the Administration interface

  1. From the Administration Server interface, access the server instance you want to manage, then click on the Java tab.

  2. Click Security Realms.

    By default, the following realms are provided:

    - file

    - native

    - ldap

  3. To add a realm, click New. To delete a realm, check the checkbox next to the name of the realm, and click OK. To edit a realm, click on the name of the realm.

  4. If you are adding or editing a realm, enter the realm’s name, classname, properties, and users (file realm only).

  5. Click OK.

Editing the server.xml File

Behind the scenes, the default realm is set in the SECURITY element in the server.xml file. The SECURITY configuration looks like this:

<SECURITY defaultrealm="file" anonymousrole="ANYJava System"
   <AUTHREALM name="file"
       <property name="file" value="instance_dir/config/keyfile">
       <property name="jaas-context" value="fileRealm">

The defaultrealm attribute points to the realm the server is using by default. The default realm will be used by all web applications that do not provide a valid realm in their web.xml. It must point to one of the configured AUTHREALM names. The default is the file realm.

The audit flag determines whether auditing information is logged. If set to true, the server logs audit messages for all authentication and authorization events.

If you change the realm configuration, you must restart the server for the change to take effect.

For more information about the server.xml file, see the Sun Java System Web Server 6.1 SP9 Administrator’s Configuration File Reference.

Configuring the Native Realm

As with all realms, you can configure the Native realm using the AUTHREALM element within the SECURITY element in server.xml. Example:

<AUTHREALM name="native" 
    <PROPERTY name="auth-db" value="mykeyfile">
    <PROPERTY name="jaas-context" value="nativeRealm">

The auth-db property points to the core authentication database to which the Native realm instance delegates all authentication requests. In this example, an authentication database named “mykeyfile”. This property is optional. If not specified, the core authentication engine will use the default auth-db to process all requests from this Native realm. As in the case of most realms, the jaas-context property is a pointer to the JAAS login context to be used (defined in login.conf).

No other configuration is needed by the Native realm. However, since requests are being delegated to a core authentication database, that particular authentication database must also be property configured. The rest of this section provides an example of configuring a core authentication database.

To configure a core (native) authentication database, in server.xml, the VS element must contain a USERDB element which maps the auth-db name to a database name. For example:

<VS id=""  ....
    <USERDB id="mykeyfile" database="myalt">

Note that if the auth-db property is not given (in which case "default" is used) you could have a USERDB entry mapping id="default" to some database name. If no mapping is present, the mapping is to default.

Next, the file install-root/userdb/dbswitch.conf must contain the configuration for the myalt database. The following example defines myalt to be a file-based authentication database.

directory myalt file
myalt:syntax keyfile
myalt:keyfile /local/ws61/

The above configuration is not specific to the Native realm. Any valid authentication directory configuration can be used as the destination authentication database by the Native realm. This means the Native realm can be configured to delegate to native LDAP authentication databases or even to custom native authentication databases.

Note –

In Sun Java System web Server 6.1, web applications have two distinct mechanisms for using LDAP as the authentication engine:

Specifying the Default Realm

The default realm is used to process authentication events for all web applications which do not specify a valid alternate realm in their web.xml deployment descriptor file.

ProcedureTo specify the active authentication realm for the server instance

  1. Access the Server Manager and choose the Java tab.

  2. Click the Java Security link.

  3. Set the following information:

    • Default Realm . Specifies the active authentication realm (an AUTHREALM name attribute) for this server instance.

      • Anonymous Role (optional). Used as the name for default or anonymous role.

      • Audit Enabled (optional). If true, additional access logging is performed to provide audit information. Audit information consists of:

        • Authentication success and failure events

        • Servlet access grants and denials

        Log Level (optional). Controls the type of messages logged to the errors log.

  4. Click OK.

Using Programmatic Security

In addition to the container-managed authentication provided by the realms, Sun Java System Web Server 6.1 also supports managed authentication accessed through the programmatic login interface. This interface provides support to custom authentication models that do not fit into the realm infrastructure. Programmatic login can be used by J2SE applications to directly establish authentication contexts for themselves. This makes the application less portable and less maintainable and is not recommended.

The ProgrammaticLoginPermission permission is required to invoke the programmatic login mechanism for an application. This permission is not granted by default to deployed applications because this is not a standard J2SE mechanism.

Sun Java System web Server 6.1 supports the Security Manager. The Security manager is disabled by default when you first install the server. If you have enabled the Java Security Manager in your server instance, you need to grant this permission to any web applications that will use programmatic login.

To grant the required permission to the application, you need to edit the server.policy file.

You can enable policy support by specifying the standard Java policy entries in the server.xml file:


For more information details about the server.policy file, see the Sun Java System Web Server 6.1 SP9 Programmer’s Guide to Web Applications.

Deciding When to Use the J2SE/Servlet Authentication Model

This section is designed to help you understand in what circumstances you should decide to use the J2SE/Servlet-based authentication model.

Use the J2SE/Servlet authentication model:

Remember that even if you use the ACL-based infrastructure you still have the option of using the Native Realm Java realm in order to propagate the user identity so that it is available for the servlet.