Introducing the OES Maven Plugin
The way I attempted to address this problem was by creating a Maven plugin for OES. The OES Maven Plugin is part of the oes-jboss project. The information in this post is based on version-1.0
The plugin supports three goals (maven speak for operations)
- import - Imports policies from the local file system into OES admin server using policyIX
- export - Exports the policies from OES admin server and into the local file system using policyIX
- generate-default-policy - Reads the files generated by the OES Annotations Processor and converts them into a policyIX policy file in the file system
The configuration for the plugin basically follows the names of the elements in the policyIX config file.
General Settings
- server_host_name - Hostname of the OES Admin Server - defaults to localhost
- server_port - SSL Port for the OES Admin Server - defaults to 7010
- blm_server_port - The BLM API port for the OES Admin Server - defaults to 7011
- print_info - Boolean flag that determs if the information about which objects policyIX is loading should be displayed - defaults to true
- userID - OES Admin user id - defaults to admin
- password - OES Admin password - defaults to password
- policyFile - The location of the policy file that policyIX imports into the OES Admin Server or the localtion of where the generated policy file should be saved - defaults to ${project.build.outputDirectory}/com/oracle/security/entitlements/policy/policy.xml
Settings for the generate-default-policy goal
- policyTemplateFile - the location of the policy template that the plugin should use when generating the default policies - defaults to ${project.build.outputDirectory}/com/oracle/security/entitlements/policy/policy_template.xml
- resources - the location of the resources file generated by the OES annotations - defaults to ${project.build.outputDirectory}/com/oracle/security/entitlements/policy/object
- actions - the location of the actions file generated by the OES annotations - defaults to ${project.build.outputDirectory}/com/oracle/security/entitlements/policy/priv
- attributes - the location of the attributes file generated by the OES annotations -defaults to ${project.build.outputDirectory}/com/oracle/security/entitlements/policy/attr
- overwrite - boolean indicating that the generated policies should be overwritten, even if th policyFile exists - defaults to true
Settings for the import goal
- policy_load_procedure - the load procedure the plug in should use when importing the policies into OES - the default is override. The other valid value is delete_existing
Settings for the export goal
- exportPolicyFile - the location of the file that the OES policies are exported to - defaults to ${project.build.sourceDirectory}/../oes/policy.xml
- clipping_scope - the clipping scope from which the OES policies are exported - defaults to RootOrg!${oes.organization}!${oes.application}
- createTemplateOnExport - boolean indicating that the export task should convert the OES policies into a "template", before saving it to disk - default value is true
- replaceAdminDirInTemplate - boolean indicating that the user and group part of the policies that are defined for the AdminDir should not be templatized - default value is true
Instructions for Installing OES-Maven Plugin
The installation is really in two parts. The first is deploying a special web-application to the OES Admin server. This web-application greatly simplifies the compilation of plugin by materializing the required OES libraries as a moven POM. This is an alternative to the previously suggested ANT based approach or explicitly loading in the OES libraries. Its just too complicated, and when I realized that I needed a slighly different set of libraries to run the policyIX tool, I took the time to build the web app. With the web-app installed, you can easily build the oes-maven plugin.
Building the repository-web-app
- Build the web-app - this is simple, just type mvn install from oes-maven/repository-web-app
- Deploy the web-app to the OES Admin Server - This is assuming that the OES Admin Server is running on WLS, but basically, all you're doing is installing a war. You can log into the WLS admin console at https://
:7010/console with admin/password, and deploy the web-app. - Import the OES policies protecting the web-app - We need to bootstrap the policies for who can access the oes-maven web-application. I included the policyIX policies here.
<?xml version="1.0" encoding="UTF-8"?>
<xb:policy_propagation xmlns:xb="http://policypropagation.ales.com/xmlbean">
<xb:policy_propagation_data_v2>
<xb:scopes>
<xb:application_entry value="RootOrg!defaultOrg!oes-maven" boundSSM="asiadmin">
<xb:admin_roles>
<xb:admin_role_entry value="AppAdmin" isPrimary="true" description="Primary Application Admin Role of current Application">
<xb:admin_role_privileges>
<xb:admin_role_privilege_entry object="action" action="adminmanage"/>
<xb:admin_role_privilege_entry object="authorizationPolicy" action="adminmanage"/>
<xb:admin_role_privilege_entry object="authorizationPolicyReport" action="adminmanage"/>
<xb:admin_role_privilege_entry object="directory" action="adminview"/>
<xb:admin_role_privilege_entry object="extension" action="adminmanage"/>
<xb:admin_role_privilege_entry object="group" action="adminview"/>
<xb:admin_role_privilege_entry object="policyDistribution" action="adminmanage"/>
<xb:admin_role_privilege_entry object="policySimulator" action="adminmanage"/>
<xb:admin_role_privilege_entry object="resource" action="adminmanage"/>
<xb:admin_role_privilege_entry object="role" action="adminmanage"/>
<xb:admin_role_privilege_entry object="rolePolicy" action="adminmanage"/>
<xb:admin_role_privilege_entry object="rolePolicyReport" action="adminmanage"/>
<xb:admin_role_privilege_entry object="user" action="adminview"/>
</xb:admin_role_privileges>
</xb:admin_role_entry>
</xb:admin_roles>
<xb:resources>
<xb:resource_entry value="//resources/url" isVirtualResoureAllowed="true"/>
</xb:resources>
<xb:actions>
<xb:action_entry value="any"/>
</xb:actions>
<xb:policies>
<xb:authorization_policy_entry>
<xb:policy_effect value="grant"/>
<xb:policy_actions>
<xb:policy_action_entry value="any"/>
</xb:policy_actions>
<xb:policy_resources>
<xb:policy_resource_entry value="//resources/url"/>
</xb:policy_resources>
<xb:policy_subjects>
<xb:policy_group_entry name="allusers" directory="AdminDir" scope="RootOrg"/>
</xb:policy_subjects>
</xb:authorization_policy_entry>
</xb:policies>
</xb:application_entry>
</xb:scopes>
<xb:security_configuration_data>
<xb:scms>
<xb:scm_entry name="adminconfig">
<xb:ssms>
<xb:ssm_entry name="asiadmin"/>
<xb:ssm_entry name="jboss"/>
<xb:ssm_entry name="oes10gR3cp4wlsssm"/>
</xb:ssms>
</xb:scm_entry>
</xb:scms>
</xb:security_configuration_data>
</xb:policy_propagation_data_v2>
</xb:policy_propagation>- Distribute The Policies - Log into the OES Entitlements Administration Server, and deploy the policies.
- Add an entry for the OES Admin Server in your Maven's settings.xml - Since the application is protected, you'll need to have the OES admin user's credentials. In Maven, this is configured in your settings.xml
<servers>
<server>
<id>oes-admin</id>
<username>admin</username>
<password>password</password>
</server>
</servers>
The id oes-admin is just a reference used by the oes-maven-plugin POM. - Import the OES policies protecting the web-app - We need to bootstrap the policies for who can access the oes-maven web-application. I included the policyIX policies here.
Build the Plugin
From the oes-maven-plugin directory type
mvn install -Does-admin-url=http://servername:7000/oes-maven
If this works, you'll see a bunch of files downloaded to your local repository, and the oes-maven-plugin will be built successfully! For those of you who are really hard-code, you can actually access the oes-maven web-app over the SSL port by passing -Does-admin-url=https://servername:7010/oes-maven. If order to get the SSL handshake to work, you just need to import the OES Admin Server's CA into the trusted keystore of the JDK (think of this as extra credit)
Using the OES Maven Plugin - an example
I've created a 1.0.1 version of the oes-spring application that demonstrates the OES maven plugin. All of the magic is inside of the oes_spring_aop_test/pom.xml. First let's run through an example of the "lifecycle", and then we can dig into the details of the POM.
- Developer Builds Simple Spring+OES Application - In this first step of the lifecycle, the developer is just building the objects. They add the annotations as a way to help surface the security meta-data - mainly the resources, actions, and attributes that will be available for policy authoring. As the developer compiles the application, the OES annotations are evaluated, and the OES maven plugin generates the sample policy file based on the template. You can see this by running
mvn -Does.server.host=<hostname of admin server> compile
The result of this is the creation of the actions, attributes, and resources files. Notice that with the sample that there were some compiler warnings generated. This is to be expected. Basically, not every Java type can be mapped to a dynamic attribute type inside of the OES console. This is fine, but you can only access these attributes via OES Attribute Retriever or Eval Function, not through the policy. In the case that you're not passing the object and its a type that is not supported in OES, then the compilation fails. - Developer tests application - So now the developer wants to start doing some unit testing. At this point, the OES maven plugin will generate the policyIX import file and import it into the OES admin server. The file is stored as a resource in the classes directory, and as such is expected to be a simple temporary set of policies. You can see the policies deployed to OES by running
mvn -Does.server.host=<hostname of admin server> test
The unit test that I have in the sample uses a dummy implemenation of the ISecurityContext, but its possible that if there was a local SM, then the policies would be available. NOTE: For the policies to take affect they need to be distributed from the OES Admin Server. The current version of the OES Maven Task does not deploy the policies - Security Administrator changes OES policies - The administrator can now log into the OES Admin console. You can see the resources, the actions, and the attributes that are available for policy authoring.
The security administrator now can go in and change the policies. Since all of the resourecs, actions, and attributes have been created for them, this greatly simplifies the task. At some point, they are happy with the policies, and the policies are exported back to the project.
mvn -Does.server.host=<hostname of admin server> oes:export
By default, this generates a policyIX export and adds it to ${project.build.sourceDirectory}/../oes/policy.xml. This is inside of the source of the project. The expectation is that this export file would be added to source control. One interesting this that the export goal does is to change the file back into a template. This is done so that when the import goal is run, the values of a different environment can be used. - Policy and Application is deployed to a different environment - Once the policy hasa been exported from OES and is now part of the project, the application and policies can be moved to a different environment - say integration testing or pre-production. The POM checks to see if the OES file exists in main/oes/policy.xml, and if it does, then it uses that file (as opposed to the generated one) to be imported. You can see this by running
mvn -Does.server.host=<hostname of admin server> install
You'll notice that the policies that get added back to OES reflect the changes made after running oes:export - not the default policies.
Understanding a some of the oes_spring_aop POM
The project depends on a few properties
<properties>
<oes.ssm>jboss</oes.ssm>
<oes.application>jboss</oes.application>
<oes.organization>MyOrg</oes.organization>
<oes.directory>jboss_dir</oes.directory>
<oes.server.host>oel55-64.localdomain</oes.server.host>
</properties>
The first four are used for the variable substuitution inside of the policies. The properties that I ship with the project are based on the OES JBOSS SPRING application. The values for these properties should match the values used in the config tool used to create the SM. I used the built in filtering capabilities of Maven to do the variable substitution of these properties into the template.
The last property is a convenient way to specify the hostname of the admin server. Notice that in the example above, I used -Does.server.host to specify the servername. You can override any of these properties with command line arguments or as part of Maven profiles.
Summary
The way that I have the goals of the plugin tied to the phases of the Maven lifecycle is definately a matter of debate. I made a deliberate decision not to tie export to an explicit phase, but if I had to pick one...maybe deploy. My thinking is that before the application is put some place else, it makes sense to get a copy of the policies. Ultimately, I don't think there is a total one size fits all lifecycle, but I think that this OES Maven plugin, and the example project provide a very solid foundation. There are definately more goals that could be added - maybe the ability to automatically create and enroll an SM from the config tool. I'm eager to hear your feedback on the life cycle that I put forth, and what variations you've seen or think the maven plugins should support.
Posts
