SecureEndpointImpl.java

The guts of the web service reside in the SecureEndpointImpl.java file. The critical component of this file are the annotation for the security domain: @SecurityDomain("sample-security"). The annotation defines the security domain that we will use for our authentication and authorization and will be defined in configuration files below. The remaining annotations are standard web service annotations.

Now that the simple service is complete, we must create the files required to add XACML authorization support.

META-INF Contents

When creating a XACML protected web service, the deployed jar must contain a META-INF directory populated with a few important files.

jboss-xml

The jboss-xml file defines the security domain we will be using to protect our service. In this instance, we define a jaas domain called: sample-security. It is important to notice this defined domain is used through out the deployment, such as in our @SecurityDomain annotation in our implementation above.

jbossxacml-config.xml

Now on to setting up our XACML policy. JBoss XACML requires a configuration file located within the META-INF directory that indicated where and how your application policies are located. It is important to remember this this file must be named jbossxacml-config.xml, otherwise it will not get found by the system. In our example, we define a single policy, also located in META-INF called xacml-policy.xml. We also use the standard Locators, JBossPolicySetLocator, and JBossPolicyLocator. Given that we only have a policy defined, we could probably get away with a single PolicyLocator, however having the PolicySetLocator does not introduce any issues.

xacml-policy.xml

When creating the actual xacml policy, a few extra resources and actions are required to properly and successfully protect a service.

In the policy below, we create a policy that only allows bob, with a role of role1 to access the echo web service, defined as an action in the policy. While no real policy would ever contain a subject match rule for a specific user, such as bob in our policy, we leave this policy requirement for learning purposes.

It is also important that our policy provide authorization for our web services contextRoot: /sampleDomain, and the endpoint: SecureEndpoint.

We must also provide a write action in our policy. (Debugging Tip:If your policy fails to provide authorization for a case you expected a PERMIT, turn on TRACE level debugging and compare the XACML request attributes with the policy. It is often the case that you are not placing a rule for the resource in the policy.)

sample-users.properties

sample-roles.properties

The sample-roles properties file is also a simple name/value pair.

bob=role1
alice=role2

Test Client

To test our simple service, we will use a simple JUnit test case. In our test case, we have three tests, a test to verify that we do not permit anonymous access to our service, a test to verify a non permitted user does not have access and finally a test for the proper user. When run successfully, all three tests should pass.

Running the Service and the Tests

To execute the service and the tests, download the attached tar file and unzip to your local workspace.

Edit the file build.properties and set the location of your JBoss instance.

Assuming you have ANT 1.7+, and JBoss is currently running, execute the following ant targets:

ant deploy-sample-endpoint

once the deployment has finished, run the tests

ant run-client

The junit target should report that all three tests passed.

Potential Issues

When deploying a service, I have frequently encountered a issue where the tests will fail because the server is reporting a null PolicyRegistration. This appears to be an bug with JBossPDP not being Serializable. When this issue occurs, remove any jars from the deploy directory that contain a XACML authorization module and restart JBoss.