Author: sohil.shah(a)jboss.com Date: 2009-09-08 14:05:46 -0400 (Tue, 08 Sep 2009) New Revision: 773 Added: authz/trunk/documentation/reference-guide/en/modules/authz-component-spec.xml Removed: authz/trunk/documentation/reference-guide/en/modules/examples.xml authz/trunk/documentation/reference-guide/en/modules/spi.xml authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/LogicData.java authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/TargetUri.java Modified: authz/trunk/documentation/reference-guide/en/master.xml authz/trunk/documentation/reference-guide/en/modules/concepts.xml authz/trunk/documentation/reference-guide/en/modules/framework.xml authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/ComponentCategory.java Log: backing up some documentation Modified: authz/trunk/documentation/reference-guide/en/master.xml =================================================================== --- authz/trunk/documentation/reference-guide/en/master.xml 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/documentation/reference-guide/en/master.xml 2009-09-08 18:05:46 UTC (rev 773) @@ -3,9 +3,9 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <book lang="en"> <bookinfo> - <title>JBoss Authorization Server</title> + <title>JBoss Authorization Service</title> <subtitle>Reference Guide</subtitle> - <releaseinfo>Preview Release</releaseinfo> + <releaseinfo>Alpha Release</releaseinfo> <author> <firstname>Sohil</firstname> <surname>Shah</surname> @@ -13,11 +13,16 @@ </author> </bookinfo> <toc/> - <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/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" /> + <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/samples.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/authz-component-spec.xml"/> + <!-- + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/core-components.xml"/> + --> </book> \ No newline at end of file Added: authz/trunk/documentation/reference-guide/en/modules/authz-component-spec.xml =================================================================== --- authz/trunk/documentation/reference-guide/en/modules/authz-component-spec.xml (rev 0) +++ authz/trunk/documentation/reference-guide/en/modules/authz-component-spec.xml 2009-09-08 18:05:46 UTC (rev 773) @@ -0,0 +1,138 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="authz-component-spec"> + <chapterinfo> + <author> + <firstname>Sohil</firstname> + <surname>Shah</surname> + <email&gt;sshah(a)redhat.com&lt;/email&gt; + </author> + </chapterinfo> + <title>Authz Component Specification</title> + <sect1> + <title>Authz Component Specification</title> + <para> + <emphasis role="bold">Authz Component Specification</emphasis> represents the <emphasis>"contract"</emphasis> between the various + <emphasis>domain-oriented security components</emphasis> and the security framework. The framework + processes these components during both the <emphasis>Authorization phases</emphasis>. + During the <emphasis>Enforcement Phase</emphasis>, these components are translated into <emphasis>"facts"</emphasis> that + the rule engine bases its access decision upon. + During the <emphasis>Provisioning Phase</emphasis>, the framework processes these components to produce the "facts" and "expressions" + that will make up the new <emphasis>system (in our case, xacml) policy</emphasis>. + </para> + <para> + This specification is typically targeted towards low level Infrastructure Developers who <emphasis role="bold">may</emphasis> need + to extend the framework using <emphasis>custom components</emphasis>. The <emphasis>core set</emphasis> of components included with the framework should satisfy 90-95% of security requirements. + As far as the <emphasis>core set</emphasis> of components is concerned, the goal of the framework is to supply functionality that can easily satisfy usecases and goals targeted by the <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xacm... specification</ulink>. + With this in mind, an Application Developer will most likely consume these components instead of writing their own components from scratch. + </para> + <sect2> + <title>Specification Rules</title> + <para> + An "Authz Component" must meet the following rules in order to be processed properly by the framework + <itemizedlist> + <listitem> + The component is a simple <emphasis>POJO (Plain Old Java Object)</emphasis> + </listitem> + <listitem> + It must have an <emphasis>empty public Constructor</emphasis> + </listitem> + <listitem> + The fields that represent the policy <emphasis>"facts"</emphasis> must have corresponding <emphasis>public accessors (getters and setters)</emphasis> + </listitem> + <listitem> + The various members of the component must be appropriately <emphasis>annotated</emphasis> to provide <emphasis>metadata</emphasis> information + for the framework. + The <link linkend="annotations">Annotations</link> are covered in greater detail a little later in this chapter + </listitem> + </itemizedlist> + </para> + </sect2> + </sect1> + <sect1 id="annotations"> + <title>Annotations</title> + <sect2 id="component"> + <title>Component</title> + <para> + <emphasis role="bold">Component</emphasis> is a <emphasis>Type-level</emphasis> annotation used to indicate that instances of the annotated class must be treated + by the framework as an <emphasis role="bold">Authz Component</emphasis>. This annotation has the following elements: + <itemizedlist> + <listitem> + <emphasis role="bold">name :</emphasis> used to represent the <emphasis>unique name</emphasis> of the component + </listitem> + <listitem> + <emphasis role="bold">type: </emphasis> used to represent whether the component represents the <link linkend="componentTypeTarget">Target</link> aspect or + the <link linkend="componentTypeLogic">Logic</link> aspect of the policy + </listitem> + <listitem> + <emphasis role="bold">category: </emphasis> used to represent the kind of data from an authorization perspective. + See <link linkend="componentCategory">ComponentCategory</link> for more details. + </listitem> + </itemizedlist> + </para> + </sect2> + <sect2 id="componentType"> + <title>ComponentType</title> + <para> + <emphasis role="bold">ComponentType</emphasis> indicates <emphasis role="bold">what aspect of the security policy</emphasis> is being represented by the application state + of the component during the Provisioning Phase. + </para> + <para> + It is an enumeration type with the following values: + <itemizedlist> + <listitem id="componentTypeTarget"> + <emphasis role="bold">Target: </emphasis> used to indicate that a component represents the <link linkend="concepts.target">Target</link> aspect of a policy + </listitem> + <listitem id="componentTypeLogic"> + <emphasis role="bold">Logic: </emphasis> used to indicate that a component represents the <link linkend="concepts.rule">Rule</link> aspect of a policy + </listitem> + </itemizedlist> + </para> + <para> + <emphasis role="bold">Note:</emphasis> The <emphasis role="bold">ComponentType</emphasis> meta-data information is used during the <emphasis>Provisioning Phase</emphasis>. + As far as the application developer is concerned, they only need to populate the application state of the component. The low-level details of policy composition/generation, propagation, dynamic deployment, etc is handled + by the framework itself. + </para> + </sect2> + <sect2 id="componentCategory"> + <title>ComponentCategory</title> + <para> + <emphasis role="bold">ComponentCategory</emphasis> indicates <emphasis role="bold">what type of security information</emphasis> is being represented by the application state of the component. + In fancy terms, it represents the semantic information associated with the component during the Enforcement Phase. + </para> + <para> + It is an enumeration type with the following values: + <itemizedlist> + <listitem id="componentCategorySubject"> + <emphasis role="bold">Subject: </emphasis> used to indicate that the component indicates the <link linkend="concepts.subject">Subject</link> who is accessing the system + </listitem> + <listitem id="componentCategoryResource"> + <emphasis role="bold">Resource: </emphasis> used to indicate that the component indicates the <link linkend="concepts.resource">Resource</link> being accessed + </listitem> + <listitem id="componentAction"> + <emphasis role="bold">Action: </emphasis> used to indicate that the component indicates the <link linkend="concepts.action">Action</link> being executed upon the resource + </listitem> + </itemizedlist> + </para> + <para> + As the framework evolves and adds support for more components, this particular entity will evolve correspondingly to indicate the proper semantics of the enforcement request. + </para> + <para> + <emphasis role="bold">Note:</emphasis> The <emphasis role="bold">ComponentCategory</emphasis> meta-data information is used during the <emphasis>Enforcement Phase</emphasis>. + As far as the application developer is concerned, they only need to populate the application state of the component. The low-level details of + policy matching, policy rule evaluation, asserting 'Permit' or 'Deny' state, etc is handled by the framework. + </para> + </sect2> + <sect2 id="securityContextData"> + <title>SecurityContextData</title> + <para> + <emphasis role="bold">SecurityContextData</emphasis> is a <emphasis>Field-level</emphasis> marker Annotation. It is used by a component to indicate + that the application state of the annotated field should be used during both, Enforcement Phase as well as Provisioning Phase of the framework. + </para> + </sect2> + <sect2 id="LogicExpression"> + <title>LogicExpression</title> + <para> + </para> + </sect2> + </sect1> +</chapter> Modified: authz/trunk/documentation/reference-guide/en/modules/concepts.xml =================================================================== --- authz/trunk/documentation/reference-guide/en/modules/concepts.xml 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/documentation/reference-guide/en/modules/concepts.xml 2009-09-08 18:05:46 UTC (rev 773) @@ -1,4 +1,9 @@ <?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" + [ + <!ENTITY concepts SYSTEM "concepts.sgm" NDATA SGML> + ] +> <chapter id="concepts"> <chapterinfo> <author> @@ -8,7 +13,7 @@ </author> </chapterinfo> <title>Concepts</title> - <sect1> + <sect1 id="concepts.resource"> <title>Resource</title> <para> A Data, Service, or a System component. @@ -17,7 +22,7 @@ <emphasis role="bold">Examples</emphasis> : a HTTP URL, a Servlet, a Portlet, a POJO (Plain Old Java Object), a Java Method, a Java Field, etc </para> </sect1> - <sect1> + <sect1 id="concepts.action"> <title>Action</title> <para> An operation on a resource. @@ -26,7 +31,7 @@ <emphasis role="bold">Examples</emphasis> : CRUD (Create, Read, Update, Delete), HTTP GET, HTTP POST, PORTLET VIEW, PORTLET ACTION, etc </para> </sect1> - <sect1> + <sect1 id="concepts.subject"> <title>Subject</title> <para> An actor. @@ -35,7 +40,7 @@ <emphasis role="bold">Examples</emphasis> : Authenticated User, Anonymous User, a Machine, etc </para> </sect1> - <sect1> + <sect1 id="concepts.environment"> <title>Environment</title> <para> The set of attributes that are relevant to an authorization decision and are independent of a particular subject, resource, or action. @@ -44,7 +49,7 @@ <emphasis role="bold">Examples</emphasis> : Current Date and/or Time, Application Data in a HTTP Session, the parameters passed to a Java method call, etc </para> </sect1> - <sect1> + <sect1 id="concepts.attribute"> <title>Attribute</title> <para> A characteristic of a Resource, Action, Subject or Environment which is referenced within a Policy Rule or a Policy Target. Attributes are runtime information @@ -65,21 +70,21 @@ <emphasis role="bold">Environment Examples</emphasis> : Current Date and/or Time, etc </para> </sect1> - <sect1> + <sect1 id="concepts.policy"> <title>Policy</title> <para> A security policy consisting of a target and multiple rules. An Enterprise application will have multiple policies stored in the system. Enforcement requests are evaluated by applying the logic specified within these policies. A Policy Evaluation results in a Permit or Deny State. </para> </sect1> - <sect1> + <sect1 id="concepts.target"> <title>Target</title> <para> The set of Enforcement requests identified by policy definitions of Resource, Subject, and Action that a Policy or a Rule is intended to evalute. Simply put, Target definition consists of logic that determines whether a particular Policy or Rule should be evaluated for the incoming Enforcement request. </para> </sect1> - <sect1> + <sect1 id="concepts.rule"> <title>Rule</title> <para> A Policy Component which consists of the following: Deleted: authz/trunk/documentation/reference-guide/en/modules/examples.xml =================================================================== --- authz/trunk/documentation/reference-guide/en/modules/examples.xml 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/documentation/reference-guide/en/modules/examples.xml 2009-09-08 18:05:46 UTC (rev 773) @@ -1,11 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="examples"> - <chapterinfo> - <author> - <firstname>Sohil</firstname> - <surname>Shah</surname> - <email&gt;sshah(a)redhat.com&lt;/email&gt; - </author> - </chapterinfo> - <title>Examples</title> -</chapter> Modified: authz/trunk/documentation/reference-guide/en/modules/framework.xml =================================================================== --- authz/trunk/documentation/reference-guide/en/modules/framework.xml 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/documentation/reference-guide/en/modules/framework.xml 2009-09-08 18:05:46 UTC (rev 773) @@ -140,9 +140,67 @@ <emphasis>EnforcementContext</emphasis> answers the <emphasis role="bold">”This is what I am trying to access, and this is my current application state”</emphasis>. 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 processed by the framework as ”Authorization Components”. - The "Authorization Component" spec will be covered in more details in the next chapter. + are processed by the framework as <emphasis>”Authorization Components”</emphasis>. + The <emphasis>"Authorization Component"</emphasis> spec will be covered in more details in the next chapter. </para> + <para> + The framework provides an extensive set of core <emphasis>”Authorization Components”</emphasis>. The core component set tries to cover the concepts covered by the + industry standard <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xacm... specification</ulink>. + More custom components can also be created based on the <emphasis>”Authorization Component”</emphasis> specification. + </para> + <sect3> + <title>Enforcement Phase Life Cycle</title> + <para> + <itemizedlist> + <listitem> + An incoming application request is intercepted before invoking a protected resource. An <emphasis role="bold">EnforcementContext</emphasis> is generated. + It consisting of authorization components that represent the runtime state of the system. + An <emphasis role="bold">Enforcement Request</emphasis> is then issued to the framework + </listitem> + <listitem> + The framework then processes this <emphasis role="bold">Enforcement Request</emphasis> through its <emphasis>rule engine</emphasis> and + <emphasis>stored policies</emphasis>. It produces a <emphasis role="bold">'Permit'</emphasis>, or <emphasis role="bold">'Deny'</emphasis> decision + </listitem> + <listitem> + If access is granted, the application request moves forward, if not, appropriate action is taken by the application + </listitem> + </itemizedlist> + </para> + <para> + TODO: Use a Diagram to illustrate this life cycle + </para> + </sect3> </sect2> + <sect2> + <title>Provisioning Phase</title> + <para> + A <emphasis role="bold">CompositionContext</emphasis> allows the Application Developer to specify the authorization component hierarchy that a policy instance + is composed of. It is processed by the <emphasis>PolicyComposer</emphasis> service. The <emphasis>PolicyComposer</emphasis> generates the low-level policy instance. + The <emphasis>PolicyComposer</emphasis> shields the Application Developer from low-level policy processing and representation details. + </para> + <sect3> + <title>Provisioning Phase Life Cycle</title> + <para> + <itemizedlist> + <listitem> + The <emphasis>component hierarchy</emphasis> represented inside a <emphasis role="bold">CompositionContext</emphasis> is created by the application. + This <emphasis role="bold">CompositionContext</emphasis> is sent to the <emphasis>PolicyComposer</emphasis>. + </listitem> + <listitem> + Inside the <emphasis>PolicyComposer</emphasis>, based on the state of the authorization components, a system level policy (in this case + an xacml policy) is autogenerated. The composer also handles generation of all conditional logic that must be associated with the policy. + </listitem> + <listitem> + The generated system policy is then propagated to storage and the runtime state of other live components. This allows dynamic provisioning of + desired application security requirements (application/cluster restart is <emphasis>not</emphasis> needed, even when the security policies are + changed at runtime). + </listitem> + </itemizedlist> + </para> + <para> + TODO: Use a Diagram to illustrate this life cycle + </para> + </sect3> + </sect2> </sect1> </chapter> Deleted: authz/trunk/documentation/reference-guide/en/modules/spi.xml =================================================================== --- authz/trunk/documentation/reference-guide/en/modules/spi.xml 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/documentation/reference-guide/en/modules/spi.xml 2009-09-08 18:05:46 UTC (rev 773) @@ -1,16 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="spi"> - <chapterinfo> - <author> - <firstname>Sohil</firstname> - <surname>Shah</surname> - <email&gt;sshah(a)redhat.com&lt;/email&gt; - </author> - </chapterinfo> - <title>Policy Store SPI</title> - <sect1> - <title>Policy Store SPI</title> - <para> - </para> - </sect1> -</chapter> Modified: authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/ComponentCategory.java =================================================================== --- authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/ComponentCategory.java 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/ComponentCategory.java 2009-09-08 18:05:46 UTC (rev 773) @@ -31,6 +31,7 @@ */ public enum ComponentCategory { + //Resources------------------------------------------------------------------------------------------------------------------------------------------------------ RESOURCE { public String getAttributeCategory() @@ -42,9 +43,8 @@ { target.addResourceMatch(expression); } - }, - - + }, + //Subjects------------------------------------------------------------------------------------------------------------------------------------------------------ SUBJECT { public String getAttributeCategory() @@ -58,32 +58,33 @@ } }, - - ACTION + CUSTOM_SUBJECT_ATTRIBUTE { public String getAttributeCategory() { - return XACMLConstants.ATTRIBUTEID_ACTION_ID; + return AttributeDesignatorUtil.ATTRIBUTEID_CUSTOM_SUBJECT_ATTRIBUTE; } public void setExpression(Target target, AttributeExpression expression) { - target.addActionMatch(expression); + target.addSubjectMatch(expression); } - }, - - CUSTOM_SUBJECT_ATTRIBUTE + }, + //---Actions--------------------------------------------------------------------------------------------------------------------------------------------------- + ACTION { public String getAttributeCategory() { - return AttributeDesignatorUtil.ATTRIBUTEID_CUSTOM_SUBJECT_ATTRIBUTE; + return XACMLConstants.ATTRIBUTEID_ACTION_ID; } public void setExpression(Target target, AttributeExpression expression) { - target.addSubjectMatch(expression); + target.addActionMatch(expression); } }; + //------Environment------------------------------------------------------------------------------------------------------------------------------------------- + //Define the enum behavior public abstract String getAttributeCategory(); Deleted: authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/LogicData.java =================================================================== --- authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/LogicData.java 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/LogicData.java 2009-09-08 18:05:46 UTC (rev 773) @@ -1,37 +0,0 @@ -/* -* JBoss, a division of Red Hat -* Copyright 2006, Red Hat Middleware, LLC, and individual contributors as indicated -* by the @authors tag. See the copyright.txt in the distribution for a -* full listing of individual contributors. -* -* This is free software; you can redistribute it and/or modify it -* under the terms of the GNU Lesser General Public License as -* published by the Free Software Foundation; either version 2.1 of -* the License, or (at your option) any later version. -* -* This software is distributed in the hope that it will be useful, -* but WITHOUT ANY WARRANTY; without even the implied warranty of -* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -* Lesser General Public License for more details. -* -* You should have received a copy of the GNU Lesser General Public -* License along with this software; if not, write to the Free -* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA -* 02110-1301 USA, or see the FSF site: http://www.fsf.org. -*/ -package org.jboss.security.authz.component; - -import java.lang.annotation.Target; -import java.lang.annotation.Retention; -import java.lang.annotation.ElementType; -import java.lang.annotation.RetentionPolicy; - -/** - * @author <a href="mailto:sshah@redhat.com">Sohil Shah</a> - */ -(a)Target(ElementType.FIELD) -(a)Retention(RetentionPolicy.RUNTIME) -public @interface LogicData -{ - -} Deleted: authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/TargetUri.java =================================================================== --- authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/TargetUri.java 2009-09-06 18:16:13 UTC (rev 772) +++ authz/trunk/public-api/src/main/java/org/jboss/security/authz/component/TargetUri.java 2009-09-08 18:05:46 UTC (rev 773) @@ -1,37 +0,0 @@ -/* -* JBoss, a division of Red Hat -* Copyright 2006, Red Hat Middleware, LLC, and individual contributors as indicated -* by the @authors tag. See the copyright.txt in the distribution for a -* full listing of individual contributors. -* -* This is free software; you can redistribute it and/or modify it -* under the terms of the GNU Lesser General Public License as -* published by the Free Software Foundation; either version 2.1 of -* the License, or (at your option) any later version. -* -* This software is distributed in the hope that it will be useful, -* but WITHOUT ANY WARRANTY; without even the implied warranty of -* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -* Lesser General Public License for more details. -* -* You should have received a copy of the GNU Lesser General Public -* License along with this software; if not, write to the Free -* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA -* 02110-1301 USA, or see the FSF site: http://www.fsf.org. -*/ -package org.jboss.security.authz.component; - -import java.lang.annotation.Target; -import java.lang.annotation.Retention; -import java.lang.annotation.ElementType; -import java.lang.annotation.RetentionPolicy; - -/** - * @author <a href="mailto:sshah@redhat.com">Sohil Shah</a> - */ -(a)Target(ElementType.FIELD) -(a)Retention(RetentionPolicy.RUNTIME) -public @interface TargetUri -{ - -}