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.

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 can set up the users and roles using admintool, or in a deployment descriptor, then declare it for the WAR file that is contained in the application. For information on setting up users and roles using admintool, see Managing Roles and Users.

The following example code shows how you would set up roles in the web.xml deployment descriptor for the Web component. As is shown, you can define multiple security roles for an application.

  <security-role>
    <role-name>admin</role-name>
  </security-role>
  <security-role>
    <description>Book customer</description>
    <role-name>customer</role-name>
  </security-role>

The <role-name> that you specify in the deployment descriptor must have a corresponding entry in your server-specific deployment descriptor. 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>
<user username='your_name' password='your_password'
  roles='admin,manager,provider'/>
<user username='Joe' password='scooby'
  roles='admin,manager,provider'/>
<user username='Mikhail' password='goblin'
  roles='admin'/>
</tomcat-users>

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

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.

<?xml version='1.0'?>
<tomcat-users>
<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. Before starting Tomcat, make sure that your PATH environment variables are set properly and that the build.properties file has been created properly. These steps are described in Setting Up.

Starting Tomcat

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

Start a Web browser.

In the Web browser, point to the following URL:

  http://localhost:8080/admin

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

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

The modifications discussed in the following sections 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 Role 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.

From the Role Actions List, select Create New Role.

Enter the name of the role to add.

Enter the description of the role.

Select Save when done. The newly defined role displays in the list.

From the Role Actions List, select Delete Existing Roles.

Select the role to remove by checking the box to its left.

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="provider"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="your_name" password="your_password"
    roles="admin,manager,provider"/>
</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 Available Actions list for User Actions display in the right pane. By default, the user name defined during Java WSDP installation is displayed.

Select the user profile to edit in the right pane.

Edit the existing user properties. You can modify a password and/or modify role assignments in this window.

From the User Actions List, select Create New User.

Enter the name of the user to add.

Enter the password for that user.

Enter the full name of the user.

Select the role assignments for this user.

Select Save when done. The newly defined user displays in the list.

Select Delete Existing Users from the User Actions list.

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. 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="provider"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="your_name" password="your_password"
    roles="admin,manager,provider"/>
  <user username="Anil" password="12345" fullName=""
    roles="customer"/>
</tomcat-users>

Declaring and Linking Role References

A security role reference allows a Web component to reference an existing security role. A security role is an application-specific logical grouping of users, classified by common traits such as customer profile or job title. When an application is deployed, roles are mapped to security identities, such as principals (identities assigned to users as a result of authentication) or groups, in the operational environment. Based on this, a user with a certain security role has associated access rights to a Web application. The link is the actual name of the security role that is being referenced.

During application assembly, the assembler creates security roles for the application and associates these roles with available security mechanisms. The assembler then resolves the security role references in individual servlets and JSPs by linking them to roles defined for the application.

The security role reference defines a mapping between the name of a role that is called from a Web component using isUserInRole(String name) (see Using Programmatic Security in the Web Tier) and the name of a security role that has been defined for the application.

For example, the mapping of the security role reference cust to the security role with role name bankCustomer, is shown in the <security-role-ref> element of the deployment descriptor, as shown:

<security-role-ref>
  <role-name>cust</role-name>
  <role-link>bankCustomer</role-link>
</security-role-ref>

In this example, isUserInRole("bankCustomer") and isUserInRole("cust") will both return true.

Because a coded name is linked to a role name, you can change the role name at a later time without having to change the coded name. For example, if you were to change the role name from bankCustomer to something else, you wouldn't need to change the cust name in the code. However, you would need to relink the cust coded name to the new role name.

Mapping Application Roles to Realm Roles

When you are developing a Web services application, you don't need to know what roles have been defined for the realm in which the application will be run. In the Java WSDP, the Web services security architecture provides a mechanism for automatically mapping the roles defined in the application to the roles defined in the runtime realm. 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.

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. The following is an example of the security constraint that could be added to the application's deployment descriptor.

Select or open the Web application deployment descriptor, for example, <JWSDP_HOME>/docs/tutorial/examples/gs/web/WEB-INF/web.xml.

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. For example, in the Tomcat server, this information is reflected in the runtime XML, as shown:


  <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>

  
  <security-role>
    <description>the administrator role</description<
    <role-name>admin</role-name>
  </security-role>

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

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