Admin/accessControl

From Omar Wiki

Jump to: navigation, search

This page provides tip and tricks for writing custom Custom Access Control Policies in XACML for freebXML Registry. More details will be added over time.

Contents

[edit]

Enabling Custom Access Control Feature

The custom access control feature is disabled by default as it adds extra processing. To enable it do edit the following properties in conf/omar.properties and then run the "deploy" ant target to deploy server with these properties enabled. Remember to shutdown and restart the Tomcat server after running the deploy target: 

 omar.security.authorization.assumeCanonicalObjectsUseDefaultACP=false
 omar.security.authorization.customAccessControlPoliciesEnabled=true
 omar.security.authorization.enableOverride.permitAllRead=false
[edit]

XACML Concepts

[edit]

Element <PolicySet>

  • A <PolicySet> element is the highest level object

A <PolicySet> element contains:

  • A <Target> element
    • Allows quick determination of whether the <PolicySet> is applicable or not.
  • One or more <Policy> sub-elements elements

Contained or referenced by its id within a <PolicySet> element 

* Should be reused in multiple <PolicySet> elements whenever possible.

A <Policy> element may contain:

  • A <Target> element
    • Allows quick determination of whether the <Policy> is applicable or not.
  • One or more <Rule> sub-elements elements
    • Evaluated only if <Target> element indicates the <Policy> is applicable
[edit]

Element <Rule>

  • Contained or referenced by its id within a <Policy> element
  • Should be reused in multiple <Policy> elements whenever possible.

A <Rule> element may contain:

  • A <Target> element
    • Allows quick determination of whether the <Rule> is applicable or not.
  • One or more <Condition> sub-elements elements
    • Evaluated only if <Target> element indicates the <Rule> is applicable
[edit]

Element <Target>

  • May be used in <PolicySet>, <Policy> or <Rule>
  • Enables highest level place to check if the PolicySet, Policy or Rule applies
  • May contain one of Subjects, Resources and Actions elements to filter on the attributes of the Subject, Resource or Action
[edit]

Element <Actions>, <Resources> or <Subjects>

This section uses <Actions> as an example but same concepts apply to <Subjects> and <Resources>. Simply substitute "Resource" or Subject in place of "Action" below:

  • An <Actions> Element may have one of the following sub-elements:
    • An <AnySubject/> element: This is less desirable. Implies that there is no Subject applicability check at this level.
    • One or more <Action> elements: This is more desirable at the highest levels (<PolicySet>, <Policy> or <Rule> in that order) when possible over <AnySubject/> sub-element.
      • Multiple <Action> elements in an <Actions> element imply a logical OR, meaning that policy is applicable if the action matches any one of the actions specified by the multiple <Action> elements in an <Action> element.
[edit]

Element <Action>, <Resource> or <Subject>

This section uses <Action> as an example but same concepts apply to <Subject> and <Resource>. Simply substitute "Resource" or Subject in place of "Action" below:

  • An <Action> element may contain one or more <ActionMatch> elements
    • Multiple <ActionMatch> elements in an <Action> element imply a logical AND, meaning that policy is applicable only if the actions matches all of the actions specified in the multiple <ActionMatch> elements. Notice the diffrence with multiple <Action> elements in an <Action> element which imply a logical OR.
[edit]
Element <ActionMatch>, <ResourceMatch> or <SubjectMatch>

This section uses <ActionMatch> as an example but same concepts apply to <SubjectMatch> and <ResourceMatch>. Simply substitute "Resource" or Subject in place of "Action" below:

  • Attribute MatchId identifies a boolean function that takes two values specified by The <ActionAttributeDesignator> and <AttributeValue> sub-elements of <ActionMatch>
  • Element <ActionAttributeDesignator> identifies an action attribute whose value is being matched by <ActionMatch>
    • May need only-one function if value returned by match function is a bag.
  • Element <AttributeValue> identifies the value of an action attribute that is being matched by <ActionMatch>
[edit]

Element <Condition>

Use a <Condition> in the following situations:

  • When a non-boolean function is needed. Targets only allow boolean functions in comparision.
  • When you need to use functions that return bags (sets) and need to do intersection operation across multiple sets.
  • When you need to specify a join condition across Subject, Resource and Action attributes
[edit]

Designing New XACML Policies

  • Use an existing example in <omar>/misc/samples/acp
  • A recent example is here
  • You can reference some Policies in the default ACP of omar using <PolicyIdReference> as follows: 
 <PolicyIdReference>urn:oasis:names:tc:ebxml-regrep:3.0:rim:acp:policy:policyid:permit-registryadministrator-all</PolicyIdReference>
 <PolicyIdReference>urn:oasis:names:tc:ebxml-regrep:3.0:rim:acp:policy:policyid:permit-anyone-to-read</PolicyIdReference>
 <PolicyIdReference>urn:oasis:names:tc:ebxml-regrep:3.0:rim:acp:policy:policyid:permit-anyone-to-reference</PolicyIdReference>
  • Make your PolicySetId be same as the id of the ExtrinsicObject for that POlicySet file.
  • Give <Description> to your elements wherever allowed. This will help when we provide policy editing tools in future.
  • Place such referecnes at the end of the new policy because whendebugging you will nothave to wade thru evaluation of these policies which are likely to not be buggy.
  • Careful specifying important identifiers to avoid typos. TRypos can ruin your whole day. Use cut/paste from known good policies:
[edit]

Debugging XACML Policies

Debugging XACML Policies and why they are not working as expected can be challenging and time consuming. Here are some tips to help ease the pain:

  • Make sure that your XACML instance document is valid compared with the XACML 1.0 XML Schema. This small thing can save you many many hours of excruciating pain. I simply open the XACML POlicy file in NetBeans IDE and use right click ACTION in Editor window and choose "Validate XML".

If your action is being denied by your custom ACP it is not always easy figuring out why that happening. Here are some tips that follow:

  • Make your custom ACP minimal by commenting out all parts (PolicyIdReference, Policy, Rule) that are clearly not applicable to the decision. This simplies debugging by reducing the policy decision steps that need to be carefully debugged. Another optionis to move such clearly non-applicable elements later than the sibling elements that are likely source of the problem.
  • Checkout sunxacml code from CVS using tag that matches version used by omar. Currently tag is: release_1_1 
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/sunxacml login 
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/sunxacml co -P -r <tag> sunxacml
  • Use a debugger like NetBeans IDE and debug registry code as it flows thru sunxacml code.
  • Common methods to set debugger break points:
    • com.sun.xacml.Target#match: Deteremine which if any of the Target children (Subjects, Resources, Actions) are failing to match when they should or matching when they should not.
    • com.sun.xacml.attr.AttributeDesignator#evaluate: Determine which AttributeDesignator is failing to match when they should or matching when they should not, causing Target child (Subjects, Resources, Actions) to fail
    • com.sun.xacml.TargetMatch#match: ??
[edit]

Debugging XACML Policies: Log Alternative

Another way to get some debug info out of sunxacml 1.1 is to use the version available here, patched by Digital Artefacts. Jar and sources available. This version adds commons-logging support (partial, not everywhere!) to original sunxacml.

For instance, if you use Log4J, replace sunxacml.jar with the patched jar and add this to log4j.properties: 

log4j.logger.com.sun.xacml=debug
log4j.logger.com.sun.xacml.cond=error

Be warned: you'll get a lot of debug information.

[edit]

Creating Access Control Policies

  • Use a text editor or an XACML Editor such as <http://xacml.dif.um.es/> and create XACML ACP
  • Add new ACP as an ExtrinsicObject of type XACML PolicySet to registry using Web/Java UI
[edit]

Assigning Custom Access Control Policies to All Instances of a Class

  • Associate new ExtrinsicObject for XACML PolicySet with a ClassificationNode that is a descendant of the ccanonical ObjectType ClassificationScheme, using Web/Java UI with following Association attributes:
    • associationType="urn:oasis:names:tc:ebxml-regrep:AssociationType:AccessControlPolicyFor"
    • sourceObject=<id of ExtrinsicObject of type XACML PolicySet>
    • targetObject=<id of ObjectType ClassificationNode representing the RIM class >
[edit]

Assigning Custom Access Control Policies to Specific RegistryObjects

The previous section defines the more common use case where a policy is assigned to an entire class of RIM objects. Sometimes it is necessary to define instance specific policies. This use case is described here. Note that instance specific policies override any Class specific policies.

  • Associate new ExtrinsicObject for XACML PolicySet with a RegistryObject using Web/Java UI with following Association attributes:
    • associationType="urn:oasis:names:tc:ebxml-regrep:AssociationType:AccessControlPolicyFor"
    • sourceObject=<id of ExtrinsicObject of type XACML PolicySet>
    • targetObject=<id of RegistryObject that wishes to use the custom XACML PolicySet>
[edit]

Replacing the Default Access Control Policy

The default ACP may not be appropriate for every registry design. Follow these steps to replace it with your own custom ACP:

  • Add an appropriate ACP to the registry
  • Edit the conf/omar.properties file and find the property that looks like this: 
#
# The id of default access control policy file
#
omar.security.authorization.defaultACP=urn:oasis:names:tc:ebxml-regrep:acp:defaultACP
  • Comment out the property and override it with the id of your own ACP
  • Redeploy omar and bounce the server

It is important not to simply submit a new RepositoryItem for the defaultACP object because if an error in your custom default ACP causes the registry to become unusable you can revert back to the defaultACP by editing conf/omar.properties again.

[edit]

Administering Roles, Groups and Users

Custom access control policies may define policies based upon the roles a users is assigned and the groups the user may be assigned to. New Roles and Groups may be created and assigned to Users. This however, is a privileged operation that MUST be performed by a User that has a RegistryAdministrator role.

[edit]

Creating the First RegistryAdministrator

Since a user needs to be RegistryAdministrator to create new roles and groups or to assign them to users, we need a special way to assign the RegistryAdministrator role to the first user that needs this role. This is done as follows:

  • In Java UI or Web UI find teh User object for the user that needs to be assigned RegistryAdministrator role
  • Edit the details of the User object and copy its Unique Id into the copy buffer (or a piece of paper)
  • Edit the conf/omar.properties file in any text editor
  • Find the property that looks like: 
#
# Specifies the ids of Users that have role of RegistryAdministrators
# Add additional users by separating with '|' symbol with no intervening spaces as shown below 
#
omar.security.authorization.registryAdministrators=urn:freebxml:registry:predefinedusers:registryoperator
  • Add the '|' symbol at the end of the existing property value with no intervening spaces
  • Add the id of the user being assigne the RegistryAdministrator role after the '|' symbol with leading or traiing intervening spaces
  • Save the conf/omar.properties file
  • Redeploy omar and bounce the server using: build.sh deploy.restart (build.bat for windows)
  • The new user should now have the RegistryAdministrator role assigned
  • You can now use this user to assigne roles and groups to other users
[edit]

Creating, Updating and Deleting Roles and Groups

Creating, updating or deleting of roles and groups to users is a privileged operation and MUST be performed by a User that has a RegistryAdministrator role. A User with RegistryAdministrator role may assign roles and groups to users as follows:

  • Login to Java UI or Web UI as a user that already has a RegistryAdministrator role
  • Roles are defined using the SubjectRole ClassificationScheme
  • Groups are defined using the SubjectGroup ClassificationScheme
  • To add a new role/group, add a ClassificationNode under the SubjectRole/SubjectGroup ClassificationScheme and save it
    • In Java UI this is done in the ClassificationSchemes Dialog (from toolbar). Right-click on SubjectRole/SubjectGroup scheme in the dialog and choose "Insert" action and provide details in the dialog for the new SubjectRole/SubjectGroup ClassificationNode.
  • To delete an existing role/group, delete the corresponding ClassificationNode under the SubjectRole/SubjectGroup ClassificationScheme
    • In Java UI this is done in the ClassificationSchemes Dialog (from toolbar). Right-click on SubjectRole/SubjectGroup scheme in the dialog and choose "Delete" action
  • To update an existing role/group, edit/update the corresponding ClassificationNode under the SubjectRole/SubjectGroup ClassificationScheme and save it
    • In Java UI this is done in the ClassificationSchemes Dialog (from toolbar). Right-click on SubjectRole/SubjectGroup scheme in the dialog and choose "Edit" action
[edit]

Assigning Roles To Users and User to Groups

Assigning roles and groups to users is a privileged operation and MUST be performed by a User that has a RegistryAdministrator role. A User with RegistryAdministrator role may assign roles and groups to users as follows:

  • Roles are assigned to a user by classifying their User object with a ClassificationNode in the SubjectRole ClassificationScheme.
  • Users are assigned to groups by classifying their User object with a ClassificationNode in the SubjectGroup ClassificationScheme.
  • Web UI or Java UI may be used to add Classification objects to a User object for roles and groups in a manner similar to any other Classification.
[edit]

Access Control Policy Tips

  • Registry Guest must have read access in order for the HTTP interface to work.
  • The Web UI can cope with Registry Guest not having read access, but the Java UI cannot.
  • Any new subject needs create access for objects of the canonical User object type in order for new user registration to work.
  • Any new subject needs reference access for the canonical User ClassificationNode in order for new user registration to work.
[edit]

How Do I Do XXX: Typical Problems and their Solution

Please add questions as first level bullet here and answers as second level bullets under the question.

  • Q: Place first question here
    • Place first answer here
Retrieved from "http://ebxmlrr.sourceforge.net/wiki/index.php/Admin/accessControl"