Securing the Web Services Handler

You can expose your ArcGIS Server services using a Web service handler. In some cases, you may want to make these services available only to certain users. Using manager, you can secure your Web service handlers using role based access control.

According to the principles of role based access control, users are granted membership into roles based on their competencies and responsibilities in the organization. The tasks that a user is permitted to perform are based on the user's role. Membership of roles can be easily withdrawn and new memberships established as the organization evolves; roles can be updated without updating the privileges for every user on an individual basis.

Users and Groups

A user gets defined in the Application Server used, for example, in Tomcat or JBoss. The user in this case is similar to an operating system user. However, the authenticating server has no knowledge of the user name and password you provide when you log on to the operating system and is not connected to the security mechanism of the operating system.

A group is a category of authenticated users classified by common traits, such as job title or customer profile. For example, most customers of an e-commerce application might belong to the CUSTOMER group, but the big spenders would belong to the PREFERRED group. Categorizing users into groups makes it easier to control the access of large numbers of users.

An Application Server group has a different scope from a role. An Application Server group is designated for the entire Application Server, whereas a role is associated only with a specific application in the Application Server.

Roles

A role is an abstract name for the permission to access a particular set of resources in an application. A role can be compared to a key that can open a lock. Many people might have a copy of the key. The lock doesn't care who you are, only that you have the right key.

Users can be associated with a group, and the user/group can be associated with one or multiple roles and can therefore access all resources protected by those roles.

As an example, the members of a city planning department are allowed access to a service showing detailed parcel information and some are allowed to update this data. Each member is a user and part of the planning_department group. Some members have an editor role, while others have a viewer role.

Autentication methods

When each user logs in, he or she is authenticated based on the user name and password. The following authentication methods are available using ArcGIS Server Manager:

• Basic: Basic authentication is the most widely supported authentication mechanism but is not very secure since the username and password are sent in clear text and are not encrypted. ArcGIS Desktop and all browsers supporting HTTP authentication can connect using basic authentication.
• Digest: Digest authentication is widely supported as well and is more secure. ArcGIS Desktop and major Web browsers support this mechanism.
• Form: Form authentication requires the authentication to occur in a Web page form. A login.jsp page is generated in a .war file and users must first go to this page before using the Web services. This mechanism transmits the username and password in clear text unless an HTTPS connection is used. The primary reason for using form based authentication is if you want to have a single sign-on for a custom application that already has a login page. However, this mechanism prevents ArcGIS Desktop from connecting.
• Client: This authentication method requires that each user connecting to the Web service to have a custom generated certificate from a trusted generator of certificates. This mechanism is generally not used for Web services being served to the public on the Internet due to the extra steps requiring a certificate to be generated. This method is more popular for intranets where security is important.

Creating a secure Web Services Handler

The process for creating a secure Web Services Handler is:

• Use ArcGIS Manager to create a Web Services Handler. For more information, please see Exporting the Web Services Handler.
• Deploy the resulting .war file in your Application Server.
• Set up users and roles for the Web application in the Application Server you are using.

Set up users and roles for your server

After using ArcGIS Manager to create a secure Web Services Handler in form of a WAR file, you will need to

1. Deploy the WAR file to a web application
2. Set up users and roles for the web application in the Application Server software you are using.

For example, to enable access to the Parcels web application, you must create a new username/password combination for the according city government members and associate the role name City with it, or add the City role to an existing username/password combination. The steps needed depend on which Application Server you are using. Please see below for the steps for the specific third-party product:

Apache Tomcat

1. Deploy the .war file by placing it in the directory <Tomcat_Home>/webapps/
2. Go to Control Panel > Administrative Tools > Services. Find the Apache Tomcat service in the list and restart it
3. The .war file will explode and create a folder in the same directory with the name of the .war file. For example, after deploying the 'parcels.war' file, you will see a directory called 'parcels' in the webapps directory)

To set up roles in Tomcat, us the Tomcat 5 MemoryRealm interface, which loads information about all users, and their corresponding roles, from the XML document tomcat-users.xml at startup time. Any changes to this file are not recognized until Tomcat is restarted. The file is an XML document with the root element <TOMCAT-USERS> and, nested inside of it, a <USER> element for each valid user consisting of the following attributes:

• name - Username this user must log on with.
• password - Password this user must log on with roles
• Comma-delimited list of the role names associated with this user.

To set up the tomcat-users.xml file:

1. Open the file <Tomcat_Home>\conf\tomcat-users.xml in a text editor such as Notepad or Wordpad.

2. Add a line with the XML <USER> tag entry for each individual user, with the according name, password and roles. The file should then look something like this (default users included):

   <tomcat-users>
           <user name="admin" password="admin" roles="admin,manager" />  
           <user name="tomcat" password="tomcat" roles="tomcat" />
           <user name="role1"  password="tomcat" roles="role1"  />
           <user name="both"   password="tomcat" roles="tomcat,role1" />
           <user name="Tom"   password="Cityapp" roles="City" />
           <user name="Peter"   password="Stateapp" roles="State" />
           <user name="Michael"   password="AllAccess" roles="City,State" />
           </tomcat-users>

   WARNING: User names and roles are case sensitive and must be unique. Do not use commas, tabs or any other characters in the following comma-separated list: < >, #, |, &, ?, ( ), { }

3. Save and close the file
4. Restart the Apache Tomcat service for the edits to take effect. For Tomcat documentation on storing the user and role information in a database accessed via JDBC or in a directory server accessed via LDAP see http://tomcat.apache.org/tomcat-5.5-doc/realm-howto.html

Weblogic

Before you begin configuring role security for Weblogic Application Server, it is recommended that you read the 'Manage users and groups' discussion at http://edocs.bea.com/wls/docs92/ConsoleHelp/taskhelp/security/ManageUsersAndGroups.html and 'Use roles and policies to secure resources' at http://edocs.bea.com/wls/docs92/ConsoleHelp/taskhelp/security/AddUsersToRoles.html.

1. Launch and login to the WebLogic Server Administration Console at http://<SERVERNAME>:7001/console.
2. In the left pane select Security Realms.
3. On the Summary of Security Realms page select the name of the realm (for example, myrealm).
4. On the Settings for Realm Name page select Users and Groups > Users. Click New.
5. On the Create New User page enter a username, password and optionally a description (e.g. the user's full name).
6. WARNING: User names are case sensitive and must be unique. Do not use commas, tabs or any other characters in the following comma-separated list: < >, #, |, &, ?, ( ), { } The minimum password length for a user defined in the WebLogic Authentication provider is 8 characters. Do not use the username/password combination weblogic/weblogic in production.
7. In the Provider drop-down list, select which Authentication provider's database should store information for the new user.
8. Re-enter the password for the user in the Confirm Password field.
9. Click OK to save your changes. The user name appears in the User table.

For more efficient management, BEA recommends adding users to groups:

To create groups:

1. In the left pane select Security Realms.
2. On the Summary of Security Realms page select the name of the realm (for example, myrealm).
3. On the Settings for Realm Name page select Users and Groups > Groups.
4. In the Groups table click New.
5. In the Name field of the Create New Group page, enter the name of the group. Groups names are case sensitive and must be unique. BEA recommends using initial capitalization and plural names for groups, for example, Administrators. Do not use commas, tabs or any other charaters in the following comma-separated list: < >, #, |, &, ?, ( ), { }
6. Optionally, in the Description field, enter a short description of the group (for example, Product Managers for Code Examples).
7. In the Provider drop-down list, select which Authentication provider's database should store information for the new group.
8. Click OK to save your changes and to display the group name in the Group table. After you create a group, you can add users or make the group a member of another group. You can nest groups by adding a group to one or more parent groups.

To add users to groups

1. In the left pane select Security Realms.
2. On the Summary of Security Realms page select the name of the realm (for example, myrealm).
3. On the Settings for Realm Name page select Users and Groups > Users.
4. In the Users table select the user you want to add to a group.
5. On the Settings for User Name page select Groups.
6. Select a group or groups from the Available list box.
7. To add a user to a group, click the right arrow to move the selection to the Chosen list box. Click Save.

To add users to roles

1. In the left pane of the Administration Console, select Security Realms.
2. On the Summary of Security Realms page, select the name of the realm that contains the role definition (for example, myrealm).
3. On the Settings page, select the Roles and Policies tab. Then select the Roles subtab.
4. Access the role's Edit Role page. In the Roles table, in the Name column, expand the Global Roles node.
5. In the Name column, expand the Roles node.
6. In the role's Role Conditions column, click the View Role Conditions link.
7. If the Role Conditions column is empty, select the radio button next the to the role's Name column. Then click the Edit Role button.
8. On the role's Edit Role page, create a role condition that adds a user to the role.
9. In the Role Conditions section, click Add Conditions.
10. On the Choose a Predicate page, in the Predicate List, select User, Group, or Role.

    BEA recommends that you use the Group condition whenever possible. This condition grants the security role to all members of the specified group (that is, multiple users). For a description of all conditions in the Predicate List, see Security Role Conditions at http://edocs.bea.com/wls/docs92/secwlres/policy_statement.

11. Click Next. Enter a user or group name in the argument field, and click Add.
12. Click Finish. On the role's Edit Role page, click Save.

Websphere

Configuring security roles for applications takes place during application install.

1. Log in to the WebSphere console
2. Click Application > Install New Application.
3. While using the Install New Application Wizard, you'll be prompted to map security roles to users. Go to "Security role to user and group selections" under Application > Install New Application.
4. To configure security roles to user mappings of deployed applications, after deployment in Additional Properties, click Map Security roles to users to change user and group mappings to a role.
5. Click Applications > application_name > Map RunAs roles to users in the Additional Properties section.

For more details please see the IBM WebSphere User Guide at http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1//index.jsp?topic=/com.ibm.websphere.exp.doc/info/exp/ae/usec_tselugrad.html

Sun Java System Application Server

Deploy the Web application:

1. Place the .war file in the directory <DRIVE>:\Sun\AppServer\domains\domain1\autodeploy\
2. Go to Control Panel > Administrative Tools > Services. Find the SunJavaSystemAppServer9PE service in the list and restart it.

The .war file will explode and create a web application with the name of the .war file. For example, after deploying the "parcels.war" file, you will see a web application listed as "parcels" in the Sun Java console.

To set up roles in Sun Java Application Server, perform the following steps:

1. Start the Sun Java System Admin Console by starting a web browser and browsing to http://localhost:4848/asadmin. If you changed the default Admin port during installation, enter the correct port number in place of 4848.
2. Log in to the Admin Console with the user name and password entered during installation.
3. In the menu tree on the left click on "Configuration" to expand the node.
4. Click on the node "Security".
5. On the left inside "Security" expand the node "Realms".
6. Click on the realm "file".
7. Choose "Class name for the realm..." and type the name of the role you set for your web application, for example Parcels.
8. Click the Manage Users button on the page on the right.
9. Click New to add one or more users.
10. Enter a User ID and Password, and type the Role name(s) you set for your web application in the Group field. Click OK to add this user to the list of users in the realm.
11. If the role names used in the application are the same as the group names defined on the Application Server, you can enable a default principal-to-role mapping on the Application Server using the Admin Console. From the Admin Console, select Configuration, then Security, then towards the bottom of the page check the enable box beside Default Principal to Role Mapping. Click Save.
12. Click Logout when you have completed this task.

JBoss

To deploy the Web application:

1. Place the .war file in the directory <JBoss_home>\server\default\deploy\
2. Go to <JBOSS>\bin\ and find the run.bat file. Shutdown JBoss by closing the console window if it's still open, then execute the run.bat file to restart JBoss

To configure security roles:

see http://www.juniper.net/techpubs/software/management/sdx/sdx50x/sw-sdx-sw-basics/html/web-app-installing5.html

Go to <JBOSS>/server/default/conf/ and open the file users.properties with Notepad. If it does not exist, create it and save it as "users.properties" (quotes included ensure that it does not append the .txt extension).

To provide access to the web application with the set role "Parcels"to the user "City" with password "government" follow these steps:

1. Add a line with the name and password of the user in the form user=<PASSWORD>, for example:

   City=government 
           Anonymous=password

2. Save and close the file
3. Go to <JBOSS>/server/default/conf/ and open the file roles.properties with Notepad. If it does not exist, create it and save it as "roles.properties" (quotes included ensure that it does not append the .txt extension).

4. Add a line with the name of the user and the role associated with it in the form user=<ROLE>. You can associate multiple roles to the same user, for example:

   City=Parcels 
     Anonymous=Other, Sample

5. Save and close the file
6. Go to <JBOSS>\bin\ and find the run.bat file. Shut down JBoss by closing the console window if it's still open, then execute the run.bat file to restart JBoss.

Oracle Application Server

To configure roles:

1. Login to the Oracle Enterprise Manager at http://localhost:8888/em
2. Go to the Administration tab
3. Click on the Go to Task for Security Provider under the Task Name 'Security'
4. Click on Instance Level Security
5. Choose the Realm tab
6. Click Create to create a new Realm
7. Provide a Name, Administrator Username and password, confirm the password and assign an Administrator Role. Click OK.
8. In the results table, find the Realm Name you want to edit and click on the number displayed in the Roles field to add one or more roles
9. Click Create to create a role.
10. Provide a Name and choose another available role if it should inherit settings. Click OK.
11. Click on the link for Instance Level Security at the top
12. In the results table, find the Realm Name you want to edit and click on the number displayed in the Users field to add one or more users.
13. Click Create to add more users.
14. Provide a Name and Password and confirm the password.
15. Choose an available role to assign it. Click OK.

Once roles have been configured, deploy your Web application:

1. Place the /war file in the directory <DRIVE><OAS_HOME>\j2ee\home\applications
2. Log in to the Oracle Enterprise Manager at http://localhost:8888/em
3. Go to the applications tab and Click Deploy
4. Choose "Archive is already present..." and type the location and name of the .war file, for example <OAS_HOME>\j2ee\home\applications\parcels.war
5. Verify "Automatically create a new deployment plan" is selected
6. Click Next to get to Step 2 of 3
7. Type the name of the application, for example Parcels
8. Verify the Context Root field has the correct name
9. Click Next to get to Step 3 of 3
10. On the Step 3 of 3 page of the "Deploy: Deployment Settings" page, click on the pencil symbol under the Go To Task column for Map Security Roles
11. Click on the pencil symbol in the Map Role field
12. Type the name of the user or group you want to add and click Add. You may repeat this steps for all users and groups you want to add.
13. Click Continue
14. Click OK to close the Map Security Roles window
15. Click Deploy
16. Logout of the Enterprise Manager
17. Restart OAS for the changes to take effect.