force.authzforce-ce-core-pdp-engine.21.0.1.source-code.pdp.xsd Maven / Gradle / Ivy
Show all versions of authzforce-ce-core-pdp-engine Show documentation
Data model of AuthZForce PDP configuration.
XML schema versioning: the
version
attribute of the root
schema
element identifies the
Major.Minor
version of this
schema. The
Minor
version is used for any backwards-compatible change. The
Major
version is
incremented after any change that is NOT
backwards-compatible.
The
Major
version part
must be a suffix of the target namespace - but
not the
Minor
version - to
change the namespace when the backward compatibility is broken.
Reference to a policy element, i.e. a XACML PolicySet or XACML Policy
If version is not specified, look for the latest version.
If
policySet=true
, then look for a XACML PolicySet matching the identifier and versions if defined.
If
policySet=false
, 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.
Pair of compatible PDP input/output processors - resp.
requestPreproc
and
resultPostproc
- where
compatible
means:
requestPreproc.getOutputRequestType() ==
resultPostproc.getRequestType()
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
attribute
resultPostproc
.
There must be one and only one Java class on the classpath - say
com.example.FooRequestPreproc
- implementing
interface
org.ow2.authzforce.core.pdp.api.DecisionRequestPreprocessor
with
zero-arg
constructor, and this URI must match the one returned by:
new
com.example.FooRequestPreproc().getId()
.
If the configuration parameter
xPathEnabled
is true, it is the
responsibility of the Request preprocessor to parse XACML
Request/Attributes/Content
nodes. If the configuration
parameter
strictAttributeIssuerMatch
is true, it is the responsibility of
the Request preprocessor to keep values of
Attributes with Issuer
separate from values of Attributes
without Issuer, in
the
attribute
map returned by
getNamedAttributes()
on
the
IndividualDecisionRequests produced by the Request preprocessor.
The following values of
requestPreproc
are natively supported:
- urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:default-lax
-
implements only XACML 3.0 Core (NO support for Multiple Decision)
and allows
duplicate <Attribute> with
same
meta-data in the
same <Attributes> element of a Request
(complying with
XACML
3.0 core spec, §7.3.3)
- urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:default-strict
-
implements only XACML 3.0 Core (NO support for Multiple Decision)
and does not
allow duplicate
<Attribute>
with
same meta-data
in the same <Attributes> element of a
Request
(NOT
complying
with XACML 3.0 core spec,
§7.3.3, but better
performances)
-
urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:multiple:repeated-attribute-categories-lax
-
implements Multiple Decision Profile, section 2.3
(repeated
attribute
categories), and
allows duplicate <Attribute> with
same meta-data in the same
<Attributes> element of a Request
(complying with XACML 3.0
core spec, §7.3.3)
-
urn:ow2:authzforce:feature:pdp:request-preproc:xacml-xml:multiple:repeated-attribute-categories-strict
-
same as previous one, except it does not allow
duplicate
<Attribute>
with same
meta-data in the same
<Attributes> element of a Request (NOT complying with XACML
3.0 core spec,
§7.3.3, but better performances)
More info about Request Preprocessors is available on
AuthzForce
wiki
.
URI of a XACML decision Result post-processor to be enabled.
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 to the requester). For
example, a
typical Result post-processor may combine
multiple individual
decisions -
produced by the
requestPreproc
- to a
single
decision
Result if and only if the XACML Request's
CombinedDecision
is
set to
true, as defined in XACML Multiple Decision Profile
specification,
section 3.
There must be one
and only one Java class on the classpath
-
say
com.example.FooResultPostproc
-
implementing interface
org.ow2.authzforce.core.pdp.api.DecisionResultPostprocessor
with
zero-arg
constructor, and this URI must match the one returned by:
new
com.example.FooResultPostproc().getId()
.
More info about Result Postprocessors is available on
AuthzForce
wiki
.
PDP configuration
URI of an XACML attribute datatype to be added to supported data-types. Policies require
data-types for function arguments and AttributeAssignment expressions. For every
datatype,
there
must be
one and only one Java class on the classpath - say
com.example.FooValueFactory
- implementing interface
org.ow2.authzforce.core.pdp.api.value.AttributeValueFactory
with zero-arg
constructor, and this URI must match the one returned by
new com.example.FooValueFactory().getId()
.
More info about Attribute Data-types is available on
AuthzForce wiki
.
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
useStandardDatatypes
attribute, or custom ones declared in previous
attributeDatatype
elements; and there must be one and only one Java class - say
com.example.FooFunction
- on the
classpath implementing interface
org.ow2.authzforce.core.pdp.api.func.Function
with zero-arg constructor, and this URI must match the one returned by:
new com.example.FooFunction().getId()
.
More info about Functions is available on
AuthzForce wiki
.
URI of a XACML policy/rule-combining algorithm to be added to supported algorithms. There
must be one and only one Java class - say
com.example.FooCombiningAlg
- on the
classpath
implementing interface
org.ow2.authzforce.core.pdp.api.combining.CombiningAlg
with zero-arg constructor, and this URI must match the one returned by:
new
com.example.FooCombiningAlg().getId()
.
More info about Policy and Rule Combining Algorithms is available on
AuthzForce
wiki
.
XACML Policy Provider that resolves
Policy(Set)IdReference
s. There must be one and only one Java class on the classpath - say
com.example.FooPolicyProviderFactory
- implementing interface
org.ow2.authzforce.core.pdp.api.policy.CLoseablePolicyProvider.Factory<CONF_T>
with zero-arg constructor, where
CONF_T
is the JAXB type bound
to this XML element type.
More info about Policy Providers (how to make/use one) is available on
AuthzForce wiki
.
Implementation classes can use
org.ow2.authzforce.pd.api.EnvironmentProperties#replacePlaceholders()
method to replace
${property_name}
placeholders with such properties. You
may use
!
(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.
${PARENT_DIR!/home/foo/conf}
will be replaced with
/home/foo/conf
if
PARENT_DIR
is undefined.
In the location, you may use placeholders enclosed between
${
and
}
for the following properties:
-
the global property
PARENT_DIR
for
defining - in a generic way
- a path relative to the parent directory to the XML file where this is used;
- Java system properties;
- System environment variables.
Identifies the root policy from which the policy evaluation begins. This identifier must be
resolved by one of the Policy Providers configured previously (cf.
policyProvider
element). In case this is not specified, the first non-null policy returned by
PolicyProvider#getCandidateRootPolicy()
method - while iterating over the Policy Providers in order of declaration - is used as root
policy. Refer to the respective PolicyProvider's documentation for more information.
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
one and
only one Java class on
the classpath - say
com.example.FooDecisionCacheFactory
-implementing interface
org.ow2.authzforce.core.pdp.api.DecisionCache.Factory<CONF_T>
with zero-arg
constructor, where
CONF_T
is the JAXB type bound to this XML element type.
More info about Decision Cache extensions is available on
AuthzForce wiki
.
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.
Version of the current schema for which the instance
document is valid. Must match the
version
attribute value of the
root
schema
element in the corresponding version
of
this
schema.
Enable support for XACML core standard mandatory
data-types. If
false
, only data-types specified in
attributeDatatype
elements are available to the PDP, and therefore
only these
data-types may be used in policies.
Enable support for XACML core standard mandatory
functions. Requires
useStandardDatatypes=true
if true; if false, only functions specified in
function
elements are
available to
the PDP, and therefore only these
functions may be used in policies.
Enable support for XACML core standard combining
algorithms. If false, only algorithms specified in
combiningAlgorithm
elements are available to the PDP, and therefore
only these
algorithms may be used in policies.
Enable support for providing the following XACML core standard attributes if not provided in the request:
- urn:oasis:names:tc:xacml:1.0:environment:current-dateTime
- urn:oasis:names:tc:xacml:1.0:environment:current-date
- urn:oasis:names:tc:xacml:1.0:environment:current-time
This is equivalent to adding the following attributeProvider elements:
- StdEnvAttributeProviderDescriptor with id="_authzforce_pdp_attribute-provider_std-env" override="false"
You must set standardAttributeProvidersEnabled='false' if you need to configure a custom attributeProvider element of one of these types.
If standardAttributeProvidersEnabled='false', only providers specified in
attributeProvider
elements are enabled.
Enable support for
AttributeSelectors
,
xpathExpression
datatype and
xpath-node-count
function. This
overrides
useStandardDatatypes
parameter, i.e.
xpathExpression
is
not
supported
anyway if
xPathEnabled
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,
AttributeSelector
and
xpathExpression
datatype support is marked
as
optional in XACML 3.0 core specification.
true iff we want strict Attribute Issuer matching and we require that all
AttributeDesignators have a non-empty
Issuer.
Strict Attribute Issuer matching
means that an AttributeDesignator without Issuer matches only request
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
§5.29 says:
If the Issuer is not present in the AttributeDesignator, then the matching of the
attribute to the named
attribute SHALL be governed by AttributeId and
DataType attributes alone.
Therefore, if
strictAttributeIssuerMatch
is false, since policies may use
AttributeDesignator
s without
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
practice, when
strictAttributeIssuerMatch =
true
, we also require that all
AttributeDesignators set the Issuer field.
Maximum absolute integer value. This is the expected maximum absolute value for XACML attributes
of standard type
http://www.w3.org/2001/XMLSchema#integer
(requires
useStandardDatatypes
= true
). Decreasing this value as much
as
possible helps the PDP engine optimize the processing of integer
values (lower memory consumption, faster computations).
Maximum depth of Variable reference chaining:
VariableDefinition1 -> VariableDefinition2 -> ...
; where
->
represents a
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).
Maximum depth of Policy(Set) reference chaining:
PolicySet1 -> PolicySet2 -> ... -> Policy(Set)N
; where
->
represents
a
Policy(Set)IdReference
. 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).
Level of verbosity of the error message trace returned in case of client request errors, e.g.
invalid requests. Increasing this value
usually helps the clients better
pinpoint the
issue with their
Requests. This parameter is relevant to the Result postprocessor (
resultPostproc
parameter) which is expected to
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.
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
com.example.FooAttributeProviderFactory
-
implementing interface
org.ow2.authzforce.core.pdp.api.CloseableDesignatedAttributeProvider.Factory<CONF_T>
with
zero-arg
constructor,
where
CONF_T
is the JAXB type bound to
this
XML element type. This Attribute
Provider may also depend on
previously defined
attributeProviders
, to find dependency
attributes, i.e.
attributes that
this
Provider does not support
itself, but requires to find its supported
attributes. Therefore, if
an
attributeProvider
AP1
requires/depends on an
attribute
A that is
not to be provided in the XACML request from the PEP,
another
attributeProvider
AP2
providing this attribute A must be
declared
before AP1.
Values of id (Attribute Provider ID) starting with underscore ('_') are reserved for AuthzForce built-in attribute providers.
More info about Attribute Providers (how to make/use one) is available on
AuthzForce wiki
.
Such configurations (XML instances of this schema)
may use placeholders enclosed between
${
and
}
for the following properties:
-
the global property
PARENT_DIR
for defining - in a generic
way - a path relative to the parent directory to the XML file where this is used;
-
Java system properties;
-
System environment variables.
Implementation classes can use
org.ow2.authzforce.pd.api.EnvironmentProperties#replacePlaceholders()
to replace
${property_name}
placeholders with such properties.
You may use
!
(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.
${PARENT_DIR!/home/foo/conf}
will be
replaced with
/home/foo/conf
if
PARENT_DIR
is undefined.
In the location, you
may use placeholders enclosed between
${
and
}
for the following properties:
-
the global property
PARENT_DIR
for defining - in a generic way - a path relative to the parent directory to the
XML file where this is used;
-
Java system properties;
-
System environment variables.
Policy(Set) Provider loading policies
statically either inline or from URLs. Any
PolicyIdReference
used in a PolicySet here
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
of declaration of
policyLocation
s, the order
matters for
PolicySetIdReference resolution.
This PolicyProvider implements the
PolicyProvider#getCandidateRootPolicy()
- the method provides a default root policy to be used when the PDP's configuration parameter
rootPolicyRef
is undefined - as follows:
-
If there is one and only one XACML Policy provided (e.g. one or more
policyLocation
s are defined, pointing to one or more versions of the same XACML Policy), return the latest
version of this Policy;
-
Else apply the same rule to XACML PolicySet(s);
-
Else no candidate (e.g. there is more than one XACML Policy and more than one XACML PolicySet,
in which case the
rootPolicyRef
must be explicitly defined in PDP's configuration to make the choice).
Such policy provider may call previously declared providers (in 'policyProvider' elements) to
resolve unsupported policy references, but only if they are static policy providers as well, i.e.
each implementation implements interface
'org.ow2.authzforce.core.pdp.api.policy.StaticPolicyProvider'.
XACML PolicySet. If you want to use a XACML Policy, you may convert it to an
equivalent PolicySet as follows:
-
Create a PolicySet with
PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:only-one-applicable"
- Nest your XACML Policy into the PolicySet as only child.
Location of the XML file that is expected to
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
form
file://DIRECTORY_PATH/*SUFFIX
or
file://DIRECTORY_PATH/**...*SUFFIX
, etc. (arbitrarily long sequence of wildcard characters) in
which case the location is
expanded to all
regular
files in
the directory located at
DIRECTORY_PATH
with suffix
SUFFIX
, not crossing directory boundaries if using a single wildcard; but crossing
directory boundaries if using more than a single wildcard (there
may not be
a SUFFIX; in
other words, SUFFIX may be an
empty
string). The number of wildcards in the sequence
**....*
defines the
maximum number of directory levels to search.
In the location, you may use placeholders enclosed between
${
and
}
for the following properties:
-
The global property
PARENT_DIR
for
defining - in a generic way - a path relative to the
parent directory to the XML file where this is used;
- Java system properties;
- System environment variables.
You may use
!
(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.
${PARENT_DIR!/home/foo/conf}
will be
replaced with
/home/foo/conf
if
PARENT_DIR
is undefined.
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.
Provides the standard environment attributes specified
in XACML 3.0 Core specification, §10.2.5: current-time, current-date and current-dateTime.
By default, the PDP engine does not set these attributes on its own and only takes the ones from the request. This AttributeProvider is enabled with override='false' whenever standardAttributeProvidersEnabled='true', ensuring strict compliance with XACML 3.0 standard (§10.2.5): If
values for these
attributes are not present in
the decision request,
then their
values MUST be supplied
by the
context
handler. Note that it does
not
say If AND ONLY IF, therefore, the override=true mode (always override the values if present in the request) may still be considered XACML-compliant.
A StdEnvAttributeProviderDescriptor configuration may not occur more than once.
Defines whether the aforementioned attribute values (if present in the request) may
be overridden by the AttributeProvider:
- true: always override, i.e. this AttributeProvider sets the current-*
attribute always - to the PDP's current dateTime (when the request is received
by the PDP) - regardless of any value present in the request.
- false: override or not, depending on the attributes present in the
request:
- If the standard current-dateTime attribute is present in the
request, then:
- If either current-date or current-time is present
in the request and does not match current-dateTime
(inconsistency): return Indeterminate.
- Else if either current-date or current-time is missing from the
request, the AttributeProvider sets the attribute according to
current-dateTime.
- Else (both are present) the request values are used as is.
- Else (current-dateTime missing from the request):
- If either current-date or current-time is missing from the
request, the AttributeProvider sets the attribute to (the PDP's)
current date/time.
- Else (both are present) the request values are used as is, and
the current-dateTime is set (if required) according to
those request values of current-date and current-time.
AttributeProvider that provides attributes based on XACML VariableDefinitions, allowing to use XACML Variables like AttributeDesignators, typically in Match elements.
This Attribute Provider provides any attribute in the category designated by 'categoryId' by interpreting it as a XACML VariableReference, and the AttributeId as VariableId (Issuer ignored).
The value is returned as a singleton bag containing the Variable value as singleton value (or empty Bag if no such Variable defined).
Defines the attribute Category that is supported by this Attribute Provider, i.e.
any AttributeDesignator or AttributeSelector/ContextSelectorId with this Category is handled exactly like a VariableReference and the AttributeId used as VariableId (Issuer ignored).