Administrative console tutorial: Standard Edition


Last updated: 7/25/2000

MANY GRAPHICS: PLEASE BE PATIENT AS IT LOADS.

Welcome to the IBM WebSphere Application Server Version 3.5 Standard Edition administrative console tutorial.

The tutorial demonstrates how, when, and why to use the central administrative tasks. It also discusses tasks you need to complete outside of the administrative console to complement and support the administrative tasks.

Using some of the Application Server sample files, you can configure and secure an application comprised of HTML files, servlet files, and JavaServer Pages (JSP) files.

In the course of completing the sections of this tutorial, you will experience the end-to-end process of managing applications in IBM WebSphere Application Server Version 3.5:

Step 1: Plan and prepare

Learn about:

The tutorial scenario

You are part of a Web site team. To save time maintaining sites, a team member has written a handy application that lets you specify "expiration dates" for Web pages. When page expires, it is automatically replaced by another page.

These files comprise the "Expiring Page" application:

For more information about ExpiringHTMLPage, open the index.html file in the WebSphereSamples directory of your product installation.

Sample files used in the tutorial

ExpiringHTMLInputPage.html
This HTML file provides an input form where you set the expiration date.

The sample file is located in:

install_root\hosts\default_host\WSsamples_app\web\WebSphereSamples\ExpHTMLServlet
where install_root is the root of your WebSphere Application Server installation. Note, the slashes will vary ("\" or "/") depending on your operating system.
ExpiringHTMLAfterDatePage.jsp
This is the page you want served after the expiration date.

This sample file is located in:

install_root\hosts\default_host\WSsamples_app\web\WebSphereSamples\ExpHTMLServlet
 
ExpiringHTMLBeforeDatePage.jsp
This is the page that you want served up until the expiration date.

This sample file is located in:

install_root\hosts\default_host\WSsamples_app\web\WebSphereSamples\ExpHTMLServlet
ExpiringHTMLServlet.class
This is a Java servlet that compares the expiration date to the current date and decides which page to serve.

This sample file is located in:

install_root\hosts\default_host\WSsamples_app\servlets\WebSphereSamples\ExpHTMLServlet
 
If these files were not part of a predefined tutorial, some planning might be involved prior to beginning administration:

Configure a Web application and supporting resources

This case will demonstrate how to quickly configure an application using mostly the default settings. It will show where to move the application files to, allowing the application to work correctly.

If you selected the "default configuration" option during your Custom installation of WebSphere Application Server, you will already have a default application server, servlet engine, and other resources required to support an application.

This tutorial does not assume you have the default resources installed. The first step of this section demonstrates configuring your own application server and other supporting resources.

In this section, you are going to:

  1. Configure a Web application and supporting resources
  2. Place the application files in WebSphere directories
Note: Slight discrepancies in the screen captures in this tutorial and the actual WebSphere Administrative Console are possible.

Open the WebSphere Administrative Console:

This is the point from which you can perform most of the administration, using task wizards that guide you through the process of configuring, securing, and analyzing the performance of resources and applications.

Notice the "Console ready" message; this indicates that the console is ready for use.

Configure a virtual host

A virtual host is a configuration that allows a single physical machine to resemble multiple host machines. You can isolate applications so that they seem to be on entirely different boxes.

You can configure your own virtual host, but for the purposes of the tutorial, use the default virtual host. You do not need to change any of its settings. Simply verify that it exists.

To view the default host, click the Topology button to display the Topology view. Expand the tree until you locate the "default_host." It should be near the bottom:

When you click it, its properties are displayed on the right side of the console. Most notable are its aliases (click the Advanced tab). Because the default host represents your local machine, its aliases include "localhost," the loopback address (127.0.0.1), and the short and fully-qualified host names of the machine.

It might not be necessary for you to configure a new virtual host for your production environment. A production environment does not necessary require multiple virtual hosts. If yours requires only one virtual host, then the default_host is probably suitable.

Next, configure resources for database support.

Configure database support

The "Expiring Page" application's servlet does not require database access, but it is likely that you will want to set up database access for one or more of your own servlets. If not, you can skip ahead to configuring the Web application, servlet engine, and application server.

The tutorial assumes your servlets are accessing an IBM Universal Database (DB2) Version 6.1.

  Even if you do not have a database right now, you can try these steps for practice. You will receive errors that you can disregard.

During this part of the tutorial, you will:

Let's begin.

Click the Types button to display the Types view. Locate the JDBCDrivers folder. Right-click the folder and select its Create menu option:

You are going to specify the type of JDBC driver you will be using. A JDBC driver is the code that lets Java components access databases. The driver properties dialog will be displayed:

Specify properties for the JDBC driver:

Name
Specify ExpiringPageDB2Driver.

This is the name by which to administer the driver. Here, you have given it a name that indicates it is a DB2 driver for the Expiring Page application to use.

Implementation class
Specify the DB2 choice, com.ibm.db2.jdbc.app.DB2Driver

This is the implementation class of the driver code. If you were using another database such as Oracle instead, you would select the class for that database type.

JTA enabled
Specify No.

This specifies whether the database brand and version supports the Java transaction services.

The remainder of the properties are optional. Do not specify anything for them. When you finish specifying the properties, click OK:

A confirmation dialog verifies that you configured the driver successfully:

The main console window displays the driver in the JDBCDrivers list:

Next, configure a data source that specifies connection pool settings for your database brand and version. In the Types tree, right-click the DataSources folder and click Create:

The data source properties dialog will be displayed:

Specify properties for the data source:

Name
Specify ExpiringPageDB2Dsrc.

This is the name by which you will administer the data source. You have specified a name indicating thatit is a DB2 database for the Expiring Page application's use.

Database Name
Specify WAS. This will be the name of the database you have configured for holding the servlet data (if you chose the default installation option, then this database was created for you automatically).
Driver
Select the ExpiringPageDB2Driver you configured in the previous step.

The remainder of the properties are optional. Click the Advanced tab to see the default values for the connection pool settings. In this case, leave the default values as they are.

When you finish specifying the properties, click OK. A confirmation dialog tells you the data source configuration was successful.

Now that you have a data source, you can return to the JDBC driver and "install" it, specifying the location of the Java code for the driver. Switch to the Topology view, and the WebSphere Admin Domain. You will see, among other things, the JDBC driver and data source you configured:

Click the ExpiringPageDB2Driver. Its properties are displayed on the right side of the console. Right-click it and select Install:

Select your local machine (shown here as rufusdlion) as the node on which to install the driver:

When you do that, the Browse button will become active. Click it to browse for the DB2 JDBC driver code. It should be in the sqllib\java directory of your DB2 installation root:

When you locate the db2java.zip file, select it and click the Open button to return to the driver installation dialog. The zip file will be displayed in the Jar file field:

Click the Install button. Note, this operation does not change the location of the db2java.zip file. It simply specifies the location of the file to the WebSphere administrative server.

Look for the confirmation dialog.

That's it. You now have the resources necessary to support database access by your applications.

Configure a Web application

In this step, you will configure a Web application containing your servlet, JSP, and HTML files. You will also configure an application server and servlet engine to support your Web application.

In the next step, you will wrap the Web application with an enterprise application for the purpose of applying security.

Let's begin.

Press the Wizards button, and select Configure an application server (the first task on the pulldown menu).

The first page of the Wizard is displayed:

On this first panel, you choose whether to configure just the application server, or also the Web application support, including a Web application and a servlet engine.

In this case, select Web Applications. Click Next.

The next screen allows you to configure an application server to handle applications containing servlets:

Specify properties for the application server:

Application Server Name
Specify MyAppServer.

This is the name by which to administer the application server.

The remainder of the properties are optional. Do not specify anything for them. Click Next to continue. The next page lets you decide whether to start the server after configuring it:

Specify that you do not want to start the server automatically. Later, you can practice starting it from the Topology tree.

Click Next to proceed. Now specify the physical machine on which the application server will reside. In this case, select your local node. The hostname in this example is rufusdlion. On your installation, it will be the hostname of your machine.

Click Next to proceed to a panel for selecting a virtual host. Recall, you are going to use the default virtual host. Expand the Virtual Hosts folder to display the default_host:

Notice there is also an option here for configuring a new virtual host, by specifying its name in the Virtual Host Name field. If you did that, the next panel or two of the wizard would let you configure the virtual host properties.

Select default_host and click Next to proceed. You will not see any virtual host configuration panels because default_host is already configured. Instead, you will see servlet engine properties:

Specify properties for the servlet engine:

Servlet Engine Name
Specify MyAppServerServletEngine. This should be the default value anyway.

This is the name by which to administer the servlet engine.

The remainder of the properties are optional. Do not specify anything for them.

To see the settings for communication between the servlet engine and the Web server (for routing requests for servlets from the Web server to the servlet engine), browse the Advanced tab. Notice the Settings button:

Click Next to proceed. Now you are ready to configure a Web application comprised of the servlet, JSP, and HTML files for the Expiring Page application.

Specify the following properties:

Web App Name
Keep the default value, MyAppServerWebApp.

This is the name by which to administer the Web application, and part of the path by which users can access the Web application from a browser. That will be discussed shortly. For your own Web applications, you might consider more descriptive names.

Virtual Host
Specify default_host.
Web Application Web Path
Keep the default value.
Together, the virtual host and the Web path indicate a path for accessing the Web application from a browser:
http://Valid_default_host_alias/webapp/MyAppServerWebApp
where Valid_default_host_alias is any of the aliases you saw earlier in the default_host properties -- the short or fully qualified name of the local machine, the loopback address, "localhost," and so on.

The Web application properties should now look like this:

Click the Advanced tab to view some additional properties.

  If you are performing Step 2b, advanced application configuration, link back to that section now -- this is the point at which the advanced application configuration procedure diverges from the basic application configuration procedure. If you are performing Step 2a, the basic application configuration, ignore this note and continue.

These Web application properties are most notable:

App Doc Root
Accept the default value, install_root\hosts\default_host\MyAppServerWebApp\web

This specifies the location of the HTML and JSP files for the application. After completing this task wizard ("Configure an application server"), you are going to move the files there.

App Classpath
Accept the default value, install_root\hosts\default_host\MyAppServerWebApp\servlets

This specifies the location of the servlets for the application. You will later move the servlet class file there.

As with the above settings, it is optional that you change the rest of the settings from their default values. In this case, accept the default values. Click Next to proceed. On this panel, you can add system servlets to the Web application. System, or internal, servlets are servlets shipped with WebSphere Application Server to support various functions in your Web applications:

Specify which system servlets to use. For the basic application configuration, this is especially important.

Enable File Servlet
Select this check box. It is required because your Web application contains HTML and JSP files.

This enables Web pages to be served from the App Doc Root you specified on an earlier Web application configuration panel. It adds a file servlet to your Web application for this purpose.

In addition to selecting this check box, make sure your Web server configuration file does not contain any pass rules that will override the App Doc Root.

Serve Servlets By Classname
Select this check box. It is required if your Web application contains servlets and you do not plan to configure the servlets explicitly in the administrative domain.

This enables servlets to be served from the servlets directory named in the Web application classpath. Any servlet class you drop into the directory can be loaded by the WebSphere administrative server, without requiring that you identify the servlet by name.

Enable JSP 1.0, Enable JSP .91
Select JSP 1.0. It is required because your Web application contains JSP files.

This specifies to include the JSP enabler servlet supporting the 1.0 level of the JavaServer Pages (JSP) specification. The JSP file for the Expiring Page application is written against the 1.0 specification.
 
 

  All three of these settings are required in order for your Web application containing HTML, servlets, and JSP files to work correctly. Make sure they are all selected:

Here's a tip. Suppose you forget to select one of the check boxes. You can use the "Add a servlet" task on the Wizards button to add the file servlet, enable servlets to be served by class name, and add a JSP enabler.

Now you are ready to finish configuring the application server and its contents. Click Finish and await the confirmation dialog:

You have configured many resources. Use the Topology view to view them. Notice that when you click a resource, such as MyAppServer, its properties are displayed on the right side of the console. You can edit most of them, including adding values for properties you formerly left blank.

You can confirm that the MyAppServerWebApp contains the system servlets you intended. Under the MyAppServerWebApp in the Topology tree, you can see the:

Notice you do not see the ExpiringHTMLServlet servlet listed under the Web application. This is because you have used the basic application configuration procedure in which you do not specify servlets by name in the administrative domain. You would have to configure a servlet resource in the administrative domain and associate it with the Web application in order to see it displayed here.

You can click MyAppServerWebApp to view its properties:

If you forget its document root or classpath values, you can visit the Advanced page:

These directories are where you will be placing the files in the next step.

One more note -- now that you have configured some resources, you can use the Types view to "take inventory" of how many of each type you have. Press the Types view button, and click the ServletEngines folder to view your servlet engines:

So, now you have a Web application and the infrastructure to support it and your Expiring Page enterprise application, once you configure one. You have also configured database access, though in this case you will not need it.

Place the application files in WebSphere directories

Now you must place the Web application files where WebSphere Application Server expects them to be, based on the Web application configuration you specified.

Currently, the directory structure looks like this:

  1. Create any necessary directories to place the files in.
  2. In this case, recall you accepted the default values for the Web application document root and classpath, which are:

    In the WebSphere Application Server installation root, create the directory structure to support the Web application configuration.
  3. Place the HTML and JSP files in directory you specified as the document root of the Web application.
  4. Place the servlet file in the servlet directory you specified in the classpath of the Web application.
Click here to review the names and locations of the HTML, JSP, and servlet files in the Expiring Page sample application.

The directory structure on Windows NT now looks like this:

The HTML and JSP files are in the web directory under the Web application:

And the servlet is in the servlets directory:

Step 3: Configure an enterprise application

In this step, you will in essence "wrap" your Web application with an enterprise application for the purpose of applying security. This is necessary because the product applies security to enterprise applications, not to Web applications.

Press the Wizards button and select Create Enterprise Application:

Name the enterprise application ExpiringPageApp. Click Next to proceed.

For the contents of the application, select the Web application you configured earlier, MyAppServerWebApp. Click Add:

The Console Messages area displays a confirmation message that the operation was successful.

Click Next and expand default_host to see the many Web resources associated with it:

Scroll down until you see the Web resources for MyAppServerWebApp. Select the *.jsp Web resource:

Click Add. It is okay if you receive this message:

If you try to add the same Web resource twice or more, you will receive this message:

When finished, click Next to proceed. The next panel is for removing resources you did not really want to add. It also provides the opportunity to confirm that everything was added. Expand the tree to ensure all of the resources are there.

When satisfied with the content of the application, click Finish. If some files are missing, instead click the Back button to return to the panel for adding resources.

A confirmation dialog informs you that the application was successfully configured:

To view the properties of your new enterprise application, click the Topology button. Locate and click ExpiringPageApp:

Step 4: Secure the administrative domain and applications

Now that you have an enterprise application, you can secure it:
  1. Set up global security and method groups
  2. Secure the application
  3. Create custom method groups
  4. Secure the Account Bean, JSP files, Web pages, and servlets
  5. Grant security permissions

Set up global security and method groups

Follow these instructions to establish default security settings for applications. New applications you create will use the defaults. You can also specify authentication and user registry information that will apply to all applications. Press the Wizards button and select Configure Global Security Settings. The first page of the task looks like this:

This page is where you enable WebSphere Application Server security. If the Enable Security check box is not selected, all security settings in this task and others will be disregarded.

Select the Enable Security check box:

Next, click the Application Defaults tab:

As its name indicates, this tab contains default settings for application security. In other words, when you configure an application, you can override or accept these default values for the individual application.

The rest of the settings in this task are global, meaning they are shared by all applications. They cannot be customized for particular applications.

The Application Defaults tab contains a realm setting.

When a user tries to access the application, he or she will be prompted to log in to the realm. A realm is the domain over which Single Sign On (SSO) is applied. For more information, see "Securing applications."

On the Application Defaults tabbed page, you can specify how users will be challenged for security credentials. For example, they can be prompted for a user ID and password, or a digital certificate instead.

For the Account application, specify Basic authentication.

Click the Authentication Mechanism tab to specify how to authenticate the information presented by users trying to access an application or resources:

For the Account application, specify that users will be authenticated against the users defined in the user registry of the local operating system.

Now click the User Registry tab. Specify the security ID and password under which the WebSphere Application Server security server will run:

The User Registry tab content is dynamic, depending on whether you selected Local Operating System or an LDAP directory service supporting Lightweight Third Party Authentication as the Authentication Mechanism. To observe this, return to the Authentication Mechanism tab and click the LTPA option:

Now click the User Registry tab. You will see a different set of properties than before. With these LDAP properties you can configure authentication with an LDAP-enabled directory service product instead of with the local operating system:

Return to the Authentication Mechanism tab and re-select Local Operating System.  Click Finish to complete the global security settings task.

Start the administrative server again to pick up the changes

The settings on the General, Authentication Mechanism, and User Registry tabbed pages, such as "Enable security," do not take effect until you stop the administrative server and start it again. At this time, switch to the Topology view. Right-click the node for the local machine and click Stop for restart.

This will cause (after the confirmation dialog) the console and adminstrative server to shut down. Start the server and console again to resume the rest of the steps in the tutorial. You can continue the tutorial without doing this, but you will not be able to verify that your application has been secured properly. Also, you might encounter errors during the other security tasks.

Secure the applications

Now configure an individual application, the Account application. Press the Wizards button and select Configure Application Security. On the first panel, select to apply application security to the ExpiringPageApp you configured earlier:

Click Next to proceed. The next panel lets you override the default settings you specified in the "Specify Global Settings" task. Notice you do not have the option to change the truly global security settings you specified in the earlier task. They are shared by this application and all others:

Click Finish to complete the task.

Create custom method groups

Use this task to create custom method groups for protecting the methods of individual resources. You only need custom method groups if you are not satisfied with the default method groups. Go ahead and create a custom method group. Press the Wizards button and select Configure Security Method Groups.  Select Add a new method group:

Click Next, and type MyCustomMethodGroup in the New Method Group field and click Finish:

Secure the JSP files, Web pages, and servlets

In addition to applying security at the application level, configure security for the HTTP methods of each resource. Press the Wizards button and select Configure Resource Security. On the first panel, specify to apply resource security to the servlet directory of the Web application:

You might have to scroll down to locate it. Click Next to proceed. A prompt asks whether to use the default method groups. Specify Yes:

The next panel shows how WebSphere Application Server has grouped the servlet HTTP methods into method groups for protection. The folders represent types of methods encountered in HTTP:

Expand the folders to see which method groups are associated with the methods.  The method groups will protect the methods:

For example, the HTTP_DELETE method has been put in the Remove Methods group. Using the final security task, you will specify who is allowed to access the Remove Methods group.

Suppose you also want your custom method group to protect the HTTP_DELETE method. Select the method and click the Add button:

A dialog box is displayed for selecting a second method group to protect HTTP_DELTE methods:

Specify MyCustomMethodGroup and click OK:

Now MyCustomMethodGroup is displayed below the HTTP_DELETE method, indicating it is protecting that method of the servlets you drop in the Web application's servlets directory:

Click Finish. Start the Configure Resource Security task over again, this time specifying to configure security for all JSP files in the MyAppServerWebApp Web application.

  Hint: When you reach the page for specifying the Web resource to protect, select:

Grant security permissions

Now give users and groups permission to access the resources within your applications. Press the Wizards button and select Configure Security Permissions.  You may view permissions by application or by method group.  Select View By Application, expand the Enterprise Applications folder and select ExpiringPageApp:

Click Next to display this screen, which shows the permissions you can possibly grant to users and groups:

Before granting the ExpiringPageApp permissions, try the following exercise.

Click the AdminApplication-WriteMethods permission. Click the Next button to display a search dialog for specifying the users or groups to whom you want to grant permission to access this method group:


 

You can select to grant Everyone access to those methods. Instead, limit the access to the local operating system administrator. Click Selection to search for that identity. Specify to search for a user, and type "Administrator" in the Search Filter field and click Search. The Administrator is displayed in the Search Results box. Click the Administrator, then click Next:

  Searching for the Administrator is likely to work only on Windows NT machines. If using UNIX, try searching for the "Staff" group, or another user or group ID that you are sure exists on the machine.

Now you see that the administrator has been granted permission to access read-only methods in the Account application:

Now specify permissions for the ExpiringPageApp. Press Back until you see the Permissions panel, then highlight all of the ExpiringPageApp permissions and click Next:

Click Add:

Now change the search dialog box to "All Authenticated Users." Click OK. Verify that each of the ExpiringPageApp permissions has been granted to All Authenticated Users.

Step 5: Verify the application configuration and security

This section describes how to verify that the ExpiringPageApp can be accessed successfully, given its configuration and the security you applied.

Remember that this step is unlikely to be successful if you did not stop the administrative server and start it again after specifying the global security settings.

Now proceed with verification.

First, make sure the application server is aware of the new Web application.

  1. Click the Topology button to display the Topology view.
  2. Expand the tree until you locate MyAppServer.
  3. Click MyAppServer so that it is selected. If the server is currently stopped, click the start button on the console toolbar to start the server. It might take a couple of minutes to start. Messages in the Console Messages area of the WebSphere Administrative Console help you monitor its progress.
  4. If the server was already started, first stop it (using the stop button on the console toolbar), then start it again.

Now the server and its contents are started:

Next, use a browser to test the Web application. Based on the Web application configuration, here is how to assemble the URL for accessing the Web application:

Therefore, valid URLs include:
http://hostname/webapp/ExpHTMLServlet
and
http://IP address/webapp/ExpHTMLServlet
where hostname and IP address are valid default_host aliases as discussed above.

Try one or more of these URLs in a browser to ensure they work. When the ExpiringHTMLInputPage is displayed, try using it to ensure you can access the servlet and JSP functionality. If so, you have successfully configured and applied security to your Web application.

Troubleshooting
If you receive an error: