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 Configuring 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 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 theadmin
role that was defined when the Java WSDP was installed.
- Select or open the Web application deployment descriptor, for example,
<
INSTALL
>/jwstutorial12/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.
<!-- 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 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>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 inadmintool
. See Appendix A for information onadmintool
.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
andmanager
.Use the following procedure to add a new role to the default realm.
Use the following procedure to remove a role from the default realm.
If you entered a new role of
customer
, thetomcat-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.
Use the following procedure to add a new user to the default realm.
Use the following procedure to remove a user from the default realm.
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 ofcustomer
, the updatedtomcat-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>
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.