Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide

> ## Chapter 3
> Securing J2EE Applications

> This chapter describes how to write secure J2EE applications, which contain components that perform user authentication and access authorization for servlets and EJB business logic.

> For information about administrative security for the server, see the Sun Java System Application Server Administrator's Guide to Security.

> This chapter contains the following sections:

> - Sun Java System Application Server Security Goals
> - Sun Java System Application Server Specific Security Features
> - Sun Java System Application Server Security Model
> - Security Responsibilities Overview
> - Common Security Terminology
> - Container Security
> - Guide to Security Information
> - Realm Configuration
> - The server.policy File
> - Programmatic Login

> ##

> Sun Java System Application Server Security Goals

> In an enterprise computing environment there are many security risks. The Sun Java System Application Server’s goal is to provide highly secure, interoperable, and distributed component computing based on the J2EE security model. The security goals for the Sun Java System Application Server include:

> - Full compliance with the J2EE security model (for more information, see the J2EE specification, v1.3 Chapter 3 Security)
> - Full compliance with the EJB v2.0 security model (for more information, see the Enterprise JavaBean specification v2.0 Chapter 15 Security Management). This includes EJB role-based authorization.
> - Full compliance with the Java Servlet v2.3 security model (for more information, see the Java Servlet specification, v2.3 Chapter 11 Security). This includes servlet role-based authorization.
> - Support for single sign-on across all Sun Java System Application Server applications within a single security domain.
> - Security support for ACC Clients.
> - Support for several underlying authentication realms, such as simple file and LDAP. Certificate authentication is also supported for SSL client authentication. For Solaris, OS platform authentication is supported in addition to these.
> - Support for declarative security via Sun Java System Application Server specific XML-based role mapping.

> ##

> Sun Java System Application Server Specific Security Features

> The Sun Java System Application Server supports the J2EE v1.3 security model, as well as the following features which are specific to the Sun Java System Application Server:

> - Single sign-on across all Sun Java System Application Server applications within a single security domain
> - Programmatic login

> ##

> Sun Java System Application Server Security Model

> Secure applications require a client to be authenticated as a valid application user and have authorization to access servlets, JSPs, and EJB business logic. Sun Java System Application Server supports security for web, ACC, web service, and JMS clients.

> Applications with secure web and EJB containers may enforce the following security processes for clients:

> - authenticate the caller
> - authorize the caller for access to the EJB business methods

> The following diagram shows the Sun Java System Application Server security model.

> ### Web Application and URL Authorizations

> Secure web applications may have authentication and authorization properties. The web container supports three types of authentication: basic, certificate, and form-based. When a browser requests the main application URL, the web container collects the user authentication information (for example, username and password) and passes it to the security service for authentication.

> Sun Java System Application Server consults the security policies (derived from the deployment descriptors) associated with the web resource to determine the security roles used to permit resource access. The web container tests the user credentials against each role to determine if it can map the user to the role. For more information, see the Sun Java System Application Server Developer’s Guide to Web Applications.

> ### Invocation of Enterprise Bean Methods

> Once the browser client has been authenticated and authorized by the web container and the servlet or JSP performs a method call to the EJB component, the user’s credentials (gathered during the authentication process) are propagated to the EJB container. A secure EJB container has a deployment descriptor with authorization properties, which are used to enforce access control on the bean method. The EJB container uses role information received from the EJB JAR deployment descriptors to decide whether it can map the caller to the role and allow access to the bean method. For more information, see the Sun Java System Application Server Developer’s Guide to Enterprise JavaBeans Technology.

> ### ACC Client Invocation of Enterprise Bean Methods

> For ACC clients, a secure EJB container consults its security policies (obtained from the deployment descriptors) to determine if the caller has the authority to access the bean method. This process is the same for both web and ACC clients. For more information, see the Sun Java System Application Server Developer’s Guide to Clients.

> ##

> Security Responsibilities Overview

> A J2EE platform’s primary goal is to isolate the developer from the security mechanism details and facilitate a secure application deployment in diverse environments. This goal is addressed by providing mechanisms for the application security specification requirements declaratively and outside the application.

> ### Application Developer

> The application developer is responsible for the following:

> - Specifying application roles.
> - Defining role-based access restrictions for the application components (Servlets/JSPs and EJB components).
> - If programmatic security is used, verifying the user roles and authorizing access to features based on these roles. (Programmatic security management is discouraged since it hard codes the security login in the application instead of allowing the containers to manage it.)

> ### Application Assembler

> The application assembler or application component provider must identify all security dependencies embedded in a component including:

> - All role names used by the components that call isCallerInRole or isUserInRole.
> - References to all external resources accessed by the components.
> - References to all intercomponent calls made by the component.

> ### Application Deployer

> The application deployer takes all component security views provided by the assembler and uses them to secure a particular enterprise environment in the application, including:

> - Assigning users or groups (or both) to security roles.
> - Refines the privileges required to access component methods to suit the requirements of the specific deployment scenario.

> ##

> Common Security Terminology

> The most common security processes are authentication, authorization, realm assignment, and role mapping. The following sections define this terminology.

> ### Authentication

> Authentication verifies the user. For example, the user may enter a username and password in a web browser, and if those credentials match the permanent profile stored in the active realm, the user is authenticated. The user is associated with a security identity for the remainder of the session.

> For more information about authentication in the Sun Java System Application Server, see the Sun Java System Application Server Developer’s Guide to Web Applications and the Sun Java System Application Server Developer’s Guide to Clients.

> ### Authorization

> Authorization permits a user to perform the desired operations, after being authenticated. For example, a human resources application may authorize managers to view personal employee information for all employees, but allow employees to only view their own personal information.

> For more information about authorization in the Sun Java System Application Server, see the Sun Java System Application Server Developer’s Guide to Web Applications and the Sun Java System Application Server Developer’s Guide to Enterprise JavaBeans Technology.

> ### Realms

> A realm, also called a security policy domain or security domain in the J2EE specification, is a scope over which a common security policy is defined and enforced by the security administrator of the security service. Supported realms in Sun Java System Application Server are file, ldap, certificate, and solaris. For information about how to configure a realm, see Realm Configuration.

> ### Role Mapping

> A client may be defined in terms of a security role. For example, a company might use its employee database to generate both a company wide phone book application and to generate payroll information. Obviously, while all employees might have access to phone numbers and email addresses, only some employees would have access to the salary information. Employees with the right to view or change salaries might be defined as having a special security role.

> A role is different from a user group in that a role defines a function in an application, while a group is a set of users who are related in some way. For example, members of the groups astronauts, scientists, and (occasionally) politicians all fit into the role of SpaceShuttlePassenger.

> The EJB security model describes roles (as distinguished from user groups) as being described by an application developer and independent of any particular domain. Groups are specific to a deployment domain. It is up to the deployer to map roles into one or more groups for each application or module.

> In the Sun Java System Application Server, roles correspond to users or groups (or both) configured in the active realm.

> ##

> Container Security

> The component containers are responsible for providing J2EE application security. There are two security forms provided by the container:

> - Programmatic security
> - Declarative security

> ### Programmatic Security

> Programmatic security is when an EJB component or servlet uses method calls to the security API, as specified by the J2EE security model, to make business logic decisions based on the caller or remote user’s security role. Programmatic security should only be used when declarative security alone is insufficient to meet the application’s security model.

> The J2EE specification, v1.3 defines programmatic security as consisting of two methods of the EJB EJBContext interface and two methods of the servlet HttpServletRequest interface. The Sun Java System Application Server supports these interfaces as specified in the specification.

> For more information on programmatic security, see the following:

> - Section 3.3.6, Programmatic Security, in the J2EE Specification,v1.3
> - Programmatic Login

> ### Declarative Security

> Declarative security means that the security mechanism for an application is declared and handled externally to the application. Deployment descriptors describe the J2EE application’s security structure, including security roles, access control, and authentication requirements.

> The Sun Java System Application Server supports the DTDs specified by J2EE v1.3 and has additional security elements included in its own deployment descriptors. Declarative security is the application deployer’s responsibility. For more information, see Chapter 4, “Assembling and Deploying J2EE Applications.”

> There are three levels of declarative security, as follows:

> - Application Level Security
> - Web Component Level Security
> - EJB Level Security

> #### Application Level Security

> The application XML deployment descriptor (sun-application.xml) contains authorization descriptors for all user roles for accessing the application’s servlets and EJB components. On the application level, all roles used by any application container must be listed in a role-name element in this file. The role names are scoped to the EJB XML deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml files) and to the servlet XML deployment descriptors (web.xml and sun-web.xml files). The sun-application.xml file must also contain matching security-role-mapping elements for each role-name used by the application.

> #### Web Component Level Security

> A secure web container authenticates users and authorizes access to a servlet or JSP by using the security policy laid out in the servlet XML deployment descriptors (web.xml and sun-web.xml files). Once the user has been authenticated and authorized, the servlet passes on user credentials to an EJB component to establish a secure association with the bean.

> #### EJB Level Security

> The EJB container is responsible for authorizing access to a bean method by using the security policy laid out in the EJB XML deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml files).

> ##

> Guide to Security Information

> Each information type below is shown with a short description, the location where the information resides, how to create the information, how to access the information, and where to look for further information.

> - User Information
> - Security Roles

> ### User Information

> User name, password, and so on.

> ##### Location:

> The location of the user information depends on the realm being used:

> - For the file realm, the users and groups are listed in the key file, which is located in the instance_dir/config directory.
> - For the ldap realm, the users and groups are stored in an external LDAP directory.
> - For the certificate realm, the user identities are obtained from cryptographically verified client certificates.
> - For the solaris realm, the users and groups are stored in the underlying Solaris user database, as determined by the system’s PAM configuration.

> For more information about these realms, see Realm Configuration.

> ##### How to Create:

> How to create users and define groups is specific to the realm being used. The Sun Java System Application Server does not provide administration capabilities for external realms such as Solaris/PAM or LDAP. Consult your Solaris or LDAP server documentation for details.

> ### Security Roles

> Role that defines an application function, made up of a number of users, groups, or both. The relationship between users and groups is determined by the specific realm implementation being used.

> ##### Location:

> Roles are defined in the J2EE application deployment descriptors.

> ##### How to Create:

> Use the Sun Java System Application Server Administration interfacor the Sun ONE Studio 5 development tools for application assembly and deployment.

> ##### How To Access:

> Use isCallerInRole() to test for a user’s role membership. For example, in the following code, if securedMethod() can be accessed by the Manager role, the call to sctx.isCallerInRole("Manager") returns true.

> public class SecTestEJB implements SessionBean
> {
> private SessionContext sctx = null;
> public void setSessionContext(SessionContext sc)
> {
> sctx = sc;
> }
> public void securedMethod( )
> {
> System.out.println( sctx.isCallerInRole( "Manager" ) );
> }
> }

> ##

> Realm Configuration

> This section covers the following topics:

> - How to Configure a Realm and Set the Default Realm
> - Supported Realms

> ### How to Configure a Realm and Set the Default Realm

> You can configure a realm in one of these ways:

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

> If you use the Administration interface or edit the server.xml file, you can set the default realm.

> #### Using the Administration Interface

> To configure a realm using the Administration interface:

> 1. Open the Security component under your server instance.
> 2. Open the Realms component under the Security component.
> 3. Go to the Realms page.
> 4. Click on the check boxes of the realms you wish to activate. You can also use the New and Delete buttons to add and remove realms. To edit a realm, click on it.
> 5. If you are adding or editing a realm, enter the realm’s name, classname, properties, and users (file realm only), then select the Save button.
> 6. Go to the Security page.
> 7. Select a default realm, then select the Save button.
> 8. Go to the server instance page and select the Apply Changes button.
> 9. Restart the server.

> #### Using the asadmin Command

> You can use the asadmin command to configure realms on local servers.

> ##### asadmin create-auth-realm

> The asadmin create-auth-realm command configures a realm. The syntax is as follows:

> asadmin create-auth-realm --user admin_user [--password admin_password] [--passwordfile password_file] [--host hostname] [--port adminport] [--secure | -s] [--instance instance_name] --classname realm_class [--property (name=value)[:name=value]*] realm_name

> For example, the following command configures the certificate realm:

> asadmin create-auth-realm --user jadams --password secret --instance server1 --classname com.iplanet.ias.security.auth.realm.certificate.CertificateRealm certificate

> ##### asadmin delete-auth-realm

> The asadmin delete-auth-realm command deactivates a realm. The syntax is as follows:

> asadmin delete-auth-realm --user admin_user [--password admin_password] [--passwordfile password_file] [--host hostname] [--port adminport] [--secure | -s] [--instance instance_name] realm_name

> For example, the following command deactivates the certificate realm:

> asadmin delete-auth-realm --user jadams --password secret --instance server1 certificate

> ##### asadmin list-auth-realms

> The asadmin list-auth-realms command lists all realms configured for a server instance. The syntax is as follows:

> asadmin list-auth-realms --user admin_user [--password admin_password] [--passwordfile password_file] [--host hostname] [--port adminport] [--secure | -s] instance_name

> For example, the following command lists all realms in the server1 instance:

> asadmin list-auth-realms --user jadams --password secret server1

> #### Editing the server.xml File

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

> <security-service default-realm="file" anonymous-role="ANYONE"
> audit-enabled="false">
> <auth-realm name="file"
> classname="com.iplanet.ias.security.auth.realm.file.FileRealm">
> <property name="file" value="instance_dir/config/keyfile"/>
> <property name="jaas-context" value="fileRealm"/>
> </auth-realm>
> ...
> </security-service>

> The default-realm attribute points to the realm the server is using. It must point to one of the configured auth-realm 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 Application Server Administrator’s Configuration File Reference.

> ### Supported Realms

> The following realms are supported in Sun Java System Application Server:

> - file
> - ldap
> - certificate
> - solaris
> - Creating a Custom Realm

> #### file

> The file realm is the default realm when you first install the Sun Java System Application Server. It has the following configuration characteristics:

> - Name - file
> - Classname - com.iplanet.ias.security.auth.realm.file.FileRealm

> Required properties are as follows:

> - file - The name of the file that stores user information. By default this file is instance_dir/config/keyfile.
> - jaas-context - The value must be fileRealm.

> The user information file is initially empty, so you must add users before you can use the file realm. You can configure users in one of these ways:

> - Using the Administration Interface
> - Using the asadmin Command

> ##### Using the Administration Interface

> To configure a user in the file realm using the Administration interface:

> 1. Open the Security component under your server instance.
> 2. Open the Realms component under the Security component.
> 3. Go to the file page.
> 4. Click on the Manage Users button.
> 5. To add a new user, click on the New button. To modify information for a user, click on the user’s name in the list. In either case, enter the following information:
> - User ID (required if new) - The name of the user.
> - Password (required) - The user’s password.
> - Retype Password (required) - The user’s password again, for verification.
> - Group List (optional) - A comma-separated list of the groups the user belongs to.
> 6. Click on the OK button.
> 7. Go to the server instance page and select the Apply Changes button.
> 8. Restart the server.

> ##### Using the asadmin Command

> The asadmin create-file-user command creates one user in the file realm. Its syntax is as follows, with defaults shown for optional parameters that have them:

> asadmin create-file-user --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] [--userpassword user_password] [--groups user_group[:user_group]*] user_name

> For example, the following command adds user dsanchez to the file realm and assigns secret as this user’s password. Note that jadams and topsecret are the administrator’s name and password, respectively.

> asadmin create-file-user --user jadams --password topsecret --userpassword secret dsanchez

> The asadmin delete-file-user command removes one user from the file realm. Its syntax is as follows, with defaults shown for optional parameters that have them:

> asadmin delete-file-user --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] user_name

> For example, the following command removes user dsanchez from the file realm. Note that jadams and topsecret are the administrator’s name and password, respectively.

> asadmin delete-file-user --user jadams --password topsecret dsanchez

> The asadmin update-file-user command changes information for one user in the file realm. Its syntax is as follows, with defaults shown for optional parameters that have them:

> asadmin update-file-user --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--instance instance_name] [--userpassword user_password] [--groups user_group[:user_group]*] user_name

> For example, the following command changes the password for user dsanchez to private. Note that jadams and topsecret are the administrator’s name and password, respectively.

> asadmin update-file-user --user jadams --password topsecret --userpassword private dsanchez

> The asadmin list-file-users command lists users in the file realm. Its syntax is as follows, with defaults shown for optional parameters that have them:

> asadmin list-file-users --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] instance_name

> For example, the following command lists file realm users for the server1 instance. Note that jadams and topsecret are the administrator’s name and password, respectively.

> asadmin list-file-users --user jadams --password topsecret server1

> The asadmin list-file-groups command lists groups in the file realm. Its syntax is as follows, with defaults shown for optional parameters that have them:

> asadmin list-file-groups --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] [--name user_name] instance_name

> For example, the following command lists file realm groups for user dsanchez. Note that jadams and topsecret are the administrator’s name and password, respectively.

> asadmin list-file-users --user jadams --password topsecret --name dsanchez server1

> #### ldap

> The ldap realm allows you to use an LDAP database for user security information. It has the following configuration characteristics:

> - Name - ldap
> - Classname - com.iplanet.ias.security.auth.realm.ldap.LDAPRealm

> Required properties are as follows:

> - directory - The LDAP URL to your server.
> - base-dn - The base DN for the location of user data. This base DN can be at any level above the user data, since a tree scope search is performed. The smaller the search tree, the better the performance.
> - jaas-context - The value must be ldapRealm.

> You can add the following optional properties to tailor the LDAP realm behavior.

> - search-filter - The search filter to use to find the user. The default is uid=%s (%s expands to the subject name).
> - group-base-dn - The base DN for the location of groups data. By default it is same as the base-dn, but it can be tuned if necessary.
> - group-search-filter - The search filter to find group memberships for the user. The default is uniquemember=%d (%d expands to the user element DN).
> - group-target - The LDAP attribute name that contains group name entries. The default is CN.
> - search-bind-dn - An optional DN used to authenticate to the directory for performing the search-filter lookup. Only required for directories that do not allow anonymous search.
> - search-bind-password - The LDAP password for the DN given in search-bind-dn.

> You must create the desired user(s) in your LDAP directory. You can do this from the Sun Java System Directory Server console in the Users & Groups main tab, or through any other administration tool which supports LDAP and your directory’s schema.

> The principal-name used in the deployment descriptors must correspond to your LDAP user information.

> For example, suppose an LDAP user, joe java, is defined in your LDAP directory as follows:

> uid=jjava,ou=People,dc=acme,dc=com
> uid=jjava
> givenName=joe
> objectClass=top
> objectClass=person
> objectClass=organizationalPerson
> objectClass=inetorgperson
> sn=java
> cn=joe java

> The required properties in the ldap realm configuration would be as follows:

> - The directory would be the LDAP URL to your server, for example:

> ldap://ldap.acme.com:389

> - The base-dn could be ou=People,dc=acme,dc=com. Note that it could also be rooted at a higher point, for example dc=acme,dc=com, but searches would traverse a larger part of the tree, impacting performance.
> - The jaas-context must be ldapRealm.

> #### certificate

> The certificate realm supports SSL authentication. The certificate realm sets up the user identity in the Sun Java System Application 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. It has the following configuration characteristics:

> - Name - certificate
> - Classname - com.iplanet.ias.security.auth.realm.certificate.CertificateRealm

> You can add the following optional property to tailor the certificate realm behavior.

> - assign-groups - If this property is set, its value is taken to be a comma-separated list of group names. All clients who present valid certificates are assigned membership to these groups for the purposes of authorization decisions in the web and EJB containers.

> When you deploy an application, you must specify CLIENT-CERT as the authentication mechanism in the web.xml file as follows:

> <login-config>
> <auth-method>CLIENT-CERT</auth-method>
> </login-config>

> You must obtain a client certificate and install it in your browser to complete the setup for client certificate authentication. For details on how to set up the server and client certificates, see the Sun Java System Application Server Administrator’s Guide to Security.

> You can configure the server instance for SSL authentication in these ways:

> - Configure an ssl element in server.xml, then restart the server. For more information about the server.xml file, see the Sun Java System Application Server Administrator’s Configuration File Reference.
> - Use the Administration interface, as follows:
> 1. Open the HTTP Server component under your server instance.
> 2. Open the HTTP Listeners component under the HTTP Server component.
> 3. Select the listener for which you want to configure SSL.
> 4. Edit the SSL/TLS Settings for the listener.
> 5. Select the Save button.
> 6. Go to the server instance page and select the Apply Changes button.
> 7. Restart the server.

> For more information, see the Sun Java System Application Server Administrator’s Guide to Security.

> #### solaris

> The solaris realm allows authentication using Solaris username+password data. This realm is only supported on Solaris 9. It has the following configuration characteristics:

> - Name - solaris
> - Classname - com.iplanet.ias.security.auth.realm.file.SolarisRealm

> Required properties are as follows:

> - jaas-context - The value must be solarisRealm.

> Note | The Solaris realm invokes the underlying PAM infrastructure for authenticating. If the configured PAM modules require root privileges, the instance must run as root to use this realm. For details, see the “Using Authentication Services (Tasks)” chapter in the Solaris 9 Systems Administrators Guide: Security Services. Solaris supports an enhanced method for controlling access to resources called Role Based Access Control (RBAC). Sun Java System Application Server includes RBAC facilities for its administrative commands. For details, see the “Role-Based Access Control (Overview)” chapter in the Solaris 9 Systems Administrators Guide: Security Services.

> #### Creating a Custom Realm

> You can create a custom realm by providing a Java Authentication and Authorization Service (JAAS) login module and a realm implementation. Note that client-side JAAS login modules are not suitable for use with Sun Java System Application Server. For more information about JAAS, refer to the JAAS specification for Java 2 SDK, v 1.4, available here:

> http://java.sun.com/products/jaas/

> ##

> The server.policy File

> Each Sun Java System Application Server instance has its own standard J2SE policy file, located in the instance_dir/config directory. The file is named server.policy.

> Sun Java System Application Server 7 is a J2EE 1.3-compliant application server. As such, it follows the requirements of the J2EE specification, including the presence of the security manager (the Java component that enforces the policy) and a limited permission set for J2EE application code.

> This section covers the following topics:

> - Default Permissions
> - Changing Permissions for an Application
> - Disabling the Security Manager

> ### Default Permissions

> Internal server code is granted all permissions. These are covered by the AllPermission grant blocks to various parts of the server infrastructure code. Do not modify these entries.

> Application permissions are granted in the default grant block. These permissions apply to all code not part of the internal server code listed previously. Sun Java System Application Server 7 does not distinguish between EJB and web module permissions. All code is granted the minimal set of Web component permissions (which is a superset of the EJB minimal set).

> A few permissions above the minimal set are also granted in the default server.policy file. These are necessary due to various internal dependencies of the server implementation. J2EE application developers must not rely on these additional permissions.

> One additional permission is granted specifically for using connectors. If connectors are not used in a particular server instance, you should remove this permission, because it is not otherwise necessary.

> ### Changing Permissions for an Application

> The default policy for each instance limits the permissions of J2EE deployed applications to the minimal set of permissions required for these applications to operate correctly. If you develop applications that require more than this default set of permissions, you can edit the server.policy file to add the custom permissions that your applications need.

> You should add the extra permissions only to the applications that require them, not to all applications deployed to a server instance. Do not add extra permissions to the default set (the grant block with no codebase, which applies to all code). Instead, add a new grant block with a codebase specific to the application requiring the extra permissions, and only add the minimally necessary permissions in that block.

> Note | Do not add java.security.AllPermission to the server.policy file for application code. Doing so completely defeats the purpose of the security manager, yet you still get the performance overhead associated with it. Disable the security manager instead, as described in Disabling the Security Manager.

> As noted in the J2EE specification, an application should provide documentation of the additional permissions it needs. If an application requires extra permissions but does not document the set it needs, contact the application author for details.

> As a last resort, you can iteratively determine the permission set an application needs by observing AccessControlException occurrences in the server log. If this is not sufficient, you can add the -Djava.security.debug=all JVM option to the server instance. For details, see the Sun Java System Application Server Administrator’s Guide or the Sun Java System Application Server Administrator’s Configuration File Reference.

> You can use the J2SE standard policytool or any text editor to edit the server.policy file. For more information, see:

> http://java.sun.com/docs/books/tutorial/security1.2/tour2/index.html

> For detailed information about the permissions you can set in the server.policy file, see:

> http://java.sun.com/j2se/1.4/docs/guide/security/permissions.html

> The Javadoc for the Permission class is here:

> http://java.sun.com/j2se/1.4/docs/api/java/security/Permission.html

> ### Disabling the Security Manager

> Developers of J2EE application components should not disable the security manager. As noted in the J2EE specification, J2EE application components should be capable of running with the default set, and otherwise a component needs to document its special requirements.

> Note | To ensure that a J2EE application is compliant with the J2EE policy set, it is critical that J2EE developers do not disable the security manager. Sun Java System Application Server 7 provides an option for disabling the security manager, but future releases may not. Applications that fail to comply with the J2EE policy set (and do not document divergences) may fail to run in future releases.

> In a production environment, you may be able to safely disable the security manager if:

> - Performance is critical
> - Deployment to the production server is carefully controlled
> - Only trusted applications are deployed
> - Applications don’t need policy enforcement

> Disabling the security manager may improve performance significantly for some types of applications. To disable the security manager, remove or comment the following entry in the server.xml file:

> <jvm-options>-Djava.security.policy=instance_dir/config/server.policy</jvm-options>

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

> ##

> Programmatic Login

> Programmatic login allows a deployed J2EE application to invoke a login method. If the login is successful, a SecurityContext is established as if the client had authenticated using any of the conventional J2EE mechanisms.

> Programmatic login is useful for an application that has special needs which cannot be accommodated by any of the J2EE standard authentication mechanisms.

> Note | Programmatic login is specific to Sun Java System Application Server and not portable to other application servers.

> This section contains the following topics:

> - Precautions
> - Granting Programmatic Login Permission
> - The ProgrammaticLogin Class

> ### Precautions

> The Sun Java System Application Server is not involved in how the login information (user, password) is obtained by the deployed application. Programmatic login places the burden on the application developer with respect to assuring that the resulting system meets their security requirements. If the application code reads the authentication information across the network, it is up to the application to determine whether to trust the user.

> Programmatic login allows the application developer to bypass the application server-supported authentication mechanisms and feed authentication data directly to the security service. While flexible, this capability should not be used without some understanding of security issues.

> Since this mechanism bypasses the container-managed authentication process and sequence, the application developer must be very careful in making sure that authentication is established before accessing any restricted resources or methods. It is also the application developer’s responsibility to verify the status of the login attempt and to alter the behavior of the application accordingly.

> The programmatic login state does not necessarily persist in sessions or participate in single sign-on.

> Lazy authentication is not supported for programmatic login. If an access check is reached and the deployed application has not properly authenticated via the programmatic login method, access is denied immediately and the application may fail if not properly coded to account for this occurrence.

> ### Granting Programmatic Login Permission

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

> To grant the required permission to the application, add the following to the instance_dir/config/server.policy file:

> grant codeBase "file:jar_file_path" {
> permission com.sun.appserv.security.ProgrammaticLoginPermission
> "login";
> };

> The jar_file_path is the path to the application’s JAR file.

> For more information about the server.policy file, see The server.policy File.

> ### The ProgrammaticLogin Class

> The com.sun.appserv.security.ProgrammaticLogin class enables a user to perform login programmatically. This class has two login methods, one for servlets or JSPs and one for EJB components.

> The login method for servlets or JSPs has the following signature:

> public Boolean login(String user, String password, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)

> The login method for EJB components has the following signature:

> public Boolean login(String user, String password)

> Both login methods:

> - Perform the authentication
> - Return true if login succeeded, false if login failed

> Previous Contents Index Next

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