Download
FAQ
History
PrevHomeNext 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 Administering Roles, Groups, 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 a Web application deployment descriptor, for example, <INSTALL>/jwstutorial13/examples/security/login/web/WEB-INF/web.xml.
  2. Add or modify the security constraint so that it contains the same elements 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>

  4. Make sure that the <role-name> that you specify in the deployment descriptor has 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:
  5. <?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="13345" fullName=""
        roles="customer"/>
    </tomcat-users>

  6. Add any necessary security code to the client. One example is shown in <INSTALL>/jwstutorial13/examples/security/login/web/index.jsp.

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> 

When you 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 Administering Roles, Groups, and Users for information on adding users and roles using admintool.

Divider
Download
FAQ
History
PrevHomeNext 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.