Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

Realms, 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 name 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's authentication service includes the following components:

Setting up 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 security role on the server that can be used by many Web services applications, you set up the users and roles that are defined for the server using admintool or by entering the information directly into <JWSDP_HOME>/conf/tomcat-users.xml. For information on setting up users and roles using admintool, see Managing Roles and Users.

To authorize one of the roles set up on the server to access a particular application, you list the authorized security roles in the application's deployment descriptor, web.xml.

The following example shows the role mapping between the application-defined role admin and the admin role that was defined when the Java WSDP was installed.

  1. Select or open the Web application deployment descriptor, for example, <INSTALL>/jwstutorial12/examples/gs/web/WEB-INF/web.xml.
  2. Add a security constraint such as the one shown below. In this example, the role of admin is authorized to access this application, and is assigned a security role.
  3.   <!-- SECURITY CONSTRAINT -->
      <security-constraint>
        <web-resource-collection>
          <web-resource-name>WRCollection</web-resource-name>
          <url-pattern>/index.jsp</url-pattern>
          <http-method>GET</http-method>
        </web-resource-collection>
        <auth-constraint>
          <role-name>admin</role-name>
        </auth-constraint>
        <user-data-constraint>
          <transport-guarantee>NONE</transport-guarantee>
        </user-data-constraint>
      </security-constraint>
    <login-config>
        <auth-method>BASIC</auth-method>
    </login-config>

      <!-- SECURITY ROLES -->
      <security-role>
        <description>the administrator role</description<
        <role-name>admin</role-name>
      </security-role>

The <role-name> that you specify in the deployment descriptor must have a corresponding entry in your server-specific file that contains the list of users and their assigned roles. For the Tomcat server, the file is <JWSDP_HOME>/conf/tomcat-users.xml. The entry needs to declare a mapping between a security role and one or more principals in the realm. An example for the Tomcat server might be as follows:

<?xml version='1.0'?>
<tomcat-users>
  <role rolename="customer" description="Customer of Java Web
    Service"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="your_name" password="your_password"
    roles="admin,manager"/>
  <user username="Anil" password="12345" fullName=""
    roles="customer"/>
</tomcat-users> 

Another example for another Web Server might be as follows:

<rolemapping>
   <role name="admin">
   <principals>
      <principal>
         <name>Khalil Singh</name>
      </principal>
   </principals>
   </role>
</rolemapping> 

Managing Roles and Users

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, the roles that have been defined for this server, and any users or roles you added after installation. The user name defined during installation is initially associated with the predefined roles of admin and manager. 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. We recommend that you use admintool in order to maintain the integrity of the users file.

Initially, the tomcat-users.xml file looks like this:

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

You can add roles and users using admintool, a GUI tool that enables you to make changes to the running Tomcat server. The file <JWSDP_HOME>/conf/tomcat-users.xml is updated as the changes are made in admintool. See Appendix A for information on admintool.

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

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 Role Actions list display in the right pane. By default, the roles defined during Java WSDP installation are displayed. These roles include admin and manager.

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

  1. From the Role Actions List, select Create New Role.
  2. Enter the name of the role to add.
  3. Enter 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 Role Actions List, select Delete Existing Roles.
  2. Select the role to remove by checking the box to its left.
  3. Select Save.

If you entered a new role of customer, the tomcat-users.xml file would now look like this:

<?xml version='1.0'?>
<tomcat-users>
  <role rolename="customer" description="Customer of Java Web
    Service"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="your_name" password="your_password"
    roles="admin,manager"/>
</tomcat-users> 

Managing Users

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

The Users List and User Actions 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 the user profile to edit in the right pane.
  2. Edit the existing user properties. You can modify a password and/or modify role assignments in this window.

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

  1. From the User Actions List, select Create New User.
  2. Enter the name of the user to add.
  3. Enter the password for that user.
  4. Enter the full name of the user.
  5. Select the role assignments 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. Select Delete Existing Users from the User Actions list.
  2. 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. If I added a new user named Anil and assigned him the role of customer, the updated tomcat-users.xml would look like this:

<?xml version='1.0'?>
<tomcat-users>
  <role rolename="customer" description="Customer of Java Web
    Service"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="your_name" password="your_password"
    roles="admin,manager"/>
  <user username="Anil" password="12345" fullName=""
    roles="customer"/>
</tomcat-users> 
Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

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