The JavaTM Web Services Tutorial
Home
TOC
PREV TOP NEXT

Users, Groups, and Roles

A Web services user is similar to an operating system user. Typically, both types of users represent people. However, these two types of users are not the same. The Tomcat server authentication service has no knowledge of the user and password you provide when you log on to the operating system. The Tomcat server authentication service is not connected to the security mechanism of the operating system. The two security services manage users that belong to different realms.

The Tomcat server authentication service includes the following components:

Security Roles

When you design a Web component, you should always think about the kinds of users who will access the component. For example, a Web application for a Human Resources department might have a different request URL for someone who has been assigned the role of admin than for someone who has been assigned the role of director. The admin role may let you view some employee data, but the director role enables you to view salary information. Each of these security roles is an abstract logical grouping of users that is defined by the person who assembles the application. When an application is deployed, the deployer will map the roles to security identities in the operational environment.

A Tomcat server group also represents a category of users. Categorizing users into groups makes it easier to control the access of large numbers of users. For example, most customers of a Web application might belong to the CUSTOMER group, but the big spenders would belong to the PREFERRED group. Groups are also associated with a set of roles, and every user that is a member of a group inherits all of the roles assigned to that group.

To create a role for a Web services application, you first set up the users and roles using admintool, then declare it for the WAR file that is contained in the application.

Managing Groups, Roles, and Users

To manage the information in the users file, we recommend that you use admintool. To use admintool, point your browser to http://localhost:8080/admin/ and log on with a user name and password combination that has been assigned the admin role, such as the user name and password that you entered during installation.

For security purposes, admintool, the Tomcat Server Administration application, verifies that you (as defined by the information you provide when you log into the application) are a user who is authorized to install and reload applications (defined as a user with the role of admin in tomcat-users.xml) before granting you access to the server.

The <JWSDP_HOME>/conf/tomcat-users.xml file is created by the installer. It contains the user name and password created during installation of the Java WSDP. This user name is initially associated with the predefined roles of admin, manager, and provider. You can edit the users file directly in order to add or remove users or modify roles, or you can use admintool to accomplish these tasks, as described herein.

The tomcat-users.xml file looks like this:

<?xml version='1.0'?>	
<tomcat-users>	
<role rolename="admin"/>	
<role rolename="manager"/>	
<role rolename="provider"/>	
<user username="your_name" password="your_password"	
     roles="admin,manager,provider"/>	
</tomcat-users>
 

The following sections describe how to add roles, groups, and users using admintool. An updated version of tomcat-users.xml is created in the process.

Using the Tomcat Administration Tool

To use admintool, the Tomcat Server Administration application, you must start Tomcat.

Starting Tomcat

To start Tomcat, type the following command in a terminal window.

<JWSDP_HOME>/bin/startup.sh        (Unix platform)
 
<JWSDP_HOME>\bin\startup.bat       (Microsoft Windows)
 

The startup script starts the task in the background and then returns the user to the command line prompt immediately. Even though you are returned to the command line, the startup script may not have completely started Tomcat. If admintool does not run immediately, wait up to a minute and then reload it.

Documentation for Tomcat can be found at <JWSDP_HOME>/docs/tomcat/index.html.

Starting admintool

Once the Tomcat server is started, follow these steps to start admintool.

  1. Start a Web browser.
  2. In the Web browser, point to the following URL:
       http://localhost:8080/admin
     
    
  3. Log in to admintool using a user name and password combination that has been assigned the role of admin.
  4. When you have finished, log out of admintool by selecting the appropriate link in the upper pane.

The following sections show how to use admintool to do the following:

This section uses the Getting Started application discussed in Getting Started With Tomcat as an example. These modifications are made to the running Tomcat server--it is not necessary to stop and restart Tomcat.

Managing Roles

Use the following procedure to view all existing roles in the realm.

  1. In the left pane, scroll down to the User and Group Administration entry.
  2. Expand the listing by selecting the magnifying glass.
  3. Select Role Administration. The Roles List and Available Actions list display in the right pane. By default, the roles defined during Java WSDP installation are displayed. These roles include admin, manager, and provider.

Use the following procedure to add a new role to the default realm.

  1. From the Roles List, select Create New Role.
  2. Enter customer for the name of the role to add.
  3. Enter Customer of the Getting Started application as the description of the role.
  4. Select Save when done. The newly defined role displays in the list.

Use the following procedure to remove a role from the default realm.

  1. From the Roles List, select Delete Existing Roles from the Available Actions list.
  2. From the Roles window, select the role to remove by checking the box to its left.
  3. Select Save.

Managing Groups

Use the following procedure to view all existing groups in the realm.

  1. In the left pane, scroll down to the User and Group Administration entry.
  2. Expand the listing by selecting the magnifying glass.
  3. Select Group Administration. The Groups List and Available Actions list display in the right pane. By default, no groups are defined.

Use the following procedure to add a new group to the default realm.

  1. From the Groups List, select Create New Group.
  2. Enter gsuser as the name of the group to add.
  3. Enter Users of the Getting Started application as the description of the group.
  4. Select the customer role to include in this group.
  5. Select Save when done. The newly defined group displays in the list.

Use the following procedure to remove a group from the default realm.

  1. From the Groups List, select Delete Existing Group from the Available Actions list.
  2. From the Groups window, select the group to remove by checking the box to its left.
  3. Select Save.

Managing Users

Use the following procedure to view all existing users in the realm.

  1. In the left pane, scroll down to the User and Group Administration entry.
  2. Expand the listing by selecting the magnifying glass.
  3. Select User Administration. The User List and Available Actions list display in the right pane. By default, the user name defined during Java WSDP installation is displayed.

Use the following procedure to add a new user to the default realm.

  1. From the Users List, select Create New User.
  2. Enter Duke as the name of the user to add.
  3. Enter javarocks as the password for that user.
  4. Enter Duke the Java programming wiz as the full name of the user.
  5. Select the gsuser group(s) for this user. Since this group has been assigned the role of customer, users in this group will inherit this role.
  6. Select Save when done. The newly defined user displays in the list.

Use the following procedure to remove a user from the default realm.

  1. From the Users List, select Delete Existing Users from the Available Actions list.
  2. From the Delete Existing Users window, select the user to remove by checking the box to its left.
  3. Select Save.

The additions of a new group, role, and user as described in the previous section are reflected in the updated tomcat-users.xml. It now contains the following data:

<?xml version='1.0'?>	
<tomcat-users>	
   <role rolename="admin"/>	
   <role rolename="customer" description="Customer 	
      of the GS app"/>	
   <role rolename="manager"/>	
   <role rolename="provider"/>	
   <group groupname="gsuser" description="Users of the 	
      GS app" roles="customer"/>	
   <user username="your_name" password="your_password" 	
      roles="admin,manager,provider"/>	
   <user username="Duke" password="javarocks" 	
      fullName="Duke the Java Programming wiz" 
groups="gsuser"/>	
</tomcat-users>
 

Mapping Application Roles to Realm Roles

When you are developing a Web services application, you will know the roles that you have used in the application, but you probably won't know exactly what roles have been defined for the realm. In a future version of the Java WSDP, that may be taken care of in the Web services security architecture, because after your application has been deployed, the administrator of the Tomcat server will map the roles of the application to the roles of the default realm.

In the EA2 release of the Java WSDP, you create a role for a Web services application by first setting up the roles and users using admintool, as discussed in Managing Groups, Roles, and Users. Then, using deploytool, you set up the authorized roles for the WAR file that is contained in the application.

For example, use the following procedure to create a role for the WAR file using deploytool and the role of customer set up in Using the Tomcat Administration Tool. This example uses the gs.war created in the Getting Started application, as discussed in Deploying the Application Using the Application Deployment Tool.

  1. Start the deploytool. The deploytool is a command line tool that is located in the bin directory of your Java WSDP installation. To start it, open a terminal window or command prompt and enter:
    <JWSDP_HOME>/bin/deploytool
  2. Select or open the Web application's WAR file, <JWSDP_HOME>/docs/tutorial/examples/gs/gs.war.
  3. In the Roles tabbed pane, click Add.
  4. In the table, enter customer for the Name field and GSApp Customer in the Description field. This role must match a role in the tomcat-users.xml file (see Managing Roles).

An administrator can authorize roles to access this Web application by selecting them in deploytool. However, before you can authorize a role for a Web application, you must create a security constraint. For more information, refer to the section Controlling Access to Web Resources.

Home
TOC
PREV TOP NEXT