Where it happens:

Redaction and filtering is performed in a Post Query Plugin that occurs after a query has been performed.

How it happens:

Each Metacard result will contain security attributes pulled from the metadata record after being processed by a PostQueryPlugin that populates this attribute. The security attribute is a HashMap containing a set of keys that map to lists of values. The Metacard will then be processed by a filter/redaction plugin that creates a KeyValueCollectionPermission from the Metacard's security attribute. This permission is then checked against the user Subject in order to determine if the Subject has the correct claims in order to view that Metacard. The decision of whether or not to filter/redact* the Metacard eventually ends up in the hands of the installed PDP. (features:install security-pdp-java OR features:install security-pdp-xacml). Whichever PDP is being used will return back a decision and the Metacard will either be filtered/redacted or allowed to pass through.

*The default setting is to redact records.

The security attributes populated on the Metacard are completely dependent on the type of the Metacard. Each type of Metacard must have its own PostQueryPlugin that reads the metadata being returned and populates the Metacard's security attribute. If either the subject or resource (Metacard) permissions are missing during redaction, that resource will be redacted.

Example (represented as simple XML for ease of understanding):

<metacard>
	<security>
		<map>
			<entry key="entry1" value="A,B" />
			<entry key="entry2" value="X,Y" />
			<entry key="entry3" value="USA,GBR" />
			<entry key="entry4" value="USA,AUS" />
		</map>
	</security>
</metacard>

<user>
	<claim name="claim1">
		<value>A</value>
		<value>B</value>
	</claim>
	<claim name="claim2">
		<value>X</value>
		<value>Y</value>
	</claim>
	<claim name="claim3">
		<value>USA</value>
	</claim>
	<claim name="claim4">
		<value>USA</value>
	</claim>
</user>

So with the above example, the user's claims are represented very simply and are similar to how they would actually appear in a SAML 2 assertion. Each of these user (or Subject) claims will be converted to a KeyValuePermission object. These permission objects will be implied against the permission object generated from the Metacard record. In this particular case, the Metacard might be allowed if the policy is configured appropriately, because all of the permissions line up correctly.

Redaction Policies:

Setting up a policy is different depending on which PDP implementation is installed. The security-pdp-java implementation is the simplest PDP to use, so it will be covered here:

Open the Web Console*
Click on the Configuration tab
Click on the Authz Security Settings configuration
Add any roles that are allowed to access protected services
Add any SOAP actions that are not to be protected by the PDP
Add any attribute mappings necessary to map between Subject claims and Metacard values
1. For example, the above example would require 2 Match All mappings of: claim1=entry1 and claim2=entry2
2. Match One mappings would contain: claim3=entry3 and claim4=entry4

*See the page at Security PDP AuthZ Realm for a description of the configuration page.

With the security-pdp-java feature configured in this way, the above Metacard would be displayed to the user.

The XACML PDP is explained in more detail in XACML Policy Decision Point (PDP). It is up to the administrator to write a XACML policy capable of returning the correct response message. The Java based PDP should perform adequately in most situations. It is also possible to install both the security-pdp-java and security-pdp-xacml features at the same time. The system could be configured in this way in order to allow the Java PDP to handle most cases and only have XACML policies to handle more complex situations than what the Java PDP is designed for. Just keep in mind that this would be a very complex configuration with both PDP's installed and it should only be done if you understand what you're doing.

How to redact a new type of Metacard:

All that is necessary to enable redaction/filtering on a new type of record is implementing a PostQueryPlugin that is able to read the String metadata contained within the Metacard record. The plugin must set the security attribute to a map of list of values extracted from the metacard. Note that in DDF, there is no default plugin that populates the security attribute on the Metacard. A plugin must be created to populate these fields in order for redaction/filtering to work correctly.

Example Redacted Record:

<?xml version="1.0" encoding="UTF-8"?>
<metacard xmlns="urn:catalog:metacard" xmlns:ns2="http://www.opengis.net/gml" xmlns:ns3="http://www.w3.org/1999/xlink" xmlns:ns4="http://www.w3.org/2001/SMIL20/" xmlns:ns5="http://www.w3.org/2001/SMIL20/Language" ns2:id="99f494b22f4341e9a3ba3ef6a5fe8734">
    <type>ddf.metacard</type>
    <source>ddf.distribution</source>
    <stringxml name="metadata">
        <value>
            <meta:Resource xmlns:meta="...">
  				<meta:identifier meta:qualifier="http://metadata/noaccess" meta:value="REDACTED"/>
  				<meta:title>REDACTED</meta:title>
  				<meta:creator>
    				<meta:Organization>
      					<meta:name>REDACTED</meta:name>
    				</meta:Organization>
  				</meta:creator>
  				<meta:subjectCoverage>
    				<meta:Subject>
      					<meta:category meta:label="REDACTED"/>
    				</meta:Subject>
  				</meta:subjectCoverage>
  				<meta:security SEC:controls="A B" SEC:group="X" SEC:origin="USA"/>
			</meta:Resource>
        </value>
    </stringxml>
    <string name="resource-uri">
        <value>catalog://metadata/noaccess</value>
    </string>
    <string name="title">
        <value>REDACTED</value>
    </string>
    <string name="resource-size">
        <value>REDACTED</value>
    </string>
</metacard>

Browser not supported