- Added XACML Request template file (request.xacml.json.ftl) to

cdanger · cdanger · commit 9ed4a936a3fd · 2018-05-01T20:25:02.000+02:00
assembled package (tar.gz)
- CombinedXacmlAclAuthorizer class:
  - better javadoc
  - better logging
  - XACML Request template loaded from file location (instead of string
in Java property)
diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@ To enable the authorizer on Kafka, set the server's property:
 
 To enable XACML evaluation, set the extra following authorizer properties:
 * **`org.ow2.authzforce.kafka.pep.xacml.pdp.url`**: XACML PDP resource's URL, as defined by [REST Profile of XACML 3.0](http://docs.oasis-open.org/xacml/xacml-rest/v1.0/xacml-rest-v1.0.html), §2.2.2, e.g. `https://serverhostname/services/pdp` for a [AuthzForce RESTful PDP](https://github.com/authzforce/restful-pdp) instance, or `https://serverhostname/authzforce-ce/domains/XXX/pdp` for a domain `XXX` on a [AuthzForce Server](https://github.com/authzforce/server) instance.
-* **`org.ow2.authzforce.kafka.pep.xacml.req.tmpl`:** [Freemarker](https://freemarker.apache.org/) template of XACML Request formatted according to [JSON Profile of XACML 3.0](http://docs.oasis-open.org/xacml/xacml-json-http/v1.0/xacml-json-http-v1.0.html), in which you can use [Freemarker expressions](https://freemarker.apache.org/docs/dgui_template_exp.html), enclosed between `${` and `}`, and have access to the following [top-level variables](https://freemarker.apache.org/docs/dgui_template_exp.html#dgui_template_exp_var_toplevel) from Kafka's authorization context:
+* **`org.ow2.authzforce.kafka.pep.xacml.req.tmpl.location`:** location of a file that contains a [Freemarker](https://freemarker.apache.org/) template of XACML Request formatted according to [JSON Profile of XACML 3.0](http://docs.oasis-open.org/xacml/xacml-json-http/v1.0/xacml-json-http-v1.0.html), in which you can use [Freemarker expressions](https://freemarker.apache.org/docs/dgui_template_exp.html), enclosed between `${` and `}`, and have access to the following [top-level variables](https://freemarker.apache.org/docs/dgui_template_exp.html#dgui_template_exp_var_toplevel) from Kafka's authorization context:
 
 | Variable name | Variable type | Description |
 | --- | --- | --- |
@@ -37,15 +37,7 @@ To enable XACML evaluation, set the extra following authorizer properties:
 |`resourceType`|[org.apache.kafka.common.resource.ResourceType](https://kafka.apache.org/11/javadoc/org/apache/kafka/common/resource/ResourceType.html)|resource type|
 |`resourceName`|`String`|resource name|
 
-For example:
- 
-```json
-org.ow2.authzforce.kafka.pep.xacml.req.tmpl={"Request"\:{"Category"\:[{"CategoryId"\:"urn\:oasis\:names\:tc\:xacml\:1.0\:subject-category\:access-subject","Attribute"\:[{"AttributeId"\:"urn\:oasis\:names\:tc\:xacml\:1.0\:subject\:subject-id","DataType"\:"http\://www.w3.org/2001/XMLSchema#string","Value"\:"${principal.name}"},{"AttributeId"\:"urn\:oasis\:names\:tc\:xacml\:1.0\:subject\:authn-locality\:dns-name","DataType"\:"urn\:oasis\:names\:tc\:xacml\:2.0\:data-type\:dnsName","Value"\:"${clientHost.hostName}"},{"AttributeId"\:"urn\:oasis\:names\:tc\:xacml\:3.0\:subject\:authn-locality\:ip-address","DataType"\:"urn\:oasis\:names\:tc\:xacml\:2.0\:data-type\:ipAddress","Value"\:"${clientHost.hostAddress}"}]},{"CategoryId"\:"urn\:oasis\:names\:tc\:xacml\:3.0\:attribute-category\:action","Attribute"\:[{"AttributeId"\:"urn\:oasis\:names\:tc\:xacml\:1.0\:action\:action-id","DataType"\:"http\://www.w3.org/2001/XMLSchema#string","Value"\:"${operation}",}]},{"CategoryId"\:"urn\:oasis\:names\:tc\:xacml\:3.0\:attribute-category\:resource","Attribute"\:[{"AttributeId"\:"urn\:thalesgroup\:xacml\:resource\:resource-type","DataType"\:"http\://www.w3.org/2001/XMLSchema#string","Value"\:"${resourceType}"},{"AttributeId"\:"urn\:oasis\:names\:tc\:xacml\:1.0\:resource\:resource-id","DataType"\:"http\://www.w3.org/2001/XMLSchema#string","Value"\:"${resourceName}"}]},{"CategoryId"\:"urn\:oasis\:names\:tc\:xacml\:3.0\:attribute-category\:environment","Attribute"\:[{"AttributeId"\:"urn\:thalesgroup\:xacml\:environment\:deployment-environment","DataType"\:"http\://www.w3.org/2001/XMLSchema#string","Value"\:"DEV"}]}]}}
-```
-
-This example is derived from the [template in the source](src/test/resources/request.xacml.json.ftl), i.e. adapted for the Java Properties format, and should be applicable to most cases.
-
-As shown in this example, the property value must be formatted according to [Java Properties API](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Properties.html). In particular, you must **either compact your JSON template on one line; or on multiple lines but only if you terminate each line with a backslash as mentioned on [Java Properties#load(Reader) API](https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html#load-java.io.Reader-). You must also escape all ':' with backslash**, because ':' is a special character (like '=') in Java properties file format. 
+For an example of XACML Request template, see the file `request.xacml.json.ftl` in the [source](src/test/resources/request.xacml.json.ftl) or in the same folder as this README if part of a release package (tar.gz). This example should be sufficient for most cases.
 
 ## Starting Kafka
 Make sure Zookeeper is started first:
diff --git a/assembly.xml b/assembly.xml
@@ -10,7 +10,7 @@
 		<dependencySet>
 			<useProjectArtifact>true</useProjectArtifact>
 			<excludes>
-			<!-- Already provided with Kafka -->
+				<!-- Already provided with Kafka -->
 				<exclude>org.slf4j:slf4j-api</exclude>
 			</excludes>
 			<outputDirectory>lib</outputDirectory>
@@ -26,12 +26,12 @@
 				<include>NOTICE*</include>
 			</includes>
 		</fileSet>
-		<!-- <fileSet> -->
-		<!-- <directory>etc</directory> -->
-		<!-- <outputDirectory></outputDirectory> -->
-		<!-- <includes> -->
-		<!-- <include>startup.*</include> -->
-		<!-- </includes> -->
-		<!-- </fileSet> -->
+		<fileSet>
+			<directory>${project.basedir}/src/test/resources</directory>
+			<outputDirectory>/</outputDirectory>
+			<includes>
+				<include>request.xacml.json.ftl</include>
+			</includes>
+		</fileSet>
 	</fileSets>
 </assembly>
diff --git a/pom.xml b/pom.xml
@@ -9,7 +9,7 @@
 		<version>7.2.0</version>
 	</parent>
 	<artifactId>authzforce-ce-kafka-extensions</artifactId>
-	<version>0.1.0-SNAPSHOT</version>
+	<version>0.2.0</version>
 	<name>AuthzForce CE - Extensions for Apache Kafka</name>
 	<repositories>
 		<repository>
@@ -205,4 +205,4 @@
 		</plugins>
 	</build>
 	<description>Includes Authorizer (KIP-11) implementation supporting both Kafka ACL and XACML policy evaluation for Attribute-Based Access Control</description>
-</project>
+</project>
diff --git a/src/main/java/org/ow2/authzforce/kafka/pep/CombinedXacmlAclAuthorizer.java b/src/main/java/org/ow2/authzforce/kafka/pep/CombinedXacmlAclAuthorizer.java
@@ -17,13 +17,15 @@
  */
 package org.ow2.authzforce.kafka.pep;
 
+import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.StringReader;
 import java.io.StringWriter;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.Collections;
 import java.util.Map;
-
-import javax.ws.rs.core.MediaType;
+import java.util.stream.Collectors;
 
 import org.apache.cxf.ext.logging.LoggingFeature;
 import org.apache.cxf.feature.Feature;
@@ -34,6 +36,7 @@
 import org.ow2.authzforce.xacml.json.model.Xacml3JsonUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.springframework.util.ResourceUtils;
 
 import com.google.common.collect.ImmutableMap;
 
@@ -42,23 +45,46 @@
 import freemarker.template.Template;
 import freemarker.template.TemplateExceptionHandler;
 import kafka.network.RequestChannel.Session;
+import kafka.security.auth.Authorizer;
 import kafka.security.auth.Operation;
 import kafka.security.auth.Resource;
 import kafka.security.auth.SimpleAclAuthorizer;
 
+/**
+ * Combined ACL and XACML-based {@link Authorizer} for Apache Kafka. Gets authorization decisions from a XACML PDP's REST API - as defined by OASIS standard 'REST Profile of XACML 3.0' - iff Kafka ACL
+ * (evaluated by {@link SimpleAclAuthorizer}) returns Deny. To enable XACML authorization, you need to set two extra configuration properties:
+ * <ul>
+ * <li>{@value #XACML_PDP_URL_CFG_PROPERTY_NAME}: XACML PDP resource's URL, as defined by <a href="http://docs.oasis-open.org/xacml/xacml-rest/v1.0/xacml-rest-v1.0.html">REST Profile of XACML 3.0</a>,
+ * §2.2.2, e.g. {@code https://serverhostname/services/pdp}</li>
+ * <li>{@value #XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME}: location of a file that contains a <a href="https://freemarker.apache.org/">Freemarker</a> template of XACML Request formatted
+ * according to <a href="http://docs.oasis-open.org/xacml/xacml-json-http/v1.0/xacml-json-http-v1.0.html">JSON Profile of XACML 3.0</a>, in which you can use
+ * <a href="https://freemarker.apache.org/docs/dgui_template_exp.html">Freemarker expressions</a>, enclosed between <code>${</code> and <code>}</code>, and have access to the following
+ * <a href="https://freemarker.apache.org/docs/dgui_template_exp.html#dgui_template_exp_var_toplevel">top-level variables</a> from Kafka's authorization context:
+ * <ul>
+ * <li><code>clientHost</code> ({@link java.net.InetAddress}): client/user host name or IP address</li>
+ * <li><code>principal</code> ({@link org.apache.kafka.common.security.auth.KafkaPrincipal}): user principal</li>
+ * <li><code>operation</code> ({@link org.apache.kafka.common.acl.AclOperation}): operation</li>
+ * <li><code>resourceType</code> ({@link org.apache.kafka.common.resource.ResourceType}): resource type</li>
+ * <li><code>resourceName</code> ({@link String}): resource name</li>
+ * </ul>
+ * </li>
+ * </ul>
+ */
 public class CombinedXacmlAclAuthorizer extends SimpleAclAuthorizer
 {
 	private static final Logger LOGGER = LoggerFactory.getLogger(CombinedXacmlAclAuthorizer.class);
 
+	private static final String XACML_JSON_MEDIA_TYPE = "application/xacml+json";
+
 	/**
 	 * Name of Kafka configuration property specifying the RESTful XACML PDP resource's URL (e.g. https://services.example.com/pdp), as defined by REST Profile of XACML, §2.2.2
 	 */
-	public static final String XACML_PDP_URL = "org.ow2.authzforce.kafka.pep.xacml.pdp.url";
+	public static final String XACML_PDP_URL_CFG_PROPERTY_NAME = "org.ow2.authzforce.kafka.pep.xacml.pdp.url";
 
 	/**
-	 * Name of Kafka configuration property specifying the XACML Request template
+	 * Name of Kafka configuration property specifying the location to XACML Request template file. The location must be a URL resolvable by {@link ResourceUtils}.
 	 */
-	public static final String XACML_REQUEST_TEMPLATE_CFG_PROPERTY_NAME = "org.ow2.authzforce.kafka.pep.xacml.req.tmpl";
+	public static final String XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME = "org.ow2.authzforce.kafka.pep.xacml.req.tmpl.location";
 
 	private static final int MAX_JSON_STRING_LENGTH = 1000;
 
@@ -80,39 +106,62 @@ public void configure(Map<String, ?> authorizerProperties)
 		{
 			super.configure(authorizerProperties);
 
-			final Object xacmlPdpUrlObj = authorizerProperties.get(XACML_PDP_URL);
+			final Object xacmlPdpUrlObj = authorizerProperties.get(XACML_PDP_URL_CFG_PROPERTY_NAME);
 			if (xacmlPdpUrlObj == null)
 			{
-				LOGGER.info("Configuration property '{}' undefined -> XACML evaluation disabled, KAFKA ACL enabled only.", XACML_PDP_URL);
+				LOGGER.info("Configuration property '{}' undefined -> XACML evaluation disabled, KAFKA ACL enabled only.", XACML_PDP_URL_CFG_PROPERTY_NAME);
 				return;
 			}
 
 			if (!(xacmlPdpUrlObj instanceof String))
 			{
-				throw new IllegalArgumentException(this + ": authorizer configuration property '" + XACML_PDP_URL + "' is not a String");
+				throw new IllegalArgumentException(this + ": authorizer configuration property '" + XACML_PDP_URL_CFG_PROPERTY_NAME + "' is not a String");
 			}
 
 			final String xacmlPdpUrlStr = (String) xacmlPdpUrlObj;
-			LOGGER.debug("XACML PDP URL set from authorizer configuration property '{}': {}", XACML_PDP_URL, xacmlPdpUrlStr);
+			LOGGER.debug("XACML PDP URL set from authorizer configuration property '{}': {}", XACML_PDP_URL_CFG_PROPERTY_NAME, xacmlPdpUrlStr);
 
 			pdpClient = WebClient
 			        .create(xacmlPdpUrlStr, Collections.singletonList(new JsonRiJaxrsProvider(/* extra parameters */)),
 			                LOGGER.isDebugEnabled() ? Collections.singletonList(new LoggingFeature()) : Collections.<Feature>emptyList(), null /* clientConfClasspathLocation */)
-			        .type(MediaType.APPLICATION_JSON_TYPE).accept(MediaType.APPLICATION_JSON_TYPE);
+			        .type(XACML_JSON_MEDIA_TYPE).accept(XACML_JSON_MEDIA_TYPE);
 
-			final Object xacmlReqTmplObj = authorizerProperties.get(XACML_REQUEST_TEMPLATE_CFG_PROPERTY_NAME);
+			final Object xacmlReqTmplObj = authorizerProperties.get(XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME);
 			if (!(xacmlReqTmplObj instanceof String))
 			{
-				throw new IllegalArgumentException(this + ": authorizer configuration property '" + XACML_REQUEST_TEMPLATE_CFG_PROPERTY_NAME + "' is missing or not a String");
+				throw new IllegalArgumentException(this + ": authorizer configuration property '" + XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME + "' is missing or not a String");
 			}
 
-			final String xacmlReqTmplStr = (String) xacmlReqTmplObj;
-			LOGGER.debug("Loading XACML Request template from authorizer configuration property '{}': {}", XACML_REQUEST_TEMPLATE_CFG_PROPERTY_NAME, xacmlReqTmplStr);
+			final String xacmlReqTmplFileLocation = (String) xacmlReqTmplObj;
+			LOGGER.debug("Loading XACML Request template from authorizer configuration property '{}': {}", XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME, xacmlReqTmplFileLocation);
+
+			final Path xacmlReqTmplFile;
+			try
+			{
+				xacmlReqTmplFile = ResourceUtils.getFile(xacmlReqTmplFileLocation).toPath();
+			}
+			catch (final FileNotFoundException e)
+			{
+				throw new IllegalArgumentException(
+				        "XACML JSON Request template file not found at location ('" + XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME + "'=) '" + xacmlReqTmplFileLocation + "'", e);
+			}
+
+			final String xacmlReqTmplStr;
+			try
+			{
+				xacmlReqTmplStr = Files.lines(xacmlReqTmplFile).collect(Collectors.joining());
+			}
+			catch (final IOException e)
+			{
+				throw new RuntimeException(
+				        "Error opening XACML JSON Request template file at location ('" + XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME + "'=) '" + xacmlReqTmplFileLocation + "'", e);
+			}
 
 			final JSONObject jsonRequest = new LimitsCheckingJSONObject(new StringReader(xacmlReqTmplStr), MAX_JSON_STRING_LENGTH, MAX_JSON_CHILDREN_COUNT, MAX_JSON_DEPTH);
 			if (!jsonRequest.has("Request"))
 			{
-				throw new IllegalArgumentException("Invalid XACML JSON Request file specified by '" + XACML_REQUEST_TEMPLATE_CFG_PROPERTY_NAME + "'. Root key is not 'Request' as expected.");
+				throw new IllegalArgumentException("Invalid XACML JSON Request template file at location ('" + XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME + "'=) '" + xacmlReqTmplFile
+				        + "': root key is not 'Request' as expected.");
 			}
 
 			Xacml3JsonUtils.REQUEST_SCHEMA.validate(jsonRequest);
@@ -162,17 +211,16 @@ public boolean authorize(Session session, Operation operation, Resource resource
 		final boolean simpleAclAuthorized = super.authorize(session, operation, resource);
 
 		/*
-		 * TODO: define combining algorithm for combining simple ACLs with XACML eval. For now, we do deny unless permit, which is the easiest to implement because it takes into account the
-		 * isSuperUser() and isEmptyAclAndAuthorized()
+		 * We do deny-unless-permit combining between ACL and XACML evaluation, which is the easiest to implement because it takes into account the isSuperUser() and isEmptyAclAndAuthorized().
 		 */
 		if (simpleAclAuthorized || this.pdpClient == null)
 		{
 			return simpleAclAuthorized;
 		}
 		/*
-		 * Denied by ACL and pdpClient != null. Is it denied by PDP?
+		 * Denied by ACL and pdpClient != null. Is it denied by XACML PDP?
 		 */
-		LOGGER.debug("Authorization denied by SimpleAclAuthorizer. Trying XACML evaluation...");
+		LOGGER.debug("Authorization denied by SimpleAclAuthorizer. Trying evaluation by XACML PDP...");
 		final Map<String, Object> root = ImmutableMap.of("clientHost", session.clientAddress(), "principal", session.principal(), "operation", operation.toJava(), "resourceType",
 		        resource.resourceType().toJava(), "resourceName", resource.name());
 		final StringWriter out = new StringWriter();
@@ -187,12 +235,13 @@ public boolean authorize(Session session, Operation operation, Resource resource
 		}
 
 		final String xacmlReq = out.toString();
-		LOGGER.debug("Calling PDP with client = {}, XACML request: {}", this.pdpClient, xacmlReq);
 		final JSONObject jsonRequest = new JSONObject(xacmlReq);
 		final JSONObject jsonResponse = pdpClient.post(jsonRequest, JSONObject.class);
 		Xacml3JsonUtils.RESPONSE_SCHEMA.validate(jsonResponse);
 		final String decision = jsonResponse.getJSONArray("Response").getJSONObject(0).getString("Decision");
-		return decision.equals("Permit");
+		final boolean isAuthorized = decision.equals("Permit");
+		LOGGER.debug("isAuthorized (true iff Permit) = {}", isAuthorized);
+		return isAuthorized;
 	}
 
 }
diff --git a/src/test/java/org/ow2/authzforce/kafka/pep/test/CombinedXacmlAclAutorizerTest.java b/src/test/java/org/ow2/authzforce/kafka/pep/test/CombinedXacmlAclAutorizerTest.java
@@ -18,14 +18,11 @@
 
 package org.ow2.authzforce.kafka.pep.test;
 
-import java.io.File;
 import java.io.IOException;
 import java.net.InetAddress;
 import java.net.UnknownHostException;
-import java.nio.file.Files;
 import java.util.Map;
 import java.util.Set;
-import java.util.stream.Collectors;
 
 import org.apache.kafka.common.acl.AclOperation;
 import org.apache.kafka.common.resource.ResourceType;
@@ -41,7 +38,6 @@
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
 import org.springframework.test.context.junit4.SpringRunner;
-import org.springframework.util.ResourceUtils;
 
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
@@ -103,11 +99,9 @@ public CombinedXacmlAclAutorizerTest() throws UnknownHostException
 	@Before
 	public void setUp() throws IOException
 	{
-		final File xacmlReqTmplFile = ResourceUtils.getFile(XACML_REQ_TMPL_LOCATION);
-
-		final String xacmlReqTmplStr = Files.lines(xacmlReqTmplFile.toPath()).collect(Collectors.joining());
-		authorizer.configure(ImmutableMap.of(KafkaConfig.ZkConnectProp(), SHARED_ZOOKEEPER_TEST_RESOURCE.getZookeeperConnectString(), CombinedXacmlAclAuthorizer.XACML_PDP_URL,
-		        "http://localhost:" + port + "/services/pdp", CombinedXacmlAclAuthorizer.XACML_REQUEST_TEMPLATE_CFG_PROPERTY_NAME, xacmlReqTmplStr));
+		authorizer.configure(ImmutableMap.of(KafkaConfig.ZkConnectProp(), SHARED_ZOOKEEPER_TEST_RESOURCE.getZookeeperConnectString(), CombinedXacmlAclAuthorizer.XACML_PDP_URL_CFG_PROPERTY_NAME,
+		        "http://localhost:" + port + "/services/pdp" /* "http://localhost:8080/authzforce-ce/domains/A0bdIbmGEeWhFwcKrC9gSQ/pdp" */,
+		        CombinedXacmlAclAuthorizer.XACML_REQUEST_TEMPLATE_LOCATION_CFG_PROPERTY_NAME, XACML_REQ_TMPL_LOCATION));
 	}
 
 	private void testAuthorization(String username, boolean expectedAuthorized)
