pdp.xsd 32.3 KB
Newer Older
1
<?xml version="1.0" encoding="UTF-8"?>
2
<xs:schema targetNamespace="http://authzforce.github.io/core/xmlns/pdp/7" elementFormDefault="qualified" version="7.1" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://authzforce.github.io/core/xmlns/pdp/7" xmlns:xacml="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" xmlns:authz-ext="http://authzforce.github.io/xmlns/pdp/ext/3" xmlns="http://www.w3.org/1999/xhtml">
3 4
	<import namespace="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" />
	<import namespace="http://authzforce.github.io/xmlns/pdp/ext/3" />
5 6 7
	<xs:annotation id="testeststset">
		<xs:documentation xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
		<p>
8
			Data model of AuthZForce PDP configuration.
9
			</p>
10
			<p>
11 12 13 14
				XML schema versioning: the <i>version</i> attribute of the root
				<i>schema</i>
				element identifies the <i>Major.Minor</i> version of this
				schema. The <i>Minor</i> version is used for any backwards-compatible change. The <i>Major</i> version is
15
				incremented after any change that is NOT
16 17 18
				backwards-compatible.
				The <i>Major</i> version part
				must be suffix of the target namespace - but
19
				not the
20
				<i>Minor</i>
21 22 23 24
				version - to
				separate namespaces that
				are not backwards-compatible.
			</p>
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
		</xs:documentation>
	</xs:annotation>
	<xs:element name="pdp">
	<xs:annotation>
			<xs:documentation>
			PDP configuration
			</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence>
				<xs:element name="attributeDatatype" type="xs:anyURI" minOccurs="0" maxOccurs="unbounded">
					<xs:annotation>
						<xs:documentation>
						<p>
							URI of an XACML attribute datatype to be added to supported datatypes. Policies require datatypes for function arguments and AttributeAssignment expressions. For every datatype,
40
							there
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
							must be one and only one Java class on the classpath - say <i>com.example.FooValueFactory</i> - implementing interface
							<i>org.ow2.authzforce.core.pdp.api.value.AttributeValueFactory</i> with zero-arg
							constructor, and this URI must match the one returned by <i>new com.example.FooValueFactory().getId()</i>.
							</p>
							<p>More info about Attribute Data-types is available on <a href="https://github.com/authzforce/core/wiki/XACML-Data-Types">AuthzForce wiki</a>.</p>
						</xs:documentation>
					</xs:annotation>
				</xs:element>
				<xs:element name="function" type="xs:anyURI" minOccurs="0" maxOccurs="unbounded">
					<xs:annotation>
						<xs:documentation>
							URI of a XACML function to be added to supported functions. For every function, its return type and all its parameter types must be either standard mandatory ones enabled by
							<i>useStandardDatatypes</i> attribute, or custom ones declared in previous <i>attributeDatatype</i> elements; and there must be one and only one Java class - say
							<i>com.example.FooFunction</i> - on the
							classpath implementing interface <i>org.ow2.authzforce.core.pdp.api.func.Function</i> with zero-arg constructor, and this URI must match the one returned by:
							<i>new com.example.FooFunction().getId()</i>.
							<p>More info about Functions is available on <a href="https://github.com/authzforce/core/wiki/XACML-Functions">AuthzForce wiki</a>.</p>
						</xs:documentation>
					</xs:annotation>
				</xs:element>
				<xs:element name="combiningAlgorithm" type="xs:anyURI" minOccurs="0" maxOccurs="unbounded">
					<xs:annotation>
						<xs:documentation>
							URI of a XACML policy/rule-combining algorithm to be added to supported algorithms. There must be one and only one Java class - say <i>com.example.FooCombiningAlg</i> - on the
65
							classpath
66 67 68 69 70 71 72 73 74 75 76 77 78
							implementing interface <i>org.ow2.authzforce.core.pdp.api.combining.CombiningAlg</i> with zero-arg constructor, and this URI must match the one returned by: <i>new
							com.example.FooCombiningAlg().getId()</i>.
							<p>More info about Policy and Rule Combining Algorithms is available on <a href="https://github.com/authzforce/core/wiki/XACML-Combining-Algorithms">AuthzForce wiki</a>.</p>
						</xs:documentation>
					</xs:annotation>
				</xs:element>
				<xs:element ref="tns:attributeProvider" maxOccurs="unbounded" minOccurs="0" />
				<xs:element name="policyProvider" type="authz-ext:AbstractPolicyProvider" minOccurs="1" maxOccurs="1">
					<xs:annotation>
						<xs:documentation>
							<p>
							XACML Policy Provider that resolves <i>Policy(Set)IdReference</i>s. There must be one and only one Java class on the classpath - say <i>com.example.FooPolicyProviderFactory</i> - implementing interface
							<i>org.ow2.authzforce.core.pdp.api.policy.CLoseablePolicyProvider.Factory&lt;CONF_T&gt;</i> with zero-arg constructor, where <i>CONF_T</i> is the JAXB type bound
79
							to this XML element type.
80 81
							</p>
							<p>More info about Policy Providers (how to make/use one) is available on <a href="https://github.com/authzforce/core/wiki/Policy-Providers">AuthzForce wiki</a>.</p>
82
							<p>
83 84
								Implementation classes can use <i>org.ow2.authzforce.pd.api.EnvironmentProperties#replacePlaceholders()</i> method to replace <i>${property_name}</i> placeholders with such properties. You
								may use <i>!</i> (exclamation mark) as a
85
								separating character between the placeholder property name and a default value that is used if the property is undefined. E.g.
86 87
								<i>${PARENT_DIR!/home/foo/conf}</i> will be replaced with
								<i>/home/foo/conf</i> if <i>PARENT_DIR</i> is undefined.
88

89 90 91
								In the location, you may use placeholders enclosed between <i>${</i> and <i>}</i> for the following properties: 
								<ul>
								<li>the global property <i>PARENT_DIR</i> for
92
								defining - in a generic way
93 94 95 96 97 98 99
								- a path relative to the parent directory to the XML file where this is used;
								</li> 
								<li>Java system properties;
								</li>
								<li>System environment variables.
								</li>
								</ul>
100
							</p>
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
						</xs:documentation>
					</xs:annotation>
				</xs:element>
				<xs:element name="rootPolicyRef" type="tns:TopLevelPolicyElementRef" minOccurs="0" maxOccurs="1">
					<xs:annotation>
						<xs:documentation>
							Identifies the root policy from which the policy evaluation begins. This identifier must be resolved by the Policy Provider configured previously (cf. <i>policyProvider</i>
							element). In case this is not specified, the policy returned by the <i>PolicyProvider#getCandidateRootPolicy()</i> method is used as root policy. Refer to the respective PolicyProvider's documentation for more information.
						</xs:documentation>
					</xs:annotation>
				</xs:element>
				<xs:element name="decisionCache" minOccurs="0" maxOccurs="1" type="authz-ext:AbstractDecisionCache">
					<xs:annotation>
						<xs:documentation>
						<p>
							Decision cache that, for a given request, provides the XACML policy evaluation result from a cache if there is a cached result for the given request. There must be
117
							one and
118 119 120 121 122 123 124 125 126 127 128
							only one Java class on the classpath - say <i>com.example.FooDecisionCacheFactory</i> -implementing interface
							<i>org.ow2.authzforce.core.pdp.api.DecisionCache.Factory&lt;CONF_T&gt;</i> with zero-arg
							constructor, where <i>CONF_T</i> is the JAXB type bound to this XML element type.
							</p>
							<p>More info about Decision Cache extensions is available on <a href="https://github.com/authzforce/core/wiki/Decision-Caches">AuthzForce wiki</a>.</p>
						</xs:documentation>
					</xs:annotation>
				</xs:element>
				<xs:element name="ioProcChain" type="tns:InOutProcChain" minOccurs="0" maxOccurs="unbounded">
					<xs:annotation>
						<xs:documentation>
129 130 131
							I/O processing chains if specific processing before and/or after policy evaluation by the PDP engine is required. Each chain must handle a different input datatype. In
							other words,
							there is no more than one I/O processing chain per supported input type, e.g. one for XACML/XML input, another for XACML/JSON input.
132 133 134 135 136 137 138 139
						</xs:documentation>
					</xs:annotation>
				</xs:element>
			</xs:sequence>
			<xs:attribute name="version" type="xs:token" use="required">
				<xs:annotation>
					<xs:documentation>Version of the current schema for which the instance
						document is valid. Must match the <i>version</i> attribute value of the
140
						root
141
						<i>schema</i> element in the corresponding version
142 143 144
						of
						this
						schema.
145 146 147 148 149 150 151
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="useStandardDatatypes" type="xs:boolean" use="optional" default="true">
				<xs:annotation>
					<xs:documentation>Enable support for XACML core standard mandatory
						datatypes. If <i>false</i>, only datatypes specified in <i>attributeDatatype</i> elements are available to the PDP, and therefore
152 153
						only these
						datatypes may be be used in policies.
154 155 156 157 158 159 160
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="useStandardFunctions" type="xs:boolean" use="optional" default="true">
				<xs:annotation>
					<xs:documentation>Enable support for XACML core standard mandatory
						functions. Requires <i>useStandardDatatypes=true</i> if true; if false, only functions specified in <i>function</i> elements are
161 162 163
						available to
						the PDP, and therefore only these
						functions may be be used in policies.
164 165 166 167 168 169 170
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="useStandardCombiningAlgorithms" type="xs:boolean" use="optional" default="true">
				<xs:annotation>
					<xs:documentation>Enable support for XACML core standard combining
						algorithms. If false, only algorithms specified in <i>combiningAlgorithm</i> elements are available to the PDP, and therefore
171 172
						only these
						algorithms may be be used in policies.
173 174 175 176 177 178 179 180 181 182
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="standardEnvAttributeSource" type="tns:StandardEnvironmentAttributeSource" use="optional" default="REQUEST_ELSE_PDP" />
			<xs:attribute name="enableXPath" type="xs:boolean" use="optional" default="false">
				<xs:annotation>
					<xs:documentation>Enable support for <i>AttributeSelectors</i>,
						<i>xpathExpression</i> datatype and <i>xpath-node-count</i> function. This
						overrides <i>useStandardDatatypes</i>
						parameter, i.e. <i>xpathExpression</i>
183 184 185
						is
						not
						supported
186
						anyway if <i>enableXpath</i>
187 188 189 190 191 192 193
						is false. This feature is
						experimental (not to be used in
						production) and
						may have a negative
						impact on performance. Use
						with caution. For your
						information,
194 195
						<i>AttributeSelector</i> and
						<i>xpathExpression</i>
196 197 198
						datatype support is marked
						as
						optional in XACML 3.0 core specification.
199 200 201 202 203 204
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="strictAttributeIssuerMatch" type="xs:boolean" use="optional" default="false">
				<xs:annotation>
					<xs:documentation>
205 206 207
						<p>true iff we want strict Attribute Issuer matching and we require that all AttributeDesignators set the
							Issuer field.</p>
						<p>
208
							<i>Strict Attribute Issuer matching</i> means that an AttributeDesignator without Issuer matches only request
209 210 211 212 213 214 215
							Attributes without Issuer. This mode is not fully compliant with XACML 3.0,
							§5.29, in the
							case that
							the Issuer is not present in the Attribute Designator, but
							it performs better and is recommended when all AttributeDesignators have an Issuer (best
							practice). Indeed, the XACML 3.0
							Attribute Evaluation section
216
							§5.29 says: <i>If the Issuer is not present in the AttributeDesignator, then the matching of the
217 218
							attribute to the named
							attribute SHALL be governed by AttributeId and
219 220
							DataType attributes alone.</i>
							Therefore, if <i>strictAttributeIssuerMatch</i> is false, since policies may use <i>AttributeDesignator</i>s without
221 222 223 224 225 226 227
							Issuer,
							if the requests are using matching Attributes but with
							none, one or more different Issuers, this PDP
							engine has to gather all the values from all the attributes with
							matching Category/AttributeId but
							with any Issuer or no Issuer. Therefore, in order
							to stay compliant with §5.29 and still enforce best
228 229
							practice, when <i>strictAttributeIssuerMatch =
							true</i>, we also require that all
230
							AttributeDesignators set the Issuer field.</p>
231 232 233 234 235 236 237 238
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="maxIntegerValue" type="positiveInteger" use="optional" default="2147483647">
				<xs:annotation>
					<xs:documentation> Maximum absolute integer value. This is the expected maximum absolute value for XACML attributes of standard type <i>http://www.w3.org/2001/XMLSchema#integer</i> (requires
						<i>useStandardDatatypes
						= true</i>). Decreasing this value as much
239 240 241
						as
						possible helps the PDP engine optimize the processing of integer
						values (lower memory consumption, faster computations).
242 243 244 245 246 247 248 249
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="maxVariableRefDepth" type="xs:nonNegativeInteger" use="optional">
				<xs:annotation>
					<xs:documentation> Maximum depth of Variable reference chaining:
						<i>VariableDefinition1 -&gt; VariableDefinition2 -&gt; ...</i>; where
						<i>-&gt;</i> represents a
250 251 252 253
						VariableReference. It is recommended to
						specify a
						value for this attribute in production for security/safety reasons.
						Indeed, if not specified, no maximum is enforced (unlimited).
254 255 256 257 258 259 260 261 262
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="maxPolicyRefDepth" type="xs:nonNegativeInteger" use="optional">
				<xs:annotation>
					<xs:documentation>Maximum depth of Policy(Set) reference chaining:
						<i>PolicySet1 -&gt; PolicySet2 -&gt; ... -&gt; Policy(Set)N</i>; where
						<i>-&gt;</i> represents
						a <i>Policy(Set)IdReference</i>. It is
263 264 265
						recommended to
						specify a value for this attribute in production for security/safety reasons.
						Indeed, if not specified, no maximum is enforced (unlimited).
266 267 268 269 270 271
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
			<xs:attribute name="clientRequestErrorVerbosityLevel" type="xs:nonNegativeInteger" use="optional" default="0">
				<xs:annotation>
					<xs:documentation>Level of verbosity of the error message trace returned in case of client request errors, e.g. invalid requests. Increasing this value
272 273
						usually helps the clients better
						pinpoint the
274
						issue with their Requests. This parameter is relevant to the Result postprocessor (<i>resultPostproc</i> parameter) which is expected to
275 276 277 278 279 280 281
						enforce this verbosity level when
						returning
						Indeterminate Results
						due to client request errors. The Result postprocessor must return all error messages in the Java stacktrace up to the same level as this parameter's
						value if
						the stacktrace is bigger, else the
						full stacktrace.
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398
					</xs:documentation>
				</xs:annotation>
			</xs:attribute>
		</xs:complexType>
		<xs:key name="datatypeKey">
			<xs:selector xpath="tns:attributeDatatype" />
			<xs:field xpath="." />
		</xs:key>
		<xs:key name="functionKey">
			<xs:selector xpath="tns:function" />
			<xs:field xpath="." />
		</xs:key>
		<xs:key name="algorithmKey">
			<xs:selector xpath="tns:combiningAlgorithm" />
			<xs:field xpath="." />
		</xs:key>
		<xs:key name="refPolicyProviderKey">
			<xs:selector xpath="tns:refPolicyProvider" />
			<xs:field xpath="@id" />
		</xs:key>
		<xs:key name="attributeProviderKey">
			<xs:selector xpath="tns:attributeProvider" />
			<xs:field xpath="@id" />
		</xs:key>
		<xs:key name="requestPreprocKey">
			<xs:selector xpath="tns:ioProcChain/tns:requestPreproc" />
			<xs:field xpath="." />
		</xs:key>
	</xs:element>
	<xs:element name="attributeProvider" type="authz-ext:AbstractAttributeProvider">
		<xs:annotation>
			<xs:documentation>
				<p>XACML Attribute Provider that provides attributes not already provided
					in the XACML request from PEP, e.g. from external sources. There must
					be one and
					only one Java class on the classpath - say
					<i>com.example.FooAttributeProviderFactory</i> - 
					implementing interface
					<i>org.ow2.authzforce.core.pdp.api.CloseableDesignatedAttributeProvider.Factory&lt;CONF_T&gt;</i>
					with
					zero-arg
					constructor,
					where
					<i>CONF_T</i> is the JAXB type bound to
					this
					XML element type. This Attribute
					Provider may also depend on
					previously defined
					<i>attributeProviders</i>, to find dependency
					attributes, i.e.
					attributes that
					this
					Provider does not support
					itself, but requires to find its supported
					attributes. Therefore, if
					an <i>attributeProvider</i> AP1
					requires/depends on an
					attribute
					A that is
					not to be provided in the XACML request from the PEP,
					another <i>attributeProvider</i> AP2
					providing this attribute A must be
					declared
					before AP1.
				</p>
				<p>More info about Attribute Providers (how to make/use one) is available on <a href="https://github.com/authzforce/core/wiki/Attribute-Providers">AuthzForce wiki</a>.</p>
				<p>
					Such configurations (XML instances of this schema)
					may use placeholders enclosed between <i>${</i> and <i>}</i> for the following properties:
					<ul>
					<li>
					the global property <i>PARENT_DIR</i> for defining - in a generic
					way - a path relative to the parent directory to the XML file where this is used;
					</li>
					<li>
					Java system properties;
					</li>
					<li>
					System environment variables.
					</li>
					</ul>
				</p>
				<p>
					Implementation classes can use
					<i>org.ow2.authzforce.pd.api.EnvironmentProperties#replacePlaceholders()</i>
					to replace <i>${property_name}</i> placeholders with such properties.
					You may use <i>!</i> (exclamation mark) as a separating character
					between the placeholder
					property name
					and a default value that is used if the property is undefined.
					E.g. <i>${PARENT_DIR!/home/foo/conf}</i> will be
					replaced with
					<i>/home/foo/conf</i> if <i>PARENT_DIR</i> is undefined.
</p>
<p>
					In the location, you
					may use placeholders enclosed between <i>${</i> and <i>}</i> for the following properties:
					<ul>
					<li>
					the global property <i>PARENT_DIR</i> for defining - in a generic way - a path relative to the parent directory to the
					XML file where this is used;
					</li>
					<li>
					Java system properties;
					</li>
					<li>
					System environment variables.
					</li>
					</ul>
</p>
			</xs:documentation>
		</xs:annotation>
	</xs:element>
	<xs:simpleType name="StandardEnvironmentAttributeSource">
		<xs:annotation>
			<xs:documentation>
			<p>
399 400 401 402
				Defines the source for the standard environment attributes specified
				in §10.2.5: current-time, current-date and current-dateTime.
				The
				options are:
403 404 405 406
				<dl>
					<dt>REQUEST_ELSE_PDP</dt>
					<dd>The default choice, that complies with the
						XACML standard (§10.2.5): <i>If
407 408 409 410 411 412 413
						values for these attributes are not
						present in the
						decision request,
						then their
						values MUST be
						supplied
						by
414
						the context handler</i>. In our case, <i>context handler</i> means the
415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443
						PDP. In other words, the
						attribute values come from request by
						default, or from the PDP
						if (and *only if* in
						this case) they are
						not set
						in the request.
						More precisely, if
						any of these standard environment attributes is provided in the request,
						none of the PDP values is used, even if some
						policy requires one that is
						missing from the
						request.
						Indeed, this is to avoid such case when the decision request
						specifies at least one date/time attribute, e.g.
						current-time,
						but not
						all of them, e.g. not current-dateTime, and the policy
						requires both the one(s) provided and the one(s) not provided.
						In this case, if the PDP provides its own value(s)
						for the missing
						attributes (e.g. current-dateTime), this may cause some
						inconsistencies since we
						end up having date/time attributes coming
						from two different sources/environments (current-time and
						current-dateTime for instance).
						In short, since this option introduces
						some ambiguities with regards to the XACMl specification, we strongly recommend to use
						the other options
444 445 446
						below.</dd>
					<dt>REQUEST_ONLY</dt>
					<dd>Always use the value from the request, or nothing
447 448 449 450 451
						if the value is not set in the request, in which case this results
						in
						Indeterminate (missing attribute) if the
						policy
						evaluation
452 453 454
						requires it.</dd>
					<dt>PDP_ONLY</dt>
					<dd>Always use the values from the PDP. In other words,
455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474
						Request values are simply ignored; PDP values systematically
						override the ones
						from the request.
						This also guarantees that
						they
						are
						always set (by the PDP).
						NB: note that the XACML standard
						(§10.2.5) says: "If
						values for these
						attributes are not present in
						the decision request,
						then their
						values MUST be supplied
						by the
						context
						handler" but it does NOT
						say "If AND ONLY IF
						values..." So
						this option could still be considered XACML compliant in a strict
475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495
						sense.</dd>
				</dl>
				</p>
			</xs:documentation>
		</xs:annotation>
		<xs:restriction base="xs:string">
			<xs:enumeration value="REQUEST_ELSE_PDP"></xs:enumeration>
			<xs:enumeration value="REQUEST_ONLY"></xs:enumeration>
			<xs:enumeration value="PDP_ONLY"></xs:enumeration>
		</xs:restriction>
	</xs:simpleType>
	<xs:complexType name="InOutProcChain">
		<xs:annotation>
			<xs:documentation><p>Pair of compatible PDP input/output processors - resp. <i>requestPreproc</i> and <i>resultPostproc</i> - where <i>compatible</i> means: <i>requestPreproc.getOutputRequestType() ==
				resultPostproc.getRequestType()</i></p>
			</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="requestPreproc" type="xs:anyURI">
				<xs:annotation>
					<xs:documentation>
496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528
						<p>URI of a XACML Request pre-processor to be enabled. A XACML Request
							preprocessor is a PDP extension that applies some processing of the
							request, such as
							validation and
							transformation, prior to
							the
							policy
							evaluation. As an example of validation, a Request preprocessor
							may reject a
							request containing an
							unsupported XACML element. As
							an example of
							transformation, it may support
							the
							MultiRequests
							element, and more generally the Multiple Decision
							Profile or
							Hierarchical
							Resource Profile by creating multiple
							Individual
							Decision
							Requests from the original
							XACML request, as defined in
							XACML
							Multiple Decision Profile specification, section 2; and then
							call the
							policy evaluation engine for each Individual
							Decision
							Request. At
							the end,
							the results (one per Individual Decision
							Request)
							may be combined by a Result postprocessor specified by next
529
							attribute <i>resultPostproc</i>.
530
						</p>
531 532
						<p>There must be one and only one Java class on the classpath - say
							<i>com.example.FooRequestPreproc</i> - implementing
533
							interface
534
							<i>org.ow2.authzforce.core.pdp.api.DecisionRequestPreprocessor</i> with
535
							zero-arg
536 537 538
							constructor, and this URI must match the one returned by: <i>new
							com.example.FooRequestPreproc().getId()</i>.</p>
						<p>If the configuration parameter <i>enableXPath</i> is true, it is the
539 540 541 542
							responsibility of the Request preprocessor to parse XACML
							Request/Attributes/Content
							nodes. If the configuration
							parameter
543
							<i>strictAttributeIssuerMatch</i> is true, it is the responsibility of
544 545 546 547 548 549
							the Request preprocessor to keep values of
							Attributes with Issuer
							separate from values of Attributes
							without Issuer, in
							the
							attribute
550
							map returned by <i>getNamedAttributes()</i> on
551 552
							the
							IndividualDecisionRequests produced by the Request preprocessor.</p>
553 554 555 556 557
							
						<p>The following values of <i>requestPreproc</i> are natively supported:
						<dl>
						<dt>urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:default-lax</dt>
						<dd>
558 559 560 561 562 563 564
							implements only XACML 3.0 Core (NO support for Multiple Decision)
							and allows
							duplicate &lt;Attribute&gt; with
							same
							meta-data in the
							same &lt;Attributes&gt; element of a Request
							(complying with XACML
565 566 567
							3.0 core spec, §7.3.3)</dd>
						<dt>urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:default-strict</dt>
						<dd>
568 569 570 571 572 573 574 575 576 577 578
							implements only XACML 3.0 Core (NO support for Multiple Decision)
							and does not
							allow duplicate
							&lt;Attribute&gt;
							with
							same meta-data
							in the same &lt;Attributes&gt; element of a
							Request
							(NOT complying
							with XACML 3.0 core spec,
							§7.3.3, but better
579 580 581
							performances)</dd>							
						<dt>urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:multiple:repeated-attribute-categories-lax</dt>
						<dd>
582 583 584 585 586 587 588 589
							implements Multiple Decision Profile, section 2.3
							(repeated
							attribute
							categories), and
							allows duplicate &lt;Attribute&gt; with
							same meta-data in the same
							&lt;Attributes&gt; element of a Request
							(complying with XACML 3.0
590 591 592
							core spec, §7.3.3)</dd>
						<dt>urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:multiple:repeated-attribute-categories-strict</dt>
						<dd>
593 594 595 596 597 598 599
							same as previous one, except it does not allow
							duplicate
							&lt;Attribute&gt;
							with same
							meta-data in the same
							&lt;Attributes&gt; element of a Request (NOT complying with XACML
							3.0 core spec,
600 601 602 603 604 605 606 607 608 609 610
							§7.3.3, but better performances)</dd>
							</dl>
							</p>
							<p>More info about Request Preprocessors is available on <a href="https://github.com/authzforce/core/wiki/XACML-Request-Preprocessors">AuthzForce wiki</a>.</p>
					</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="resultPostproc" type="xs:anyURI" minOccurs="0">
				<xs:annotation>
					<xs:documentation>
					<p>URI of a XACML decision Result post-processor to be enabled.
611 612 613 614 615 616 617 618 619 620 621
						A decision Result post-processor is a PDP extension that process the
						result(s) from the
						policy evaluation before
						the final
						XACML
						Response is created (and returned back to the requester). For
						example, a
						typical Result post-processor may combine
						multiple individual
						decisions -
						produced by the
622
						<i>requestPreproc</i> - to a
623 624
						single
						decision
625
						Result if and only if the XACML Request's <i>CombinedDecision</i>
626 627 628 629 630 631
						is
						set to
						true, as defined in XACML Multiple Decision Profile
						specification,
						section 3.
						There must be one
632
						and only one Java class on the classpath
633 634
						-
						say
635
						<i>com.example.FooResultPostproc</i> - 
636
						implementing interface
637
						<i>org.ow2.authzforce.core.pdp.api.DecisionResultPostprocessor</i> with
638
						zero-arg
639 640
						constructor, and this URI must match the one returned by:
						<i>
641
						new
642 643 644 645 646 647 648 649 650
						com.example.FooResultPostproc().getId()
						</i>.
						</p>
						<p>More info about Result Postprocessors is available on <a href="https://github.com/authzforce/core/wiki/XACML-Result-Postprocessors">AuthzForce wiki</a>.</p>
						
					</xs:documentation>
				</xs:annotation>
			</xs:element>
		</xs:sequence>
651

652 653 654 655 656 657 658
	</xs:complexType>
	<xs:complexType name="StaticPolicyProvider">
		<xs:annotation>
			<xs:documentation>
			<p>
			Policy(Set) Provider loading policies
				statically from URLs. Any <i>PolicyIdReference</i> used in a PolicySet here
659 660 661 662 663 664 665
				must refer to a
				Policy loaded here as well. Besides, a
				PolicySet
				P1
				must be loaded before any other PolicySet P2 with a reference
				(PolicySetIdReference) to P1. As
				PolicySets are loaded in the order
666
				of declaration of <i>policyLocation</i>s, the order
667 668
				matters for
				PolicySetIdReference resolution.
669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691
				This PolicyProvider implements the <i>PolicyProvider#getCandidateRootPolicy()</i> - the method provides a default root policy to be used when the PDP's configuration parameter <i>rootPolicyRef</i> is undefined - as follows:
				<ul>
				<li>
				If there is one and only one XACML Policy provided (e.g. one or more <i>policyLocation</i>s are defined, pointing to one or more versions of the same XACML Policy), return the latest version of this Policy;
				</li>
				<li>
				Else apply the same rule to XACML PolicySet(s); 
				</li>
				<li>
				Else no candidate (e.g. there is more than one XACML Policy and more than one XACML PolicySet, in which case the <i>rootPolicyRef</i> must be explicitly defined in PDP's configuration to make the choice).
				</li>
				</ul>
				</p>
			</xs:documentation>
		</xs:annotation>
		<xs:complexContent>
			<xs:extension base="authz-ext:AbstractPolicyProvider">
				<xs:sequence>
					<xs:element name="policyLocation" type="xs:anyURI" minOccurs="1" maxOccurs="unbounded">
						<xs:annotation>
							<xs:documentation>
							<p>
							 Location of the XML file that is expected to
692 693 694 695 696
								contain the Policy or PolicySet element to be referenced by a
								Policy(Set)IdReference in the root PolicySet loaded by a
								root
								policy
								Provider. The location may also be a file pattern in the
697
								form <i>file://DIRECTORY_PATH/*SUFFIX</i> or <i>file://DIRECTORY_PATH/**...*SUFFIX</i>, etc. (arbitrarily long sequence of wildcard characters) in
698 699 700 701 702
								which case the location is
								expanded to all
								regular
								files in
								the directory located at
703
								<i>DIRECTORY_PATH</i> with suffix <i>SUFFIX</i>, not crossing directory boundaries if using a single wildcard; but crossing
704 705 706 707
								directory boundaries if using more than a single wildcard (there
								may not be
								a SUFFIX; in
								other words, SUFFIX may be an empty
708
								string). The number of wildcards in the sequence <i>**....*</i> defines the
709
								maximum number of directory levels to search.
710 711 712 713 714
</p>
<p>
								In the location, you may use placeholders enclosed between <i>${</i> and <i>}</i> for the following properties:
								<ul>
							<li>The global property <i>PARENT_DIR</i> for
715 716
								defining - in a generic way - a path relative to the
								parent directory to the XML file where this is used;
717 718 719 720 721 722 723 724 725
</li>
<li>Java system properties;
</li>
<li>System environment variables.
</li>
</ul>
</p>
<p>
								You may use <i>!</i> (exclamation mark) as a separating
726 727 728
								character
								between the placeholder property name
								and a default value that is used if the property is undefined.
729
								E.g. <i>${PARENT_DIR!/home/foo/conf}</i> will be
730
								replaced with
731
								<i>/home/foo/conf</i> if <i>PARENT_DIR</i>
732
								is undefined.
733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766
								</p>
							</xs:documentation>
						</xs:annotation>
					</xs:element>
				</xs:sequence>
				<xs:attribute name="ignoreOldVersions" type="xs:boolean" use="optional" default="false">
					<xs:annotation>
						<xs:documentation>true iff all versions of any policy must be ignored except the last, i.e. whenever there are multiple versions for the same policy ID, do as if only the last one exists.
						</xs:documentation>
					</xs:annotation>
				</xs:attribute>
			</xs:extension>
		</xs:complexContent>
	</xs:complexType>
	<xs:complexType name="TopLevelPolicyElementRef">
		<xs:annotation>
			<xs:documentation>Reference to a policy element, i.e. a XACML PolicySet or XACML Policy</xs:documentation>
		</xs:annotation>
		<xs:simpleContent>
			<xs:extension base="xs:anyURI">
				<xs:attribute name="version" type="xacml:VersionType" use="optional">
					<xs:annotation>
						<xs:documentation>If version is not specified, look for the latest version.</xs:documentation>
					</xs:annotation></xs:attribute>
				<xs:attribute name="policySet" type="xs:boolean" use="optional">
					<xs:annotation>
						<xs:documentation>If <i>policySet=true</i>, then look for a XACML PolicySet matching the identifier and versions if defined.
If <i>policySet=false</i>, then look for a XACML Policy matching the identifier and versions if defined.
If this attribute is not specified, look for a XACML Policy matching the identifier and version, then if not found, look for a XACML PolicySet matching the identifier and version.</xs:documentation>
					</xs:annotation></xs:attribute>
			</xs:extension>
		</xs:simpleContent>
	</xs:complexType>
</xs:schema>