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

> `<!-- 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:

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

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

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.