Date: Tue, 19 Mar 2024 04:17:35 -0400 (EDT) Message-ID: <118751498.8697.1710836255540@lyrasis1-roc-mp1> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_8696_718676195.1710836255540" ------=_Part_8696_718676195.1710836255540 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
XACML provides a very flexible language for expressing access control po= licies. This document offers guidance on writing a range of useful policies= for Fedora such as
This guide also provides a collection of sample XACML policies intended =
as reference material to help in writing custom XACML policies for Fedora. =
The sample policies demonstrate one possible authoring style for XACML; the=
re are other ways to write XACML policies that have the same effect. Most o=
f the sample repository-wide policies are authored to have a si=
ngle effect, meaning that each policy has a single rule that =
either permits or denies access. This style of policy writing results in ma=
ny individual policies, but each policy is atomic and uncomplicated. An alt=
ernative is to have fewer policies, each with multiple rules within. This m=
ulti-rule approach can result in more complicated policies, but is, neverth=
eless, 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 r=
epository's XACML-based Authorization module. By default, the "Deny Overrid=
es" algorithm is configured in Fedora, which means that when multiple polic=
ies are applicable to an incoming request, deny will trump permit. As you a=
dd 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 contain=
s 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 Techni= cal 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 implementati= on. 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 exampl= es 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 docu= ments, 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 Spec= ification: this is the official specification and a good reference docu= ment
A Brie= f Introduction to XACML: this is nice introduction to the XACML concept= s
OASIS XACML Technical Commi= ttee: this home page of the technical committee provides access to othe= r documents on XACML
More information on the Fedora security architecture:= p>
Fedora Authorizat= ion 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 t= he 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 XA= CML policies, specifically within a SubjectAttributeDesignator, ResourceAtt= ributeDesignator, ActionAttributeDesignator, or EnvironmentAttributeDesigna= tor.
The set of identifiers defined for the Fedora policy vocabulary can be f= ound in the Fedora software distribution at:
$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 as= pects of a Fedora digital object (Resources in XACML), key attributes of th= e environment in which Fedora runs in (Environment in XACML), and common su= bject (i.e., user) attributes. (Other user attributes are named according t= o site-usage and so their names aren't included in the Fedora XACML vocabul= ary.)
Every policy has an identifier, a rule combining algorithm, and a descri= ption. In the root element of an XACML policy there is an attribute to prov= ide the policy with a unique identifier. Also, the <Description> elem= ent provides a place to put a textual description of the purpose of the pol= icy.
<Pol= icy PolicyId=3D"deny-apia" RuleCombiningAlgId=3D"urn:oasis:names:tc:xacml:1.0:rule-combining-algor= ithm:first-applicable" xmlns=3D"urn:oasis:names:tc:xacml:1.0:policy" xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"> <Description>This policy will DENY access to THESIS datastreams.&= lt;/Description> <Target> ... </Target> <Rule> ... </Rule> </Policy>
The main body of a policy consists of a Policy Target a= nd one or more Rules which are described in the next secti= ons. Note that in the root element of a policy, the rule combining algorith= m (i.e., attribute "RuleCombiningAlgID"), specifies how the Fedora Policy E= nforcement Module will deal with multiple Rules in a policy (how those rule= s are combined and evaluated together). This algorithm is valid for only th= e specific policy containing it, and is independent of similar algorithms i= n other policies. It governs how the various effects of the potentially sev= eral 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 operativ= e for all policies collectively, which governs how the various results of a= ll 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:
<Pol= icy PolicyId=3D"deny-apia" RuleCombiningAlgId=3D"urn:oasis:names:tc:xacml:1.0:rule-combining-a= lgorithm:first-applicable" xmlns=3D"urn:oasis:names:tc:xacml:1.0:policy" xmlns:xsi=3D"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> elemen= t is defined at the Policy level (as a child of the root <Policy> ele= ment). 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 Ru= le-level Target overrides =E2=80=94 for that Rule only =E2=80=94 the Policy= level Target. Typically, a Target defined at the Rule level is used to rep= lace and so tighten a broader match specification found at the overall Poli= cy level. (This is described below.)
All Fedora resources (objects and datastreams) have attribute identifier= s defined in the Fedora policy vocabulary (see: ^vocabulary.txt).
The <Resources> element of a Policy Target is use= d to wrap one or more descriptions of the kinds of Fedora resources (object= s, datastreams, disseminations, etc.) that the policy should apply to. At r= untime, the Policy Enforcement Module will compare attributes of a requeste= d resource against the criteria in the <Resources> specification with= in the policy Target to determine if the policy is applicable to the incomi= ng request. For example, to define a policy that is applicable to any Fedor= a resource, the following is specified:
<Res= ources> <AnyResource/> </Resources>
Within a single <Resource> specification, there may be one or more= attributes that together determine whether a policy match should occur. Ea= ch <ResourceMatch> element is used to specify the name/value of an at= tribute of a Fedora resource.
If multiple <ResourceMatch> elements are specified, they will be l= ogically ANDed together, meaning that for a policy to be a= pplicable to an incoming service request, all <ResourceMatch> specifications must match the attributes of the re= quested Fedora resource. The AttributeID in the <ResourceAttributeDesign= ator> element is used to identify a particular resource attribute by a U= RN, as defined in the Fedora policy vocabulary. In the example below, there= are two attributes to match on: "urn:...datastream:id" and "urn:...mimeTyp= e". The snippet says that a policy match will occur if the incoming request= context indicates that the requested resource has the datastream id of THE= SIS and the MIME type of "application/pdf."
<Res= ources> <Resource> <ResourceMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:stri= ng-equal"> <ResourceAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:resource:*datastream:id*= " DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> THESIS </AttributeValue> </ResourceMatch> <ResourceMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:stri= ng-equal"> <ResourceAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:resource:datastream:mime= Type" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> application/pdf </AttributeValue> </ResourceMatch> </Resource> </Resources>
To create an OR condition for resource= matching, multiple <Resource> elements must be specified. If there a= re multiple <Resource> elements within the <Resou= rces> wrapper component, the <Resource> elements are logic= ally OR-ed together. This means that a match on only one of the Re= source specifications is necessary for the policy to apply to a service req= uest. 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."
<Res= ources> <Resource> <ResourceMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> UVA_STD_IMAGE </AttributeValue> <ResourceAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:resource:object:contentM= odel" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </ResourceMatch> </Resource> <Resource> <ResourceMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> MRSID </AttributeValue> <ResourceAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:resource:object:contentM= odel" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </ResourceMatch> </Resource> </Resources>
All Fedora service operations have an action identifier in defined by th= e Fedora policy vocabulary (see: ^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 inc=
oming request against the criteria specific in the <Actions> of a Tar=
get in a policy. For example, to define a policy that is applicable to
<Act= ions> <AnyAction/> </Actions>
From a practical standpoint in Fedora, there are only two attributes tha= t pertain to identifying Fedora API operations:
To create a policy that is intended for an entire service (e.g.= , ALL operations of API-A) do the following:
<Act= ions> <Action> <ActionMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType=3D"http://www.w3.org2001/XMLSchema#string= "> urn:fedora:names:fedora:2.1:action:api-a </AttributeValue> <ActionAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:action:api" DataType=3D"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:
<Act= ions> <Action> <ActionMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string= -equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#string"> urn:fedora:names:fedora:2.1:action:id-getDatastreamDissemination </AttributeValue> <ActionAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:action:id" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action> </Actions>
The above can be considered a shortcut for fully qualifying a service op=
eration 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
<Act= ions> <Action> <ActionMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string= -equal"> <AttributeValue DataType=3D"http://www.w3.or/2001/XMLSchema#string= "> urn:fedora:names:fedora:2.1:action:api-a </AttributeValue> <ActionAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:action:api" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> <ActionMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string= -equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> urn:fedora:names:fedora:2.1:action:id-getDatastreamDissemination </AttributeValue> <ActionAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:action:id" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action> </Actions>
To create an OR condition for action m= atching, multiple <Action> elements must be specified. If there are m= ultiple <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 speci= fications is necessary for the policy to apply to a service request. For ex= ample, the snippet below says that a resource match will occur if the incom= ing request is either the getDatastreamDisseminat= ion operation of API-A or the getDissemination operation of API-A.
Note: The "shortcut" method of referring to a Fedora API operation i= s 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 themselve= s. Fedora automatically knows that the getDatastreamDissemination operation= is part of API-A.
<Act= ions> <Action> <ActionMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string= -equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> urn:fedora:names:fedora:2.1:action:id-getDatastreamDissemination </AttributeValue> <ActionAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:action:id" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action> <Action> <ActionMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:string= -equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> urn:fedora:names:fedora:2.1:action:id-getDissemination </AttributeValue> <ActionAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:action:id" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </ActionMatch> </Action> </Actions>
The Fedora policy vocabulary (see: ^vocabulary.txt) defines general-purp= ose attributes for use in policies (e.g., login-id). However, attributes fo= r subjects will vary depending on what a repository uses as the source of u= ser information (e.g., tomcat-users.xml, LDAP, Shibboleth). Fedora XACML po= licies can make reference to the identifiers of any subject attribute that = can be passed into Fedora from authenticating sources. See the section belo= w on "Getting User Attributes into the Fedora Policy Enforcement Module" fo= r 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 shoul= d apply to. At runtime, the Fedora Policy Enforcement Module will compare a= ttributes of the user/agent making a service request against the criteria s= pecific in the <Subjects> specification of the policy Target to deter= mine if the policy is applicable to the incoming request. For example, to d= efine a policy that is applicable to any kind of user or agent, the followi= ng is specified:
<Sub= jects> <AnySubject/> </Subjects>
Within a single <Subject> specification, there may be one or more = XACML attributes that together determine whether a policy match should occu= r. 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 A= ND-ed together. This means that for a policy to be applicable to a= n incoming service request, all <SubjectMatch&= gt; specifications must match the attributes of the requesting user/agent. = In the example below, there is only one attribute to match on (i.e., "fedor= aRole"). The AttributeID in the <SubjectAttributeDesignator> element = is used to identify a particular subject attribute by its local or global i= dentifier. 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."
<Sub= jects> <Subject> <SubjectMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:strin= g-equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> administrator </AttributeValue> <SubjectAttributeDesignator AttributeId=3D"fedoraRole" MustBePrese= nt=3D"false" DataType=3D"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."
<Sub= jects> <Subject> <SubjectMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:strin= g-equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> administrator </AttributeValue> <SubjectAttributeDesignator AttributeId=3D"fedoraRole" MustBePrese= nt=3D"false" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </SubjectMatch> </Subject> <Subject> <SubjectMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:strin= g-equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> superuser </AttributeValue> <SubjectAttributeDesignator AttributeId=3D"fedoraRole" MustBePrese= nt=3D"false" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </SubjectMatch> </Subject> </Subjects>
The Environments component of a Target is intended to specify aspects of= the runtime environment that would make the policy match the incoming requ= est. Such attributes include the current date, current time, the IP address= of the client, and the protocol being used for the request. The En= vironments 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 expr= ession of environment matching criteria within Targets.
Therefore, do not create policies that specify Environment matching = criteria in the policy Target.
Although the Environments element is not currently supported for use wit= hin a Target, this does not mean that you cannot encode matching criteria f= or environmental attributes within a policy. Within a policy Rule, you can = specify a Condition that contains matching criteria for environmental attri= butes. Refer to the discussion of policy rules below for an example of Envi= ronment 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 deter= mines 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 Targ= et is so used, and if it has no Target, the policy's Target is used instead= .
<Pol= icy PolicyId=3D"deny-apia" RuleCombiningAlgId=3D"urn:oasis:names:tc:xacml:1.0:rule-combining-algorit= hm:first-applicable" xmlns=3D"urn:oasis:names:tc:xacml:1.0:policy" xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"> <Description>This policy will DENY access to Dublin Core datastream= s.</Description> <Target> ... </Target> <Rule RuleId=3D"1" Effect=3D"Deny"> <Target> ... </Target> <Condition> ... </Condition> </Rule> </Policy>
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 th= at 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 en= forced.
Each Rule in a policy can have its own Rule Target. While a Policy Targe= t generally describes the kinds of requests to which an entire policy appli= es, 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 det= ermine 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 element= s.
A Condition is a predicate that must be satisfied for a rule to be assig= ned its effect. These predicates can be built upon XACML Functions.
While Targets are appealing, frame-like expressions, they have a constra= ined logic which isn't always expressive enough to narrow down whether a po= licy is applicable to a service request. Hence, the need for Condition elem= ents. If either the policy Target or the rule Target is not able to adequat= ely express a constraint, a Condition can be added to a Rule. _ A C= ondition 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 e= very Rule in that Policy. Unlike the relationship of rule targets to policy= targets, conditions do in fact begin with the associate (rule or policy) t= arget, and proceed to further constrain that target.
The XACML specification defines numerous functions that can be used in d= efining attribute match criteria in Targets and in defining predicates for = Conditions. Consult the XACML Specification for a complete list of functions with their de= scriptions. For convenience, here is a small sampling of convenient functio= ns with their XACML identifiers:
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 address= es. The Condition element itself contains an outer-most function which is a= negation function. Wit= hin the condition, we see the application of the set membership= function, which specifies that the environment attribute "cl= ientIpAddress" (from the Fedora vocabulary) should be evaluated. Finally, t= he inner most bag function wraps a set of possibl= e values for the clientIPAddress attribute. Again, if the clientIpAddress o= n the incoming request is not one of those in the bag of addresses, then th= e rule's Deny effect should take place.
<Con= dition FunctionId=3D"urn:oasis:names:tc:xacml:1.0:function:not"> <Apply FunctionId=3D"urn:oasis:names:tc:xacml:1.0:function:string-at-l= east-one-member-of"> <EnvironmentAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:environment:httpRequest:cl= ientIpAddress" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> <Apply FunctionId=3D"urn:oasis:names:tc:xacml:1.0:function:string-ba= g"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> 127.0.0.1 </AttributeValue> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> 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 Targ= et 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 i= s not found in the incoming request context - an Indeterminate result is re= turned and an authorization exception is thrown. Policy authors can avoid u= nwanted Indeterminate results by indicating in the attribute designators of= a Target or Condition that a particular attribute can be considered option= al in terms of whether it must existing in the incoming request context. Th= is is done by setting MustBePresent=3D"false" on a SubjectAttribututeDesign= ator, ResourceAttributeDesignator, ActionAttributeDesignator, or Environmen= tAttributeDesignator element. This will tell the Fedora Policy Enforcement = module that it's ok if the incoming request does not have the specified att= ribute available within it. (The implicit/unstated default is MustBePresent= =3D"true")
Let's take an example to make this clearer. Consider a policy where the = SubjectMatch specification talks about an attribute "fedoraRole" and specif= ies that the value of this attribute must be "administrator" in order for t= his 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 co= ntext, 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 "fedo= raRole" attribute. This will cause an authorization exception to be thrown = for the request because the PDP expects the "fedoraRole" attribute to be pr= esent in the request context. However, we essentially want to somehow indic= ate that the fedoraRole attribute is considered "optional" on an incoming r= equest (i.e., not every incoming request must have this particular attribut= e in context). To do this, you must indicate in the policy Target that the = attribute does not have to be present ("MustBePresent=3D"false") in the inc= oming request as follows:
<Sub= jects> <Subject> <SubjectMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:strin= g-equal"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#strin= g"> administrator </AttributeValue> <SubjectAttributeDesignator AttributeId=3D"fedoraRole" MustBePrese= nt=3D"false" DataType=3D"http://www.w3.org/2001/XMLSchema#string"/> </SubjectMatch> </Subject> </Subjects>
In this example, it's easy to imagine that another policy could independ= ently permit access. Hence the fit of MustBePresent=3D"false": if the polic= y above lacks an attribute, it may not be crucial to the ultimate authoriza= tion decision. Policies are not authored in isolation, but to work together= .
<Res= ourceMatch MatchId=3D"urn:oasis:names:tc:xacml:1.0:function:dateTime-less-t= han"> <AttributeValue DataType=3D"http://www.w3.org/2001/XMLSchema#dateTime"= > 2004-12-07T20:22:26.705Z </AttributeValue> <ResourceAttributeDesignator AttributeId=3D"urn:fedora:names:fedora:2.1:resource:object:lastModified= Date" DataType=3D"http://www.w3.org/2001/XMLSchema#dateTime"/> </ResourceMatch>
out-of-the-box, the Fedora repository is configured with a default set o= f access control policies that provide for a highly restricted management s= ervice (API-M), an open access service (API-A), and an open OAI provider se= rvice. These default access control policies establish the same level of ou= t-of-the-box security on the repository that was previously configured for = Fedora 2.0 release; however, as of Fedora 2.1 these basic access controls a= re now specified as XACML policies. Please consult the Default R= epository Policies documentation for a description of each default poli= cy.
The sample policies are written with the assumption that Fedora's Default Repository-Wide Polici= es are unedited and activated. These default policies lock down access = to the Fedora API-M service so that only the Fedora Administrator is permit= ted access. The default policies also result in open access to API-A (all u= sers are permitted). Given this starting point, you can think writing custo= m policies as a way to "loosen up" the API-M defaults and "tighten up" the = API-I defaults. In other words, it is likely that you will want to write po= licies that let more users have access to API-M operations. Also, you will = likely want to add restrictions in who can access digital objects, datastre= ams, and disseminations (i.e., via API-A). The sample policies will demonst= rate how to do these things, given various authentication scenarios. Notice= that there are some policies which restrict access based on user identity/= attributes based on Tomcat's default user directory ( tomcat-users.xml). Ot= her policies demonstrate how to restrict access by user attributes/groups t= hat are defined in an LDAP directory.
Note that the sample policies have been written for demonstration purpos= es. They are not intended to work as a collaborative set of policies, since= they often demonstrate different ways of of doing the same basic thing (e.= g., one policy demonstrating rules based on Tomcat user identity, another s= howing a similar thing with LDAP groups). If you want to try them out, you = can put one or more of the sample policies into play by following the instr= uctions for activating and loading polic= ies into a Fedora repository. However, it is recommended that you test = them individually to understand the effect each policy has. This approach o= f augmenting the default policies, which are left as-is, allows progressive= learning, without endangering your repository. It may be that this approac= h goes farther in opening up API-M than in tighting up API-I, and that even= tually the default policy for API-A will need to be replaced by one or more= policies written to your site's needs. So it goes. Ultimately, you can pro= ceed to write a meaningful suite of policies that are intended to work toge= ther for your repository.
Policy | Service | XACML Policy File | Policy Description |
4.1.1 | API-A | deny-apia-to-ldap-group.xml | Deny access to all API-A methods to users who are "Librarians" or "Info= Technologists" (as indicated by their LDAP attributes). |
4.1.2 | API-A | deny-apia-if-not-tomcat-role.xm= l | This policy will DENY access to ALL API-A methods to users who are NOT = in the "administrator" or "professor" ROLES. |
4.1.3 | API-A | deny-apia-to-tomcat-user.xml | This policy will deny access to all API-A methods to a particular user = based on login id (as registered in the tomcat-users.xml file). |
4.1.4 | API-A | deny-apia-except-by-owner.xml | Deny access to all API-A methods to any user unless that user is the ow= ner of the object being accessed. This sample policy primarily exists to sh= ow how to create a policy that compares the owner-id of an object to the lo= gin-id of the current user. It is important to note that due to how XACML p= olicies are processed, you cannot do this comparison in th= e <Subject> section of the XACML policy. The comparison must appear i= n a <Condition> specification in the <Rule> section. |
Policy | Service | XACML Policy File | Policy Description |
4.2.1 | API-A | deny-objects-by-= pids-to-tomcat-role.xml | Overall, this policy will identify a set of objects by their PIDs and i= t will DENY ALL APIA access to users of particular ROLES. NOTE: As a reposi= tory-wide policy, this policy demonstrates how to control access to specifi= c objects (identified by PID). As an alternative, it is possible to create = "object-specific" policies that either resides in the digital object's POLI= CY datastream, or that is stored in the object-specific policy directory. (= See the Fedora system documentation on XACML policies for more information.= ) |
4.2.2 | API-A | deny-objects-by= -cmodel-to-ldap-group.xml | This policy will DENY all APIA access to digital objects that are EAD F= inding AIDS. This is based on the object content model attribute having a v= alue of "UVA_EAD_FINDING_AID." Specifically, the policy will DENY access to= users that belong to a particular LDAP-defined GROUP. |
4.2.3 | API-A | deny-objects-hide-datastreams-if-not-tomcat-role.xml | The overall intent of this policy is datastream hiding, meaning that ra= w datastreams must not be accessible to anyone except very privileged users= , but service-mediated disseminations are accessible by a broader audience.= The key point is that students can access disseminations of the object, bu= t not the raw datastreams. This might typically be done in cases where less= er privileged users are given a derivation of the main datastream, or a les= ser quality view, or a less complete view of the raw datastream content. Gi= ven that an object is of a certain content model (in this case UVA_STD_IMAG= E), this policy will DENY datastream access to users who do NOT have the RO= LE of "administrator" or "professor". It will also DENY dissemination acces= s to users who do NOT have the ROLE of "student," "administrator," or "prof= essor." |
Policy | Service | XACML Policy File | Policy Description |
4.3.1 | API-A | deny-apia-d= atastream-all-to-all-users.xml | This policy will DENY access to ALL datastreams. Specifically, it will = DENY access to ALL USERS making requests to the getDatastreamDissemination = method of API-A. |
4.3.2 | API-A | deny-apia-datas= tream-DC-to-all-users.xml | This policy will DENY access to Dublin Core datastreams. Specifically, = it will DENY access to ALL users making getDatastreamDissemination requests= on API-A to obtain datastreams with an identifier of 'DC.' |
4.3.3 | API-A | deny-apia-datastream-DC-to-tomcat-group-ALT1.xml | This policy will DENY access to Dublin Core datastreams. Specifically, = it will deny access to USER GROUPS making getDatastreamDissemination reques= ts on API-A for datastreams with a datastream identifier of 'DC.' User grou= ps are defined using custom roles in the tomcat-users.xml file. |
4.3.4 | API-A | deny-apia-datastream-DC-to-tomcat-group-ALT2.xml | This policy will DENY access to Dublin Core datastreams. Specifically, = it will deny access to USER GROUPS making getDatastreamDissemination reques= ts on API-A for datastreams with a datastream identifier of 'DC.' User grou= ps are defined using custom roles in the tomcat-users.xml file. |
4.3.5 | API-A | deny-apia-datastream-MRSID-if-not-tomcat-role.xml| | This policy will DENY access to MRSID image datastreams by controlling = access to the getDatastreamDissemination method of the Fedora Access Servic= e (API-A). Specifically, it will DENY access to users who are NOT of partic= ular ROLES when the requested resource is a datastream with identifier of '= MRSID.' |
4.3.6 | API-A | deny-apia-datastream-TEISOURCE-to-tomcat-user.xml| | This policy will DENY access to TEI datastreams by controlling access t= o the getDatastreamDissemination method of the Fedora Access Service (API-A= ). The TEI datastream is identified as a Resource where the Fedora datastre= am id has the value of 'TEISOURCE.' This policy will DENY access to a SPECI= FIC USER based on login id (as registered in the tomcat-users.xml file). |
Policy | Service | XACML Policy File | Policy Description |
4.4.1 | API-A | deny-apia-dissem-demo1-getMedium-to-all-users.xml | This policy will DENY access to the 'demo:1/getMedium' dissemination (d= efined on a disseminator that subscribes to the demo:1 behavior definition.= Specifically, it will DENY access to ALL users making getDissemination req= uests on API-A for the 'demo:1/getMedium' dissemination. |
4.4.2 | API-A | deny-apia-dissem-demo1-getMedium-to-ldap-group.xml | This policy will DENY access to the 'demo:1/getMedium' dissemination (d= efined on a disseminator that subscribes to the demo:1 behavior definition.= Specifically, it will DENY access to users of particular LDAP-defined GROU= PS who are making getDissemination requests on API-A for the 'demo:1/getMed= ium' dissemination. |
4.4.3 | API-A | deny-apia-dissem-demo1-getMedium-if-not-tomcat-role.xml<= /td> | This policy will DENY access to the 'demo:1/getMedium' dissemination (d= efined on a disseminator that subscribes to the demo:1 behavior definition.= Specifically, it will DENY access to users who are NOT of particular ROLES= who are making getDissemination requests on API-A for the 'demo:1/getMediu= m' dissemination. |
4.4.4 | API-A | deny-apia-dissem-demo1-getMedium-to-tomcat-user.xml | This policy will DENY access to disseminations that are available on ob= jects via a disseminator subscribing to the 'demo:2' behavior definition. S= pecifically, it will DENY access to a particular user (as registered in the= tomcat-users.xml file). |
4.4.5 | API-A | de= ny-apia-dissem-DualResImage-to-all-users.xml | This policy will DENY access to ALL disseminations that are available o= n objects via a particular disseminator (one that subscribes to an image-ba= sed behavior definition whose PID is 'demo:DualResImage'. Specifically, it = will DENY access to ALL users making getDissemination requests on this diss= eminator. |
Policy | Service | XACML Policy File | Policy Description |
4.5.1 | API-M | permit-apim-by-ldap-group.xml | |
4.5.2 | API-M | permit-apim-by-tomcat-group.xml= a> | |
4.5.3 | API-M | permit-apim-by-tomcat-user.xml<= /td> | |
4.5.4 | API-A/API-M | permit-if-owner.xml | If the logged-in user is the owner of an object, permit all actions. No= te: This policy also works if the object has multiple owners and the logged-in user is one of them. |
Object-specific policies are policies that refer to one particular digit= al object. An object-specific policy is stored in the "POLICY" datastream o= f the digital object to which it pertains.
Policy | Service | XACML Policy File | Policy Description |
5.1.1 | N/A | = demo-5.xml | By using multiple policy rules, this policy s= hows how to deny access to all raw datastreams in the object except to part= icular users (e.g., the object owners). It also shows how to deny access to= a particular disseminations to selected user roles. |
5.1.2 | N/A | demo-11.xml | By using multiple policy rules, this policy s= hows how to deny access to particular datastreams in the object. 1) The pol= icy will DENY everyone except professors and researchers access to particular source datastreams= of the demo:11 object by controlling access to the getDatastreamDisseminat= ion method of the Fedora Access Service (API-A). 2) The policy will DENY ev= eryone except students, professors, and researchers, access to all dissemin= ations of demo:11. 3) This policy will also DENY ALL access to the demo:11 = object to a SPECIFIC USER based on login id (as registered in the tomcat-us= ers.xml file). NOTE: The net effect of the policy permits open access to th= e descriptive metadata datastream of demo:11. |
5.1.3 | N/A | demo-26.xml | By using multiple policy rules, this policy s= hows how to deny access to particular datastreams in the object. The policy= will DENY visitors access to the TEI and FOP source datastreams of the dem= o:26 object by controlling access to the getDatastreamDissemination method = of the Fedora Access Service (API-A). These datastreams are open to all oth= er kinds of users, and Disseminations are open to all users. This is an obj= ect-specific policy. It could be stored inside the demo:26 digital object i= n the POLICY datastream OR in the directory for object-specific policies. (= The directory location is set in the Authorization module configuration in = the Fedora server configuration file (fedora.fcfg). |