Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
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:
- Realm - For a Web application, a realm is a complete database of roles, users, and groups that identify valid users of a Web application (or a set of Web applications).
- User - An individual (or application program) identity that has been authenticated (authentication is discussed in Using Login Authentication). In a Web application, a user can have a set of roles associated with that identity, which entitles them to access all resources protected by those roles. In a Web Services application, users can be associated with a group, which categorizes users by common traits.
- Group - A set of authenticated users classified by common traits such as job title or customer profile. In most cases for Web applications, you will map users directly to roles and have no need to define a group.
- Role - An abstract name for the permission to access a particular set of resources in a Web application. 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.
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 ofdirector
. Theadmin
role may let you view some employee data, but thedirector
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 usingadmintool
, 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 theadmin
role that was defined when the Java WSDP was installed.
- Select or open a Web application deployment descriptor, for example,
<
INSTALL
>/jwstutorial13/examples/security/login/web/WEB-INF/web.xml
.- 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.
<!-- 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>- 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:
<?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>- 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 ofadmin
andmanager
. You can edit the users file directly in order to add or remove users or modify roles, or you can useadmintool
to accomplish these tasks. We recommend that you useadmintool
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 inadmintool
. See Appendix Administering Roles, Groups, and Users for information on adding users and roles usingadmintool
.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
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.