English

How To: Secure an ESRI Java ADF Web Application Using Sun Java Studio Enterprise 6

Summary

Authentication and authorization are essential components of the security model for modern Web applications. Instructions provided describe how to use the Sun Java System technology stack to implement authentication and authorization for an ESRI Java ADF Web application that provides differing map overlays dependent on a user's associated role.

Instructions provided describe how to configure the Sun Application Server and modify the DynamicLayers sample web application (from the ArcGIS Server Software Development Kit) to enable authentication and authorization. The new web application will honor the following use case:

     - The user makes an initial attempt to connect to the DynamicLayers web
application URL, http:\\localhost:49153\DynamicLayers, with a web browser (port 49153 is
the default Sun Application Server web server port, replace as necessary).

- The user is redirected to an authentication page provided by the
policy agent and asked to enter login and password credentials.

- User credentials are verified against the directory server via
the policy agent and the identity server.

- If matching credentials are not found, the user is presented with an error
page which prompts to try again.

- If credentials are matched, the DynamicLayers web application page opens
in the browser. The choice of available map layers is dependent on the user's
associated role. Each role is authorized to access some subset of available
layers. For example, users in the administrator role can access 4 layers, while
those in the customer role can only access 2 layers.

Procedure

Perform the following in the order given:

Step One: Install the required software:

Sun Java Studio Enterprise 6 (2004Q1)
ArcGIS ArcCatalog
ArcGIS Server
ArcGIS Server software developer kit
ArcGIS Server Java ADF

The necessary components installed and configured by the Sun Java Studio Enterprise 6 (2004Q1) installer include the Java System Application Server 7, the Identity Server 6.1, the Directory Server and the Policy Agent. A policy agent is a java class that handles authentication and authorization for the application server container hosting web applications. The Directory Server and Identity Server are the tools used to create users and associated roles that policy agents can poll to authenticate and authorize users according to the security constraints declared in the application deployment descriptors. Either the Sun Java Studio IDE or any text editor can be used to modify the files referenced in this article.

After installing ArcCatalog, ArcGIS Server, ArcGIS Server software developer kit and ArcGIS Server Java ADF, you will need to configure a MapServer object to be used by the DynamicLayers sample. To do this, start ArcCatalog and create a new MapServer object called "USA" using the usa.mxd located at <ARCGIS_INSTALL_HOME>\DeveloperKit\samples\data\usa.

For more information on how to configure Server Objects using ArcCatalog, please refer to the ArcGIS Desktop Help.

At this point, you should have access to the source code for the DynamicLayers Web application. The DynamicLayers Web application can be found in the file:

<ARCGIS_INSTALL_HOME>\DeveloperKit\samples\Server_Development\Dynamic_Layers_in_pooled_Server_ObjectsJava.zip

Unzip this file and copy the contents of the newly created 'Java' sub-directory to a workspace directory, hereafter referred to as <WORKSPACE_DIR> in this article.

Step Two: Configure users and roles with the Indentity Server

To implement authorization and authentication for the DynamicLayers Web application:

A. Start the Identity console
- Follow the instructions given in the following link to start your Identity Server console: Starting the Identity Server Console

B. Create two roles: 'Administration' and 'Customer'
- Follow the instructions at the following link: Creating the Roles and create 'Administration' and 'Customer'.

C. Create at least two users
- Follow the instructions at the following URL: Creating the Users and create two users: 'admin' and 'acustomer'.

D. Associate users to roles
- Follow the instructions at the following URL: Assigning Users to Roles and associate the 'admin' user to the 'Administration' role and the 'acustomer' user to the 'Customer' role.

Step Three: Update DynamicLayers application code for the new authorization policy

Making the authorization policy for the DynamicLayers application allows access to the layers. Users in the 'Customer' role have access to two of four layers; users in the 'Administration' role have access to all four layers.

Note:
The following instructions use command line tools only but it is possible to use the integrated Sun One IDE to edit and deploy your application:

A. Edit the LayerCatalog.java file

1. Use a command window to navigate to the $WORKSPACE_DIR and unjar the dynamiclayers.jar file by typing:
jar -xf dynamiclayers.jar

2. Navigate to $WORKSPACE_DIR\WEB-INF\classes\com\esri\arcgis\webcontrols\test and edit the file LayerCatalog.java:
a. Add the following import statement after the line, "import javax.faces.model.SelectItem;":

Code:
import javax.faces.context.FacesContext;

b. Replace the line "private static String CATALOG_FILE = "com/esri/arcgis/webcontrols/test/catalog.properties""; with the following lines:

Code:
private static String ADMIN_CATALOG_FILE = "com/esri/arcgis/webcontrols/test/admin_catalog.properties";
private static String CUSTOMER_CATALOG_FILE = "com/esri/arcgis/webcontrols/test/customer_catalog.properties";

c. Also replace the line "InputStream stream = this.getClass().getClassLoader().getResourceAsStream(CATALOG_FILE);" with the following lines:

Code:
boolean is_admin = FacesContext.getCurrentInstance().getExternalContext().isUserInRole("administration");
InputStream stream = null;

if(is_admin) {
stream = this.getClass().getClassLoader().getResourceAsStream(ADMIN_CATALOG_FILE);
} else {
stream = this.getClass().getClassLoader().getResourceAsStream(CUSTOMER_CATALOG_FILE);
}


B. Create the referenced catalog properties files

1. In the $WORKSPACE_DIR\WEB-INF\classes\com\esri\arcgis\webcontrols\test directory rename the file 'catalog.properties' to 'admin_catalog.properties' (no quotes).
2. Using the template provided in the file, edit the file to reference four layers.
3. Make a copy of the admin_catalog.properties file and name it 'customer_catalog.properties' (no quotes).
4. Edit this new file and remove two of the four layers.

C. Compile the web application

1. In a command window navigate to $WORKSPACE_DIR.
2. Create a new source jar file by typing: jar -cf dynamiclayers.jar *
3. Build the application by typing: arcgisant build
4. Enter the necessary impersonation information in the GUI that displays.
5. Click Check Connection.
6. Click OK. Your new Web application is created in the $WORKSPACE_DIR\dist directory.
7. Delete the file $WORKSPACE_DIR\dist\DynamicLayers.war. This will be re-created later.

Step Four: Configure the Web application deployment descriptors

Configuring the deployment descriptors is done by editing two Web application deployment description files: web.xml and sun-web.xml. Follow the steps in the order given below:

A. Declare the policy filter

At runtime, the servlet container filter works with the policy agent to enforce authentication. Insert the following filter declaration into $WORKSPACE_DIR\dist\DynamicLayers\WEB-INF\web.xml after the declaration of other filters:

Code:
<filter>
<filter-name>AmAgentFilter</filter-name>
<display-name>AmAgentFilter</display-name>
<filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
</filter>

Insert the following filter mapping declaration into the web.xml after the declaration of any other filter mappings:

Code:
<filter-mapping>
<filter-name>AmAgentFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

B. Add security constraints, roles and mappings

Configure the <security-constraint> element to protect the application URLs using an authorized role; DEFAULT is used to aggregate the Administration and Customer roles. Add the following lines to $WORKSPACE_DIR\dist\DynamicLayers\WEB-INF\web.xml after the <error-page> element:

Code:
<security-constraint>
<web-resource-collection>
<web-resource-name>ALL</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>DEFAULT</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<role-name>DEFAULT</role-name>
</security-role>
<security-role>
<role-name>administration</role-name>
</security-role>
<security-role>
<role-name>customer</role-name>
</security-role>

C. Configure the Web Application Authentication Method

Set FORM based authentication with the <login-config> element by inserting the following lines into $WORKSPACE_DIR\dist\DynamicLayers\WEB-INF\web.xml after the <security-constraint> element:

Code:
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/index.html</form-login-page>
<form-error-page>/timeout.html</form-error-page>
</form-login-config>
</login-config>

In the $WORKSPACE_DIR\dist\DynamicLayers\WEB-INF directory create a new file, sun-web.xml, and insert the following lines to map the web.xml security roles to the Identity Server roles:

Code:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 Servlet 2.3//EN"
"http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_3-0.dtd">

<sun-web-app>
<security-role-mapping>
<role-name>DEFAULT</role-name>
<group-name>Customer</group-name>
<group-name>Administration</group-name>
</security-role-mapping>
<security-role-mapping>
<role-name>administration</role-name>
<group-name>Administration</group-name>
</security-role-mapping>
<security-role-mapping>
<role-name>customer</role-name>
<group-name>Customer</group-name>
</security-role-mapping>
<session-config>
<session-manager persistence-type="memory">
<manager-properties/>
<store-properties/>
</session-manager>
<session-properties/>
<cookie-properties/>
</session-config>
<cache max-entries="4096" timeout-in-seconds="30" enabled="true">
<default-helper/>
</cache>
<jsp-config>
<property value="true" name="classdebuginfo">
<description>Enable debug info compilation in the generated servlet class</description>
</property>
<property value="true" name="mappedfile">
<description>Maintain a one-to-one correspondence between static content
and the generated servlet class' java code</description>
</property>
</jsp-config>
</sun-web-app>


Step Five: Deploy the DynamicLayers Web application

A. Create a Web archive file (WAR) and deploy it to the SUN Application Server. B. In the $WORKSPACE_DIR\dist\DynamicLayers directory, at a command prompt type:jar -cf ..\DynamicLayers.war *

This creates a WAR file in the $WORKSPACE_DIR\dist directory, deployed to the application server by following the instructions in the application server Help.

B. To use the application, access the URL http://localhost:<your port>/DynamicLayers. When logging in as the 'admin' user, notice four layers available from the 'Add Layer' toolbar menu item; otherwise there are two.

If the application does not properly authenticate, restart your application server; this often solves authentication problems.

Related Information