Author: sohil.shah(a)jboss.com Date: 2009-08-24 09:56:27 -0400 (Mon, 24 Aug 2009) New Revision: 13785 Added: modules/authorization/trunk/documentation/authz-component-spec.braindump modules/authorization/trunk/documentation/dev-api.braindump modules/authorization/trunk/documentation/reference-guide/en/modules/framework.xml Removed: modules/authorization/trunk/documentation/reference-guide/en/modules/api.xml Modified: modules/authorization/trunk/documentation/reference-guide/en/master.xml Log: some docs backup * note: delete the .braindump files once incorporated into organized docbook modules Added: modules/authorization/trunk/documentation/authz-component-spec.braindump =================================================================== --- modules/authorization/trunk/documentation/authz-component-spec.braindump (rev 0) +++ modules/authorization/trunk/documentation/authz-component-spec.braindump 2009-08-24 13:56:27 UTC (rev 13785) @@ -0,0 +1,57 @@ +"Authorization Component" spec represents the "contract" between the various domain oriented security components and the framework. The framework +processes these components during both the Authorization phases. During the Enforcement Phase, these components are translated into "facts" that +Rule Engine bases its access decision upon. In the Provisioning Phase, the framework processes these components to produce the "facts" and "expressions" +that will make up the new policy. + + +Here are the rules that an "Authorization component" must meet in order to be properly processed by the framework. + +* The component are simple java beans or POJOs. +* They must have an empty constructor +* The fields that represent the "facts" must have corresponding accessors (getters and setters) +* The various members of the component must be appropriately annotated to provide meta data information for the framework. The Annotations are covered +in greater detail a little later in this chapter + + +Annotations + +Component: A "Type" level component used to indicate that an instance of the annotated class must be treated as an "Authorization Component" +by the framework. + name: represents the unique name of the component + type: represents whether the component represents the "Target" aspect or the "Logic" aspect of the Policy + category: represents what kind of data it represents. There are 4 main categories that "facts" can belong to: + Resource: what resource am I trying to access? + Subject: who am I? + Action: what action/operation am I trying to perform upon the Resource + Environment: what other interesting facts can I provide such as "current date", "client ip address", "portlet preferences", etc + + +ComponentType: + +ComponentCategory: + +SecurityContextData: + +LogicExpression: + +ImpliedActions: + +Core Components: + + Identity: + + Roles: + + URIResource: + + Read: + + Write: + + Manage: + +More to Come based on the XACML Spec scenarios: + + + + \ No newline at end of file Added: modules/authorization/trunk/documentation/dev-api.braindump =================================================================== --- modules/authorization/trunk/documentation/dev-api.braindump (rev 0) +++ modules/authorization/trunk/documentation/dev-api.braindump 2009-08-24 13:56:27 UTC (rev 13785) @@ -0,0 +1,143 @@ +The Authorization Framework relies on a Rule based approach for enforcing access control. A rule engine matches the current Enforcement State of the application +against the various Policies stored in the Policy Store. A matching policy is found based on "facts" presented within the incoming Enforcmenet State. +Once a Policy match is found, all the Rules associated with this Policy are evaluated against the "facts" presented by the Enforcement State. +Each Policy Rule consists of a Pattern Matching component and an optional Conditional component that evaluates a boolean expression against the incoming +"facts". A Rule results in a "Permit" or "Deny" assertion and a Policy Combining Algorithm processes these assertions to make a "Yes", or "No" +decision. + + + +A Policy forms the central concept of this framework. A Policy is composed of the following components: + +* One Target - A Policy Target component consists of "facts" to once matched appropriately with the "facts" included with the incoming Enforcement Request, +qualifies that particular Policy instance for evaluation inside the Rule Engine + +* One or More Rules - Each Rule inside a Policy is evaluated against the "facts" of the incoming Enforcement Request. A Rule execution results in a "Permit" +or "Deny" state. A Rule itself is composed of multiple components. + +* One Rule Target - A Rule is selected for execution if the "facts" represented within its Target component match the "facts" within the incoming request. + +* One (optional) Conditional Expression - If a Rule contains a Conditional Expression, it is evaluated for a boolean result against the "facts" within the +incoming request. If the result is "true", then the appropriate Rule Effect "Permit" or "Deny" becomes the state of this Rule evaludation + + +A typical Authorization system operates in two phases. + +* Enforcement - This is where Access Control is enforced during application request execution. + +* Provisioning - This is where Security Policies are administered in the system. +This is done via tools like GUI based Admin tool, a command line tool, or xml based configuration tool etc. It uses the Provisioning API of the framework + + +Enforcement + +* Enforcement is the cross cutting concern of the application and injected into the application request life cycle as a system service + +* Enforcement Interceptor – This is the component that intercepts incoming request for access control evaluation. +The term Interceptor needs clarification. I use the term Interceptor in a logical sense, and not in low level technical terms. +What that means that interceptor does not mean it has to be an AOP interceptor only. +What component performs the interception is at the discretion of the Application Developer/System Integrator. +Some examples of interceptors could be: + +* In the Http Layer it could be a Servlet Filter or a Tomcat Valve + +* In the Portal Layer it could actually be an AOP based Interceptor + +* In the Portlet Layer it could be a Portlet Filter + +* In the Seam Layer it could be a Phase Listener + +EnforcementContext – This consists of runtime application state populated by the Enforcement Interceptor against which Policy Rules are evaluated. +This state is arbitrary and depends upon what data is useful in coming up with an access control decision. EnforcementContext answers the ”This is what I am trying to access, and this is my current application state”. It has no knowledge of the logic that will be applied to this data or cares for it. Objects placed into an EnforcementContext are understood as ”Security Components”. These components are basically Annotated POJOs that the framework can understand and process against the Rule Engine. +More about the ”Security Component” specification is discussed later. + +The framework provides an extensive set of core ”Security Components”. The core Component Set is extensive and tries to cover the concepts covered by the industry standard xacml specification. +More custom Components can also be created based on the ”Security Component” specification. + +An incoming request is intercepted before invoking a protected resource, an EnforcementContext consisting of runtime state of the system is populated, +and and Enforcement Request is issued to the framework + +The framework then processes this Request through its Rule Engine and stored Policies to come up with a yes or no decision + +If access is granted, the request moves forward, if not, appropriate action is taken by the application + + +Provisioning + +CompositionContext – The CompositionContext allows the Developer to specify the Policy Structure for the Policy using ”Security Components”, +just like the EnforcementContext. + +This Policy Structure is then handed over to a PolicyComposer by the framework which then auto generates the system policy (an xacml policy) +including all the conditional logic that must be used within the Policy Rules. As a Developer trying to provision a policy your +main concern is to populate the state of the ”Security Component” based on your Security Requirements. +Rule Generation including conditional logic expressions is automatically handled by the PolicyComposer component of the framework + +The Developer is never exposed to any low-level xacml/xml mess. In fact, we picked xacml which is an industry spec, and a supported +JBoss Security component. This can be completely replaced with a custom Rule Engine with proprietary Policy Language, +and the Application would never be affected. + +Once the Policy is provisioned it is then managed by the framework and used during incoming Enforcement Requests. + +All provisioning is dynamic as in, when the Policy Repository is updated, the changes go into effect immediately without requiring any server/application restart + + +Development Process + +The original goal of the Authorization Framework was to eliminate all authorization related logic from the core application and/or infrastructure code. +The idea was to make Authorization a purely cross cutting concern for applications. + +With this goal in mind, development using the Authorization Framework fell into three stages + +* Core Application/Infrastructure Development: This is where the developers develop their applications without any concern of embedding any security checking +logic inside their implementation. Basically, think of it as developing an application that does not have any security functionality + +* Enforcement Layer: This is the cross cutting layer of the application that introduces authorization functionality to an otherwise authorization agnostic +application. This layer makes the "Enforcement Phase" possible. + +* Provisioning Layer: This is the provisioning aspect of authorization. This layer provides policy management capabilities associated with the functional +requirements of the application being developed. + +As a user of the Authorization Framework, the developer is concerned with the Enforcement Layer and Provisioning Layer development + + + +Enforcement Layer Development Steps + +* Depending upon the architecture of your application, identify the interception points and interceptor type when Enforcement Calls can be plugged in. +For instance, if you are trying to protect the application at the Http Layer, you can used a Servlet Filter based Enforcement Layer +In case of a POJO Service layer, you could possibly use an AOP based approach + +* Based on the "facts" and "rules" used inside the Policy Structure decide what "facts" about your application will be used to populate the Enforcement +Request. This is what I would loosely qualify as the contract between the Enforcement Phase and the Provisioning Phase, and is driven by the authorization +requirements of the application + +* Select the Authorization "components" that will be used to represent these facts. You can pick from the set of core components that come packaged out of +the box with the framework itself. If the set of core components are not enough for your requirements, then you can develop custom components +that adhere to the "Authorization Component Spec". + +* Populate the EnforcementContext with Authorization Components for Access Control checks + + +Provisioning Layer Development Steps + +* Depending upon the authorization requirements of the application, select the "Authorization Components" to be used to provision the corresponding Policies + +* Populate the Composition Context with these components. + +* Policy Composer takes care of the rest related to generating the appropriate Policy. It generates all the "Targets", "Rules", and "Conditional Expressions" +to be associated with the Policy + + +Some Development Observations + +* As a Developer, in both authorization phases, when dealing with "Authorization Components", you are more concerned with populating the "state" of the +components which is represented as "facts" inside the Rule Engine + +* You are not concerned as much about low level details of Policy Composition and Policy Structure. That is taken care of by the Policy Composer + +* The "Authorization Components" in a way enforce the "contract" between the Enforcement and Provisioning phases. The same components are involved to ensure +appropriate "facts" and "rules" are represented within the Policy and then while doing security checks + +Simple Enforcement Phase Example + +Simple Provisioning Example \ No newline at end of file Modified: modules/authorization/trunk/documentation/reference-guide/en/master.xml =================================================================== --- modules/authorization/trunk/documentation/reference-guide/en/master.xml 2009-08-24 02:03:05 UTC (rev 13784) +++ modules/authorization/trunk/documentation/reference-guide/en/master.xml 2009-08-24 13:56:27 UTC (rev 13785) @@ -16,7 +16,7 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/introduction.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/concepts.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/architecture.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/api.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/framework.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/profiles.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/spi.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/examples.xml" /> Deleted: modules/authorization/trunk/documentation/reference-guide/en/modules/api.xml =================================================================== --- modules/authorization/trunk/documentation/reference-guide/en/modules/api.xml 2009-08-24 02:03:05 UTC (rev 13784) +++ modules/authorization/trunk/documentation/reference-guide/en/modules/api.xml 2009-08-24 13:56:27 UTC (rev 13785) @@ -1,16 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="api"> - <chapterinfo> - <author> - <firstname>Sohil</firstname> - <surname>Shah</surname> - <email&gt;sshah(a)redhat.com&lt;/email&gt; - </author> - </chapterinfo> - <title>Developer API</title> - <sect1> - <title>Developer API</title> - <para> - </para> - </sect1> -</chapter> Copied: modules/authorization/trunk/documentation/reference-guide/en/modules/framework.xml (from rev 13731, modules/authorization/trunk/documentation/reference-guide/en/modules/api.xml) =================================================================== --- modules/authorization/trunk/documentation/reference-guide/en/modules/framework.xml (rev 0) +++ modules/authorization/trunk/documentation/reference-guide/en/modules/framework.xml 2009-08-24 13:56:27 UTC (rev 13785) @@ -0,0 +1,145 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="framework"> + <chapterinfo> + <author> + <firstname>Sohil</firstname> + <surname>Shah</surname> + <email&gt;sshah(a)redhat.com&lt;/email&gt; + </author> + </chapterinfo> + <title>Framework</title> + <sect1> + <title>Developer API</title> + <para> + The <emphasis>Authorization Framework</emphasis> consists of a <emphasis role="bold">component-oriented Developer API</emphasis>. + The API is used to integrate an Authorization layer for your application. + This allows your Application components to be free from any embedded Security Logic. + The Framework itself provides a number of useful <emphasis>reusable</emphasis> components. + These components can be used by application developers to create custom Authorization layers, and/or by infrastructure developers + to develop Profiles for their respective tier. + The components adhere to what we call the "Authorization Component" spec, to be covered in more detail in the next chapter. + </para> + </sect1> + <sect1> + <title>Rule based Framework</title> + <para> + The Authorization Framework relies on a Rule based approach for enforcing access control. A Rule Engine matches the incoming enforcement request + against the various policies stored in the Policy Store. A matching policy is found based on "facts" presented within the request. + Once a Policy match is found, all the Rules associated with this Policy are evaluated to reach a "Permit" or "Deny" state. + </para> + <sect2> + <title>Policy</title> + <para> + A Policy forms the central concept of this framework. A Policy is composed of the following components: + <itemizedlist> + <listitem><emphasis role="bold">One</emphasis> Target : + A policy-level <emphasis>Target</emphasis> component consists of <emphasis role="bold">"facts"</emphasis> to be matched + appropriately with the <emphasis role="bold">"facts"</emphasis> included with the incoming enforcement request. + This <emphasis role="bold">"fact-matching"</emphasis> selects a policy instance for evaluation inside the Rule Engine. + </listitem> + <listitem><emphasis role="bold">One or More</emphasis> Rules : Each <emphasis>Rule</emphasis> inside a policy is evaluated + against the <emphasis role="bold">"facts"</emphasis> presented by the incoming enforcement request. + A <emphasis>Rule</emphasis> execution results in a <emphasis role="bold">"Permit"</emphasis> + or <emphasis role="bold">"Deny"</emphasis> state. A <emphasis>Rule</emphasis> itself is composed of a <emphasis>Target</emphasis> and a <emphasis>Conditional Expression</emphasis>. + </listitem> + <listitem> + <emphasis role="bold">One</emphasis> rule-level Target - A <emphasis>Rule</emphasis> is selected for execution if the + <emphasis role="bold">"facts"</emphasis> represented within its Target component match the <emphasis role="bold">"facts"</emphasis> + within the incoming request. + </listitem> + <listitem> + <emphasis role="bold">One (optional)</emphasis> Conditional Expression - If a <emphasis>Rule</emphasis> contains an optional + <emphasis>Conditional Expression</emphasis>, it is evaluated for a boolean result against the <emphasis role="bold">"facts"</emphasis> + within the incoming request. + If the result is <emphasis role="bold">"true"</emphasis>, then the appropriate <emphasis>Effect</emphasis> + <emphasis role="bold">"Permit"</emphasis> or <emphasis role="bold">"Deny"</emphasis> becomes the state of this Rule evaluation. + </listitem> + </itemizedlist> + </para> + <para> + A simple Policy that <emphasis>Permit</emphasis> or <emphasis>Denies</emphasis> a particular <emphasis>Identity</emphasis> + from making a <emphasis role="bold">GET</emphasis> HTTP Request on <emphasis>/intranet/index.html</emphasis> resource + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8" standalone="yes"?> +<Policy xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" RuleCombiningAlgId="rule-combining-alg:nopermit-means-denied" Version="2.0" PolicyId="testGetURLTargetWithParameters"> + <!-- Policy-Level Target Component --> + <Target> + <Resources> + <Resource> + <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> + <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">/intranet... + <ResourceAttributeDesignator MustBePresent="true" DataType="http://www.w3.org/2001/XMLSchema#string" AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id"/> + </ResourceMatch> + </Resource> + </Resources> + </Target> + <Rule Effect="Permit" RuleId="8b167dd5-78c5-4c5a-b744-db376927211d"> + <!-- Rule-Level Target Component --> + <Rule Effect="Permit" RuleId="b72cd78d-b76c-4efb-8e6b-5daa1d417567"> + <Target> + <Actions> + <Action> + <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> + <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">get</A... + <ActionAttributeDesignator MustBePresent="true" DataType="http://www.w3.org/2001/XMLSchema#string" AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"/> + </ActionMatch> + </Action> + </Actions> + </Target> + <!-- An optional Conditional Expression. This particular expression points to a Drools expression --> + <Condition> + <Apply FunctionId="urn:oasis:names:tc:xacml:2.0:function:jboss-drools:rule"> + <VariableReference VariableId="roles://allowRule/856e41d7-9f4b-4c03-bc1a-c58d0a683786"/> + </Apply> + </Condition> + </Rule> +</Policy> + ]]> + </programlisting> + </para> + <para>Note: This is just to show what a Policy looks like. A Developer using this framework will never have to deal with this low-level XACML-based xml representation. + The Policies are composed, generated, and managed automatically by the framework itself. + </para> + </sect2> + </sect1> + <sect1> + <title>Authorization Phases</title> + <para> + A typical Authorization system operates in two phases + <itemizedlist> + <listitem> + <emphasis role="bold">Enforcement</emphasis>: This is where access control is enforced during application request execution. + </listitem> + <listitem> + <emphasis role="bold">Provisioning</emphasis>: This is where security policies are administered in the system. + This is done via tools like GUI based tools, a command line tool, xml based configuration tool etc. + </listitem> + </itemizedlist> + </para> + <sect2> + <title>Enforcement Phase</title> + <para> + Enforcement is the cross cutting concern of the application and injected into the application request life cycle as a system service. + Enforcement Interceptors intercept incoming application requests for access control evaluation. + The term Interceptor needs clarification. The term Interceptor is used in a logical sense, and not in low level technical sense. + What that means that interceptor does not mean it has to be an AOP interceptor only. + What component performs the interception is at the discretion of the Application Developer/System Integrator. + Some examples of interceptors could be: + <itemizedlist> + <listitem>In the Http Layer it could be a Servlet Filter or a Tomcat Valve</listitem> + <listitem>In the Portal Layer it could actually be an AOP based Interceptor</listitem> + <listitem>In the Portlet Layer it could be a Portlet Filter</listitem> + <listitem>In the Seam Layer it could be a Phase Listener</listitem> + </itemizedlist> + </para> + <para> + An <emphasis role="bold">EnforcementContext</emphasis> consists of runtime application state populated by the <emphasis>EnforcementInterceptor</emphasis>. These "facts" contained + inside the <emphasis>EnforcementContext</emphasis> are using during evaulation against security policies. + This state is arbitrary and depends upon what data is useful in coming up with an access control decision. + <emphasis>EnforcementContext</emphasis> answers the ”This is what I am trying to access, and this is my current application state”. + It has no knowledge of the logic that will be applied to this data or cares for it. Objects placed into an <emphasis>EnforcementContext</emphasis> + are understood as ”Authorization Components”. The "Authorization Component" spec will be covered in more details in the next chapter. + </para> + </sect2> + </sect1> +</chapter> Property changes on: modules/authorization/trunk/documentation/reference-guide/en/modules/framework.xml ___________________________________________________________________ Name: svn:mergeinfo +