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

> ## Chapter 4
> J2EE-based Security for Web Container and Web Applications

> This chapter describes the basic features of J2EE-based security for the Sun ONE 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 J2EE/Servlet-based security model. It also discusses new functionality in Sun ONE 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 J2EE/Servlet configuration issues, related security issues are described in the following chapters:

> - Certificates and public key cryptography, in Using Certificates and Keys.
> - ACL-based security, in Controlling Access to Your Server.

> This chapter contains the following sections:

> - About Sun ONE Web Server Security
> - Overview of ACL-based Access Control
> - Overview of J2EE/Servlet-based Access Control
> - Realm-based Security
> - How to Configure a Realm
> - Specifying the Default Realm
> - Using Programmatic Security
> - Deciding When to Use the J2EE/Servlet Authentication Model

> ##

> About Sun ONE 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 ONE Web Server 6.1 supports two security models: the ACL-based security model provided by the HTTP engine and the J2EE Servlet version 2.3 specification -based provided by the web container.

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

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

> Sun ONE Web Server 6.1 supports both declarative security and programmatic security.

> Sun ONE Web Server 6.1 leverages the features of the J2EE 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 J2EE containers. The deployment descriptor files for web applications in Sun ONE 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 ONE Web Server 6.1:

> - ACL-based access control, described in the section Overview of ACL-based Access Control.
> - J2EE-based access control, described in the section Overview of J2EE/Servlet-based Access Control.
> - Native Realm support, described in the section Native Realm.
> - Programmatic security, described in the section Using Programmatic Security.

> ##

> Overview of ACL-based Access Control

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

> Sun ONE Web Server 6.1 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.

> 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 ONE Web Server 6.1 support 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:

> - ACL-based authentication and authorization use the following configuration files:
> - server-install/httpacl/*.acl files
> - server-install/userdb/dbswitch.conf
> - server-install/server-instance/config/server.xml
> - Authentication databases are provided by auth-db modules which are configured in the dbswitch.conf file.
> - Authentication and authorization is performed by access control rules set in the server-install/httpacl/*.acl files, if ACLs are configured. The authorization rules that apply are those that are defined in the ACL file corresponding to the virtual server processing the request (as configured in the appropriate VS entry in server.xml) See the ACLFILE element and aclids property of the VS element in the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference. Typically these files are located in the /httpacl/ directory, but don't necessarily have to be if you change the server.xml configuration.

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

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

> ##

> Overview of J2EE/Servlet-based Access Control

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

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

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

> - Servlets
> - JavaServer Pages (JSP) components
> - HTML documents
> - Miscellaneous resources, such as image files and compressed archives

> The J2EE/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 that is currently active in the security service for this particular application.

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

> - J2EE/Servlet-based authentication uses the following configuration files:
> - The web application deployment descriptor files web.xml and sun-web.xml
> - server-install/server-instance/config/server.xml
> - Authentication is performed by Java security realms which are configured through AUTHREALM entries in the server.xml file.
> - Authorization is performed by access control rules in the deployment descriptor file, web.xml, in case any such rules have been set.

> The following section briefly explains the concept of security realms. For a fuller discussion on the J2EE security model and realm-based authentication, see the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.

> ##

> Realm-based Security

> The J2EE-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. This verifies users through an underlying realm.
> - Role-based Authorization. This assigns users to roles, which in turn are granted or restricted access to resources.

> ### 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 ONE Web Server, the authentication service is built using JAAS, which provides pluggable security domains. The Java authentication realms in Sun ONE Web Server 6.1 are compatible with Sun ONE Application Server 7.0 realms.

> Sun ONE Web Server 6.1 provides the following realms:

> - LDAP realm
> - File realm
> - Solaris realm
> - Certificate realm
> - Custom Realm
> - Native Realm

> #### 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 ONE Web Server. This realm, easy and simple to set up, represents a 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:

> - keyfile-style databases
> - htaccess-style databases
> - digest-style databases

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

> The user information file used by the file realm is initially empty, so 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. Because this realm uses the user database in the Solaris 9 Operating Environment, it eliminates the extra step of setting up a separate database.

> #### Certificate realm

> The certificate realm supports SSL authentication. The certificate realm sets up the user identity in the Sun ONE Web Server's security context and populates it with user data from the client certificate. The J2EE 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 Using Certificates for 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 that client-side JAAS login modules are not suitable for use with Sun ONE Web Server.

> Refer to the sample realm in Sun ONE 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 J2EE/Servlet authentication model. By using the Native realm for Java web applications it becomes possible 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.

> Since Native realm delegates the authentication to the core, some additional configuration is required. For more information, see Configuring the Native Realm.

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

> ### Role-based Authorization

> The Java Servlet 2.3 Specification define how to establish access control rules to restrict access to the various J2EE application resources.

> #### Mapping Roles to Restricted Areas

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

> - The restricted areas, as listed in the Web module descriptors (web.xml)
> - The roles which are granted access to each restricted area (in web.xml)
> - User and group mappings to roles, that determine which specific users are authorized to access which restricted areas (in sun-web.xml).

> Users can assume multiple roles and, upon verification that they have been assigned at least one of the roles, they are allowed access to the corresponding areas.

> Use the samples located in the webapps/security directory with various access restrictions in Sun ONE 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

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

> <sun-web-app>

> <security-role-mapping>

> <role-name>manager</role-name>

> <principal-name>jsmith</principal-name>

> <group-name>divmanagers</group-name>

> </sun-web-app>

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

> ##

> How to Configure a Realm

> You can configure realms in one of these ways:

> - Using the Administration Interface
> - Editing the server.xml File

> ### Using the Administration Interface

> To 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 the Security Realms link.

> By default, the following realms are provided:

> - file

> - native

> - ldap

> 3. To add a realm, click the New button. To delete a realm, check the checkbox next to the name of the realm, and click OK. To edit a realm, click onthe 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), then click the OK button.
> 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="ANYONE"
> audit="false">
> <AUTHREALM name="file"
> classname="com.iplanet.ias.security.auth.realm.file.FileRe alm">
> <property name="file" value="instance_dir/config/keyfile"/>
> <property name="jaas-context" value="fileRealm"/>
> </AUTHREALM>
> ...
> </SECURITY>

> The defaultrealm attribute points to the realm the server is using by default. The default realm will be used by all web applications which 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 ONE Web Server 6.1 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" classname="com.sun.enterprise.security.auth.realm.webcore.NativeRea lm">

> <PROPERTY name="auth-db" value="mykeyfile">

> <PROPERTY name="jaas-context" value="nativeRealm"/>

> </AUTHREALM>

> The auth-db property points to the core authentication database to which this Native realm instance will delegate 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="https-plaza.com" ....

> ....

> <USERDB id="mykeyfile" database="myalt"/>

> ....

> </VS>

> 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/https-plaza.com/config/keyfile

> The above configuration is in no way 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 ONE web Server 6.1, web applications have two distinct mechanisms for using LDAP as the authentication engine: Using the Java LDAP realm Using the Java Native realm configured to delegate to the native LDAP authentication database.

> ##

> 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. To specify the active authentication realm for the server instance, perform the following steps:

> 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 ONE Web Server 6.1 also supports managed authentication accessed through the programmatic login interface. This interface supports custom authentication models that do not fit into the realm infrastructure. Programmatic login can also be used by J2EE applications to directly establish authentication contexts for themselves. However, such a practice 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 J2EE mechanism.

> Sun ONE 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:

> <JVMOPTIONS>-Djava.security.manager</JVMOPTIONS>

> <JVMOPTIONS>-Djava.security.policy=install-root/https-servername/co nfig/server.policy</JVMOPTIONS>

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

> ##

> Deciding When to Use the J2EE/Servlet Authentication Model

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

> Use the J2EE/Servlet authentication model:

> - In general, for most new J2EE/Servlet-based web applications.
> - For existing .war files that you do not wish to modify.
> - For creating web applications where full J2EE/Servlet compatibility is important either now or in the future.
> - If you wish to use form-based authentication since form-based authentication is not supported by ACLs.

> 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.

> Previous Contents Index Next

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