XACML
provides a very flexible language for expressing access control
policies. This document offers guidance on writing a range of
useful policies for Fedora such as 1) broad repository-wide policies for
controlling access to Fedora API operations, 2) more detailed
repository-wide policies for controlling access to groups of digital objects
based on various attributes, and 3) more fine-grained object-specific policies
for controlling access to individual digital objects. It
should be noted that to help users who do not wish to learn native XACML, a
Policy Authoring Client is currently under development that will provide an
easy graphical user interface for creating XACML policies for Fedora.
This
guide also provides a collection of sample XACML policies is intended as
reference material to help in writing custom XACML policies for Fedora.
The sample policies demonstrate one possible authoring style for XACML, in
recognition that there are other ways to write XACML policies that have the
same effect. Most of the sample repository-wide policies are
authored to have a single effect, meaning that each policy has a
single rule that either permits or denies access. This style of
policy writing results in many individual policies, but each policy is atomic
and uncomplicated. An alternative is to have fewer policies, each with
multiple rules within. This multi-rule approach can result in more
complicated policies, but is, nevertheless, appropriate for writing object-specific
policies in Fedora where a single policy states all the rules for
a particular digital object. In either case, it is essential
to understand the policy combining algorithm that is configured for your
repository's XACML-based Authorization module. By default, the "Deny
Overrides" algorithm is configured in Fedora, which means that when
multiple policies are applicable to an incoming request, deny will trump
permit. As you add new policies to the mix, you must be aware of
what kinds of policies are already active in the repository.
Also, when writing a policy that contains more than one rule, you must
understand the the rule combining algorithm (which is specified in the root
element of an individual XACML policy). The sample policies use the
"first-applicable" rule combining algorithm, which means that the
first applicable rule in the policy will prevail.
This
document is not intended to be a comprehensive tutorial on writing XACML
policies. Anyone intending to author custom XACML policies for
Fedora is encouraged to read the following documentation provided by OASIS
Technical Committee that defined the XACML standard, and Sun who is the
provider of the open source Sun XACML engine that is used in the Fedora
implementation. It is very important to understand the basics
of XACML to ensure that a suite of policies works as intended. One
of the most important concepts in using XACML is understanding how multiple
policies can interact with each other (in good ways, or in ways you didn't intend).
By following the examples in this guide, you should be able to set up many
kinds of access control policies for your repository. With
additional help from the following documents, you should be able to do more
advanced policies, and change some of the XACML settings for how sets of
policies are combined.
More
information on writing XACML policies:
OASIS
XACML Specification: this is the official specification and a good
reference document.
A
Brief Introduction to XACML: this is nice introduction to the XACML
concepts
OASIS
XACML Technical Committee: this home page of the technical
committee provides access to other documents on XACML
More
information on the Fedora security architecture:
Securing Your Repository : documentation on
security options and configuring configuring user authentication sources for
Fedora repositories
Fedora Authorization with XACML Policy
Enforcement : documentation on configuration and implementation of the
Fedora XACML-based policy enforcement module
Binding to user attributes to policies :
a discussion of how to use attributes from different sources (e.g., Tomcat,
LDAP, Shibboleth) in policies
A Fedora-specific policy vocabulary is
defined to enable the creation of XACML policies for Fedora repositories and digital
objects. This vocabulary define a set of URNs that can be used to
identify specific Fedora API operations, Fedora object attributes, and the
Fedora environment within an XACML policy. These URNs are used as
attribute designators in XACML policies, specifically within a
SubjectAttributeDesignator, ResourceAttributeDesignator,
ActionAttributeDesignator, or
EnvironmentAttributeDesignator.
The
set of identifiers defined for the Fedora policy vocabulary is automatically
generated on Fedora build and can be found in the Fedora software distribution
at:
Under
Windows:
%FEDORA_HOME%\server\fedora-internal-use\vocabulary.txt
Under
Unix:
$FEDORA_HOME\server\fedora-internal-use\vocabulary.txt
This
vocabulary provides a set of identifiers (URNs) that can appear in XACML
policies to refer to Fedora API operations (Actions in XACML), any aspects of a
Fedora digital object (Resources in XACML), key attributes of the environment
in which Fedora runs in (Environment in XACML), and common subject (i.e., user)
attributes. (Other user attributes are named according to site-usage and
so their names aren't included in the Fedora XACML vocabulary.)
Every
policy has an identifier, a rule combining algorithm, and a description.
In the root element of an XACML policy there is an attribute to provide the
policy with a unique identifier. Also, the <Description>
element provides a place to put a textual description of the purpose of the
policy.
<Policy PolicyId="deny-apia" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" xmlns="urn:oasis:names:tc:xacml:1.0:policy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Description>This policy will DENY access to THESIS datastreams.</Description><Target>
... </Target> <Rule> ... </Rule></Policy>
The
main body of a policy consists of a Policy Target and one or more Rules
which are described in the next sections. Note that in the root element
of a policy, the rule combining algorithm (i.e., attribute
“RuleCombiningAlgID”), specifies how the Fedora Policy Enforcement Module will
deal with multiple Rules in a policy (how those rules are combined and
evaluated together). This algorithm is valid for only the specific policy
containing it, and is independent of similar algorithms in other policies. It
governs how the various effects of the potentially several rules of a policy
are combined into the single effect of the policy as a whole. It is also
independent of the policy-combining algorithm operative for all policies
collectively, which governs how the various results of all policies are
combined into a single result.
A Policy Target is the part of a policy that specifies
matching criteria for figuring out whether a particular policy is applicable to
an incoming service request. A Target contains three basic
"matching" components: Subjects, Actions, and Resources.
All of these components must be matched to the context of an incoming request
for the policy to be applicable. These matching specifications can
be built upon XACML Functions. (A fourth
matching component, Environments, is defined in XACML and will be available in
Fedora's XACML policies when it is available in the Sun XACML version as used
in Fedora.)
<Policy PolicyId="deny-apia" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" xmlns="urn:oasis:names:tc:xacml:1.0:policy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Description>This policy will DENY access to THESIS datastreams.</Description> <Target> <Subjects>...
</Subjects>
<Resources>...
</Resources>
<Actions>...
</Actions> </Target><Rule/>
</Policy>
A
Policy Target can be specified for a Policy (or for a PolicySet, which is an
advanced way of grouping policies together). A <Target>
element is defined at the Policy level (as a child of the root <Policy>
element). A Policy Target applies to any contained Rules that are
expressed in that policy. However, a Rule may have its own Target, in
which case the Rule-level Target overrides — for that Rule only — the Policy level
Target. Typically, a Target defined at the Rule level is used to replace
and so tighten a broader match specification found at the overall Policy level.
(This is described below.)
<Resources>
All Fedora resources (objects, datastreams, disseminations)
have attribute identifiers defined in the Fedora policy vocabulary (see:
dist/server/config/xacml-policies/vocabulary.txt).
The <Resources> element of a Policy Target is used to
wrap one or more descriptions of the kinds of Fedora resources (objects,
datastreams, disseminations, etc.) that the policy should apply to. At
runtime, the Policy Enforcement Module will compare attributes of a requested
resource against the criteria in the <Resources> specification within the
policy Target to determine if the policy is applicable to the incoming request.
For example, to define a policy that is applicable to any Fedora resource, the
following is specified:
<Resources> <AnyResource/> </Resources>
Within a single <Resource> specification, there may be
one or more attributes that together determine whether a policy match should
occur. Each <ResourceMatch> element is used to specify the
name/value of an attribute of a Fedora resource. Multiple <ResourceMatch>
elements are used to specify multiple attributes of a resource, and are logically
AND-ed together. This means that for a policy to be applicable to an
incoming service request, all <ResourceMatch>
specifications must match the attributes of the requested Fedora resource.
The AttributeID in the <ResourceAttributeDesignator> element is used to
identify a particular resource attribute by a URN, as defined in the Fedora
policy vocabulary. In the example below, there are two attributes to
match on: “urn:…datastream:id” and “urn:…mimeType”. The snippet says that
a policy match will occur if the incoming request context indicates that the
requested resource has the datastream id of THESIS and the MIME type of
“application/pdf.”
<Resources> <Resource> <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <ResourceAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:resource:datastream:id" DataType="http://www.w3.org/2001/XMLSchema#string"/> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">THESIS</AttributeValue> </ResourceMatch>
<ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <ResourceAttributeDesignator AttributeId=" urn:fedora:names:fedora:2.1:resource:datastream:mimeType" DataType="http://www.w3.org/2001/XMLSchema#string"/> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">application/pdf</AttributeValue> </ResourceMatch> </Resource> </Resources>
To create an OR condition for resource
matching, multiple <Resource> elements must be specified. If
there are multiple <Resource> elements within the
<Resources> wrapper component, the <Resource> elements are logically
OR-ed together. This means that a match on only one of the Resource
specifications is necessary for the policy to apply to a service request.
For example, the snippet below says that a resource match will occur if the
incoming request is for a digital object that has the content model type of
either “UVA_STD_IMAGE” or “MRSID.”
<Resources> <Resource> <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">UVA_STD_IMAGE</AttributeValue> <ResourceAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:resource:object:contentModel" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ResourceMatch> </Resource>
<Resource> <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">MRSID</AttributeValue> <ResourceAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:resource:object:contentModel" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ResourceMatch> </Resource> </Resources>
<Actions>
All Fedora service operations have an action identifier in
defined by the Fedora policy vocabulary (see:
dist/server/config/xacml-policies/vocabulary.txt).
The <Actions> element of a Policy Target is used to
wrap one or more service operations that this policy should apply to. At
runtime, the Policy Enforcement Module will compare the identity of an incoming
request against the criteria specific in the <Actions> of a Target in a
policy. For example, to define a policy that is applicable to any
Fedora service operation, the following is specified:
<Actions> <AnyAction/></Actions>
From a practical standpoint in Fedora, there are only two
attributes that pertain to identifying Fedora API operations: 1) an
attribute that indicates what Fedora API is in context, and 2) an attribute
that indicates the specific service operation within that
API. To create a policy that is intended for an entire
service (e.g., ALL operations of API-A) do the following:
<Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">urn:fedora:names:fedora:2.1:action:api-a</AttributeValue> <ActionAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:action:api" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action></Actions>
To create a policy that is about a specific operation in a
Fedora API do the following:
<Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">urn:fedora:names:fedora:2.1:action:id-getDatastreamDissemination</AttributeValue> <ActionAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:action:id" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action></Actions>
The above can be considered a shortcut for fully qualifying
a service operation within its respective service API. An
alternative way to specify an Action as a Fedora API operation is to refer to
the Fedora service API AND the service operation. As
with <SubjectMatch> and <ResourceMatch> specifications, multiple <ActionMatch>
elements are logically AND-ed together. For
example the following snippet says that the policy will match if the incoming
request pertains to the Fedora API-A service AND the service request is for the
the “getDatastreamDissemination” operation.
<Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">urn:fedora:names:fedora:2.1:action:api-a</AttributeValue> <ActionAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:action:api" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch>
<ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">urn:fedora:names:fedora:2.1:action:id-getDatastreamDissemination</AttributeValue> <ActionAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:action:id" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action></Actions>
To create an OR condition for action matching,
multiple <Action> elements must be specified. If there are
multiple <Action> elements within the <Actions> wrapper
component, the <Action> elements are logically OR-ed together.
This means that a match on only one of the Action specifications is necessary
for the policy to apply to a service request. For example, the snippet
below says that a resource match will occur if the incoming request is either
the getDatastreamDissemination operation of API-A or the getDissemination
operation of API-A.
Note: The "shortcut" method of referring to
a Fedora API operation is used in the example (i.e., we have an ActionMatch for
the specific Fedora API of "api-a") because Fedora actions
identifiers are unique in themselves. Fedora automatically knows that the
getDatastreamDissemination operation is part of API-A.
<Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">urn:fedora:names:fedora:2.1:action:id-getDatastreamDissemination</AttributeValue> <ActionAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:action:id" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action>
<Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">urn:fedora:names:fedora:2.1:action:id-getDissemination</AttributeValue> <ActionAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:action:id" DataType="http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action></Actions>
<Subjects>
The Fedora policy vocabulary (see:
dist/server/config/xacml-policies/vocabulary.txt) defines general-purpose
attributes for use in policies (e.g., login-id). However, attributes for subjects
will vary depending on what a repository uses as the source of user information
(e.g., tomcat-users.xml, LDAP, Shibboleth). Fedora XACML policies
can make reference to the identifiers of any subject attribute that can be
passed into Fedora from authenticating sources. See the section below on
“Getting User Attributes into the Fedora Policy Enforcement Module” for more
information on the sources of subject attributes.
The <Subjects> element of a Policy Target is used to
wrap one or more descriptions of users or agents that this policy should apply
to. At runtime, the Fedora Policy Enforcement Module will compare
attributes of the user/agent making a service request against the criteria
specific in the <Subjects> specification of the policy Target to
determine if the policy is applicable to the incoming request. For
example, to define a policy that is applicable to any kind of user or agent,
the following is specified:
<Subjects> <AnySubject/> </Subjects>
Within a single <Subject> specification, there may be
one or more XACML attributes that together determine whether a policy match
should occur. Each <SubjectMatch> element is used to specify an
name/value of an attribute of a user/agent. Multiple <SubjectMatch>
elements are used to specify multiple attributes of a subject, and are logically
AND-ed together. This means that for a policy to be applicable to an
incoming service request, all <SubjectMatch> specifications
must match the attributes of the requesting user/agent. In the example
below, there is only one attribute to match on (i.e., “fedoraRole”). The
AttributeID in the <SubjectAttributeDesignator> element is used to
identify a particular subject attribute by its local or global identifier.
The snippet says that a policy match will occur if the incoming request context
indicates that the user/agent has a role attribute with the value of
“administrator.”
<Subjects> <Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">administrator</AttributeValue> <SubjectAttributeDesignator AttributeId="fedoraRole" MustBePresent="false" DataType="http://www.w3.org/2001/XMLSchema#string"/> </SubjectMatch> </Subject> </Subjects>
To create an OR condition for subject
matching, multiple <Subject> elements must be specified. If
there are multiple <Subject> elements within the <Subjects>
wrapper component, the <Subject> elements are logically OR-ed together.
This means that a match on only one of the Subject specifications is necessary
for the policy to apply to a service request. For example, the snippet
below says that a subject match will occur if the requesting user has the role
of either “administrator” or “superuser.”
<Subjects> <Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">administrator</AttributeValue> <SubjectAttributeDesignator AttributeId="fedoraRole" MustBePresent="false" DataType="http://www.w3.org/2001/XMLSchema#string"/> </SubjectMatch> </Subject>
<Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">superuser</AttributeValue> <SubjectAttributeDesignator AttributeId="fedoraRole" MustBePresent="false" DataType="http://www.w3.org/2001/XMLSchema#string"/> </SubjectMatch> </Subject> </Subjects>
<Environments>
The
Environments component of a Target is intended to specify aspects of the
runtime environment that would make the policy match the incoming
request. Such attributes include the current date, current
time, the IP address of the client, and the protocol being used for the
request. The Environments element is discussed in the OASIS
XACML specification, but it is not yet implemented by the Sun XACML
engine that underlies the Fedora Authorization module. This
prevents the expression of environment matching criteria within Targets.
** Therefore, in Fedora 2.1 do not create policies that specify Environment matching criteria in the policy Target.
Although
the Environments element is not currently supported for use within a Target,
this does not mean that you cannot encode matching criteria for environmental
attributes within a policy. Within a policy Rule, you can specify a
Condition that contains matching criteria for environmental attributes.
Refer to the discussion of policy rules below for an example of Environment
attribute matching in a Condition.
Each
policy has at least one, and possibly more, rules. There must be at least one
Rule in a policy that matches the incoming request for a policy to be deemed
applicable to that request. The way the Sun XACML engine
determines whether a rule is applicable to an incoming request is by evaluating
the Target and optional Condition (if it exists). These are ANDed
together, and the rule's effect achieved if the ANDed value is TRUE. (If there
is no Condition, this result is simply the value of the Target.) The rule's
Target is so used, and if it has no Target, the policy's Target is used
instead.
<Policy PolicyId="deny-apia" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable" xmlns="urn:oasis:names:tc:xacml:1.0:policy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Description>This policy will DENY access to Dublin Core datastreams.</Description>
<Target> ... </Target>
<Rule RuleId="1" Effect="Deny"> <Target>...
</Target>
<Condition> ... </Condition></Rule>
</Policy>
<Rule>
A policy contains one or more Rules. Each rule has a RuleId
and and Effect. An Effect is the intended consequence of a
satisfied rule, which can be either "Deny" or
"Permit." This means that if the rule is
deemed applicable to an incoming service request, and the rule's conditions
evaluate to TRUE, then the specified effect should be enforced.
<Target>
Each Rule in a policy can have its own Rule Target.
While a Policy Target generally describes the kinds of requests to which an
entire policy applies, a Rule Target describes the kinds of request to which a
particular rule applies. If a Rule Target is not present, the
Policy Target is used to determine whether the Rule is applicable to an
incoming request. When a policy target exists, it is applicable to every
rule in the policy which does not have its own Target. In practice, a rule
target is often more constrained than the associated policy target, fine tuning
to specific Subject/Resource/Action match criteria that are in the context of a
the particular rule.
Refer to the documentation above for the Defining a Policy Target for the structure of a
Target, since rule and policy Targets are defined using the same
elements.
<Condition>
A Condition is a predicate that must be satisfied for a rule
to be assigned its effect. These predicates can be built
upon XACML Functions.
While Targets are appealing, frame-like expressions, they
have a constrained logic which isn't always expressive enough to narrow down
whether a policy is applicable to a service request. Hence, the need for
Condition elements. If either the policy Target or the rule Target
is not able to adequately express a constraint, a Condition can be added to a
Rule. A Condition can appear only within a Rule. It
cannot appear within a Target, nor directly under Policy or
PolicySet. If a Condition is intended to be applicable to the
entire Policy, the Condition must be repeated in every Rule in that
Policy. Unlike the relationship of rule targets to policy targets,
conditions do in fact begin with the associate (rule or policy) target, and
proceed to further constrain that target.
The XACML specification defines numerous functions that can
be used in defining attribute match criteria in Targets and in defining
predicates for Conditions. Consult the XACML
Specification for a complete list of functions with their
descriptions. For convenience, here is a small sampling of
convenient functions with their XACML identifiers:
Equality predicates
·
String
Equality -
urn:oasis:names:tc:xacml:1.0:function:string-equal
·
Boolean
Equality -
urn:oasis:names:tc:xacml:1.0:function:boolean-equal
·
Date/Time
Equality -
urn:oasis:names:tc:xacml:1.0:function:dateTime-equal
·
others
Logical functions
·
OR -
urn:oasis:names:tc:xacml:1.0:function:or
·
AND -
urn:oasis:names:tc:xacml:1.0:function:and
·
NOT -
urn:oasis:names:tc:xacml:1.0:function:not
·
others
Comparison functions
·
Greater
Than -
urn:oasis:names:tc:xacml:1.0:function:integer-greater-than
·
Less
Than -
urn:oasis:names:tc:xacml:1.0:function:type-bag
·
Greater
Than or Equal -
urn:oasis:names:tc:xacml:1.0:function:integer-greater-than-or-equal
·
Less
Than or Equal - urn:oasis:names:tc:xacml:1.0:function:integer-less-than-or-equal
·
Date/Time
Greater Than -
urn:oasis:names:tc:xacml:1.0:function:dateTime-greater-than
·
others
Bag and Set functions
·
Bag
of Strings -
urn:oasis:names:tc:xacml:1.0:function:string-bag
·
Member
of Set -
urn:oasis:names:tc:xacml:1.0:function:type-at-least-one-member-of
·
others
Below is an example Condition that uses several of these
functions. This Condition evaluates to TRUE if the client IP address
(from the environment of the incoming request) is NOT a member of a set of
privileged IP addresses. The Condition element itself contains an
outer-most function which is a negation function.
Within the condition, we see the application of the set membership
function, which specifies that the environment attribute
"clientIpAddress" (from the Fedora vocabulary) should be
evaluated. Finally, the inner most bag function wraps a set
of possible values for the clientIPAddress attribute. Again, if the
clientIpAddress on the incoming request is not one of those in the bag of
addresses, then the rule's Deny effect should take place.
<Condition FunctionId="urn:oasis:names:tc:xacml:1.0:function:not"> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-at-least-one-member-of"> <EnvironmentAttributeDesignator AttributeId="urn:fedora:names:fedora:2.1:environment:httpRequest:clientIpAddress" DataType="http://www.w3.org/2001/XMLSchema#string"/> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-bag"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">127.0.0.1</AttributeValue> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">128.84.103.11</AttributeValue> </Apply> </Apply></Condition>
In summary, each policy must have at least one Rule.
For a Rule to have an effect, (1) the Rule must match the incoming request by
virtue of a Target match (either via a policy Target, or a constraining rule
Target), and (2) if a Condition is specified, the condition predicate
evaluates to TRUE. An applicable rule will result in a Permit or
Deny for an incoming request, based on what is specified in the Rule Effect.
There
are times when an attribute that is referred to by a policy target will not be
available on an incoming service request. By default, when the policy
matching activity occurs - and an attribute specified in a policy is not
found in the incoming request context - an Indeterminate result is
returned and an authorization exception is thrown. Policy authors can
avoid unwanted Indeterminate results by indicating in the attribute designators
of a Target or Condition that a particular attribute can be considered optional
in terms of whether it must existing in the incoming request
context. This is done by setting MustBePresent="false" on a SubjectAttribututeDesignator,
ResourceAttributeDesignator, ActionAttributeDesignator, or
EnvironmentAttributeDesignator element. This will tell the
Fedora Policy Enforcement module that it's ok if the incoming request does not
have the specified attribute available within it. (The implicit/unstated
default is MustBePresent="true")
Let's
take an example to make this clearer. Consider a policy where the
SubjectMatch specification talks about an attribute "fedoraRole" and
specifies that the value of this attribute must be "administrator" in
order for this policy to be considered applicable by the PDP. Now
consider an incoming service request that has a user login id (e.g.,
"wdn5e") in the request context, but this user does not have a
"fedoraRole" attribute associated with it. So, when the
PEP tries to determine whether this policy is applicable to the incoming service
request, it returns INDETERMINATE because it can't figure out whether there is
a subject match without the presence of a "fedoraRole"
attribute. This will cause an authorization exception to be thrown
for the request because the PDP expects the "fedoraRole" attribute to
be present in the request context. However, we essentially
want to somehow indicate that the fedoraRole attribute is considered
"optional" on an incoming request (i.e., not every incoming request
must have this particular attribute in context). To do this, you
must indicate in the policy Target that the attribute does not have to be
present ("MustBePresent="false") in the incoming request as
follows:
<Subjects> <Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">administrator</AttributeValue> <SubjectAttributeDesignator AttributeId="fedoraRole" MustBePresent="false" DataType="http://www.w3.org/2001/XMLSchema#string"/> </SubjectMatch> </Subject></Subjects>
In
this example, it's easy to imagine that another policy could independently
permit access. Hence the fit of MustBePresent="false": if the policy
above lacks an attribute, it may not be crucial to the ultimate authorization
decision. Policies are not authored in isolation, but to work together.
<Policy
PolicyId="deny-objects-to-students" . . . > corresponds
to filename of "/repository-policies/deny-objects-to-students.xml"
<Policy
PolicyId="demo-5" . . . > corresponds
to filename of "/object-policies/demo-5.xml"
<Policy
PolicyId="demo-5"
RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable"
. . . >