Creating an ArcGIS Server Java custom security store

ArcGIS Server at 9.3 introduces Role Based Access Control (RBAC) to secure capabilities published by the GIS Server. ArcGIS Server comes with a default embedded database system to maintain all user and role information. ArcGIS Server for Java provides the ability to customize the security system to manage user and roles that exist in other Relational Databases or Directory Services (LDAP or Active Directory) as well as an API to extend the security system. Extending the system through the Principle Store API allows you to build a custom Java class which reads and writes security parameters to and from a custom data store. In this example we will create a Java class which reads and writes users and roles to and from an XML file, from which your ArcGIS security mechanism will consume the user and role information. There are four steps involved in this process which we will step you through.

1. Create a custom security store class which implements SecurityStore. The SecurityStore interface is located in the com.esri.adf.security.store package inside the arcgis_securityapi.jar file. It includes methods to work with users and roles in your custom RBAC as well as the ability to test your connection to the data store. We will use the Eclipse developer environment to stub out our class with the appropriate methods. From within Eclipse, create a package called demo.
   
   
   

   Inside the demo package, create a class called FileStore which inherits the interface com.esri.adf.security.store.SecurityStore. Be sure the 'Inherited abstract methods' box is checked.
   
   
   

   This will stub out the appropriate methods for our new class of which we can implement to support our custom security store. Let's discuss some of the methods that we implemented in the full source included in the Code Gallery.

   init(): The init method initializes the SecurityStore implementation. This is where we work with the file store by first checking to see if the file exists, creating it if it does not, and then getting any users and roles which already exist.

   addUser(), deleteUser(), modifyUser(), getUser(), getAllUsers(): These methods take in an ArcGISSecurityUser class parameter and allows us to manipulate these users within the security store.

   addRole() addUsersToRoll(), deleteRole(), deleteAllRolesForUsers(), deleteAllUsersForRolls(), deleteRolesFromUser(), deleteUsersFromRole(), modifyRole(), getRole(), getAllRolls(), getRolesForUser(), getUsersForRole(): These methods allow us to manipulate the roles, and users assigned to specific roles, within our security store.

   validateUser(): Here we can check the users credentials from the security store. The method returns a Boolean value of true when the user credentials match the information in the security store.

   We also created two helper methods:

   createFileStore(): This method gets called in the init method if the file store does not exist. It will then create the initial file store as an xml file and create the required elements.

   updateFileStore(): This methods gets called from within our add/delete user/role methods we inherited and allows us to write a document memory object back to our file store.

   Please implement the full source code from the FileStore.java class provided in the ArcGIS code gallery.

2. Create a custom security.xml file to configure the custom SecurityStore implementation we created in step 1. This file is located in the ‘%ARCGISHOME%\java\manager\service\lib’ folder and by default contains the information for the internal data store.

   To use our custom implementation, we need to replace the required connection parameter and add a user defined parameter <FS_FilePath> which points to the file based XML file we are using to store our data store:

   <entry key="UserStore">demo.FileStore</entry>		 
   <entry key="FS_FilePath">filestore.xml</entry>
   

   We have included a simplified security.xml file in the ArcGIS code gallery which assumes security has not already been configured and enabled on your GIS server.

3. Create a jar file with our custom SecurityStore implementation and hot deploy it to the ‘%ARCGISHOME%\java\manager\config\security\lib’ directory. This is easy to do from within Eclipse. (Alternatively you can create a jar from the command line with the Java jar tool.) Return back to our class in Eclipse, right click on the class file, and select 'Export' from the menu:
   
   
   

   Select Java->Jar file from the Export wizard:
   
   
   

   Ensure that only the classes you want to export are selected, in this example the demo.FileStore class:
   
   
   

   Select an appropriate export destination and click Finish to accept the remaining defaults and generate a jar file for deployment. Copy the resulting jar file containing the custom SecurityStore implementation to the ‘%ARCGISHOME%\java\manager\config\security\lib’ directory.

4. Once our custom SecurityStore implementation jar file is in place and our security.xml file is properly configured, we are ready to begin using our custom security implementation. To reload the security configuration used in our custom SecurityStore implementation, restart the ArcGIS Server Manager Service.

Now let’s test our custom security configuration through Manager. ArcGIS Server 9.3 includes a new ‘Security’ menu where we can configure and setup our custom Principle Store to manage users and roles. The ‘Roles link, under the ‘Security’ menu, lists all the Web GIS Roles currently configured on the system. To add a new role, click the ‘Add Role’ button, fill in the ‘Rolename’, and optionally a ‘Description’ for the new role:

Now that we have a role defined, let’s add a new user by clicking the ‘Users’ link under the ‘Security’ menu. To add a new Web GIS User, click the ‘Add User’ button and fill in the required fields and add the newly created ‘Editor’ role defined in the previous step.

Now let’s take a look at the XML data store that our custom Security Store uses to maintain users and roles to confirm that our custom implementation is working as expected. Navigate your operating systems file browser to the ‘%ARCGISHOME%\java\manager\service\lib’ directory and open the newly created filestore.xml in your favorite text/xml editor. The contents should look similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<FileStore>
     <users>
          <user name="spatial" password="cdb36c370b737074c455bf1ee75a2f56"/>
     </users>
     <roles>
          <role description="Allows write access" name="Editor"/>
     </roles>
     <user_role>
          <spatial>Editor</spatial>
     </user_role>
</FileStore>

This file will now manage your users and roles as you continue to configure them through Manager.

Download

Sample Custom Security Store source code for this article

Resources

Extending the Principal Store API

Security API documentation

Contributed by Dan O'Neill of the ArcGIS Server Java software development team