Home TOC Index

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:

• Role - an abstract name for the permission to access a particular set of resources. A role can be compared to a key that can open a lock. Many people might have a copy of the key, and the lock doesn't care who you are, just that you have the right key.
• User - an individual (or application program) identity that has been authenticated (authentication was discussed in the previous section). A user can have a set of roles associated with that identity, which entitles them to access all resources protected by those roles.
• Group - a set of authenticated users classified by common traits such as job title or customer profile. 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. In most cases, you will map users directly to roles and have no need to define a group.
• Realm - a complete database of roles, users, and groups that identify valid users of a Web application (or a set of Web applications).

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.

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 Roles and Users

To manage the information in the users file, we recommend that you use admintool. To use admintool, start Tomcat, then 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 Web Server Administration Tool, 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, in plain text, 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 and users using admintool. The file JWSDP_HOME/conf/tomcat-users.xml is updated as the changes are made in admintool.

Using the Tomcat Web Server Administration Tool

To use admintool, the Tomcat Web Server Administration Tool, 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. The startup script does not completely start Tomcat for several minutes.

---

Note: The startup script for Tomcat can take several minutes to complete. To verify that Tomcat is running, point your browser to http://localhost:8080. When the Tomcat splash screen displays, you may continue. If the splash screen does not load immediately, wait up to several minutes and then retry. If, after several minutes, the Tomcat splash screen does not display, refer to the troubleshooting tips in "Unable to Locate the Server localhost:8080" Error.

---

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.

The admintool utility displays in the Web browser window:

Figure 17-1 The Tomcat Web Server Administration Tool

4. When you have finished, log out of admintool by selecting Log Out.

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

• Display all roles in the default realm
• Add a role to the default realm
• Remove a role from the default realm
• Display all users in the default realm
• Add a user to the default realm
• Remove a user

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

To view all existing roles in the realm, select Roles from the User Definition section in the left pane.

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 user for the name of the role to add.
3. Enter Getting Started App Security Role 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 Users

To view all existing users in the realm, select Users from the User Definition section in the left pane.

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 edit a user's profile.

1. Select Users from the User Definition section in the left pane.
2. Select the user profile to edit in the right pane.
3. Edit the existing user properties.

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 user role for this user.
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 addition of a new 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="user" description="Getting Started
     App Security Role"/>
   <role rolename="manager"/>
   <role rolename="provider"/>
   <user username="your_name" password="your_password"
      roles="admin,manager,provider"/>
   <user username="Duke" password="javarocks"
      fullName="Duke the Java Programming wiz"
      roles="user"/>
</tomcat-users>
 

Considerations When Changing a User Profile

When you add a user or change a user name or password using admintool, the changes are written to the file tomcat-users.xml, as discussed in Managing Users. When Tomcat is started, it reads the information in tomcat-users.xml. When you make changes to a user or add a user using admintool, then save the changes, the changes are made to the running Tomcat server - no need to shut down and restart Tomcat.

However, if you add a new user or modify the default user name or password using admintool and want to run deploytool using the new or modified user profile, Tomcat must be stopped and restarted. This is because the deploytool and admintool login requires that the user name and password in the build.properties file match a user name and password with the proper role assignment in tomcat-users.xml. When you want to log in to deploytool using a new or modified user profile, follow these steps:

1. In admintool, assign the new user the roles of admin and manager. The role of admin is required for admintool and deploytool. The role of manager is required for deploytool.
2. Log out of admintool.
3. Shut down Tomcat.
4. Edit the build.properties file to match the new or modified user name and password. For more about the build.properties file, see Creating the Build Properties File.
5. Start Tomcat (waiting about 3 minutes for it to fully load).
6. Start deploytool. Enter a user name and password from tomcat-users.xml that is assigned the roles of admin and manager, and that matches the user name and password from build.properties.

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 the Java WSDP, that is taken care of in the Web services security architecture. 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 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 Roles and Users. Then, using deploytool, you import the defined roles and select which are authorized roles for the WAR file that is contained in the application.

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.

The following example authorizes the role of user set up in Using the Tomcat Web Server Administration Tool for the Getting Started application. This example uses the gs.war created in the Getting Started application, as discussed in Deploying the Application Using deploytool.

1. Make sure Tomcat is running.
2. Start deploytool. The deploytool utility 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
    
   

3. Enter a user name and password that has been assigned the role of admin in the Set Tomcat Server dialog.
4. Select or open the Web application's WAR file, <JWSDP_HOME>/docs/tutorial/examples/gs/gs.war.
5. Select the Security pane.
6. Add a Security Constraint by selecting the Add button beside the Security Constraints field.
7. Select the Edit button below Authorized Roles to add an authorized role to the application.
8. Select Import Roles to import the roles previously defined using admintool.
9. Select User, select Add, then select OK to close this dialog.

Home TOC Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.