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).
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
adminthan for someone who has been assigned the role of
adminrole may let you view some employee data, but the
directorrole 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/adminand log on with a user name and password combination that has been assigned the
adminrole, 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
tomcat-users.xml) before granting you access to the server.
>/conf/tomcat-users.xmlfile 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
provider. You can edit the users file directly in order to add or remove users or modify roles, or you can use
admintoolto accomplish these tasks, as described herein.
tomcat-users.xmlfile 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
/conf/tomcat-users.xmlis updated as the changes are made in
Using the Tomcat Web Server Administration Tool
admintool, the Tomcat Web Server Administration Tool, you must start 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 <
Once the Tomcat server is started, follow these steps to start
- Start a Web browser.
- In the Web browser, point to the following URL:http://localhost:8080/admin
- Log in to
admintoolusing a user name and password combination that has been assigned the role of
admintoolutility displays in the Web browser window:
Figure 17-1 The Tomcat Web Server Administration Tool
- When you have finished, log out of
admintoolby selecting Log Out.
The following sections show how to use
admintoolto 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.
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
Use the following procedure to add a new role to the default realm.
- From the Roles List, select Create New Role.
userfor the name of the role to add.
Getting Started App Security Roleas the description of the role.
- Select Save when done. The newly defined role displays in the list.
Use the following procedure to remove a role from the default realm.
- From the Roles List, select Delete Existing Roles from the Available Actions list.
- From the Roles window, select the role to remove by checking the box to its left.
- Select Save.
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.
- Select Users from the User Definition section in the left pane.
- Select the user profile to edit in the right pane.
- Edit the existing user properties.
Use the following procedure to add a new user to the default realm.
- From the Users List, select Create New User.
Dukeas the name of the user to add.
javarocksas the password for that user.
Duke the Java programming wizas the full name of the user.
- Select the
userrole for this user.
- Select Save when done. The newly defined user displays in the list.
Use the following procedure to remove a user from the default realm.
- From the Users List, select Delete Existing Users from the Available Actions list.
- From the Delete Existing Users window, select the user to remove by checking the box to its left.
- 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
admintooland want to run
deploytoolusing the new or modified user profile, Tomcat must be stopped and restarted. This is because the
admintoollogin requires that the user name and password in the
build.propertiesfile match a user name and password with the proper role assignment in
tomcat-users.xml. When you want to log in to
deploytoolusing a new or modified user profile, follow these steps:
admintool, assign the new user the roles of
manager. The role of
adminis required for
deploytool. The role of
manageris required for
- Log out of
- Shut down Tomcat.
- Edit the
build.propertiesfile to match the new or modified user name and password. For more about the
build.propertiesfile, see Creating the Build Properties File.
- Start Tomcat (waiting about 3 minutes for it to fully load).
deploytool. Enter a user name and password from
tomcat-users.xmlthat is assigned the roles of
manager, and that matches the user name and password from
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
userset up in Using the Tomcat Web Server Administration Tool for the Getting Started application. This example uses the
gs.warcreated in the Getting Started application, as discussed in Deploying the Application Using deploytool.
- Make sure Tomcat is running.
deploytoolutility is a command line tool that is located in the
bindirectory of your Java WSDP installation. To start it, open a terminal window or command prompt and enter:
- Enter a user name and password that has been assigned the role of
adminin the Set Tomcat Server dialog.
- Select or open the Web application's WAR file,
- Select the Security pane.
- Add a Security Constraint by selecting the Add button beside the Security Constraints field.
- Select the Edit button below Authorized Roles to add an authorized role to the application.
- Select Import Roles to import the roles previously defined using
- Select User, select Add, then select OK to close this dialog.
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.