From jboss-identity-commits at lists.jboss.org Fri Sep 18 18:05:49 2009
Content-Type: multipart/mixed; boundary="===============3547528126816379089=="
MIME-Version: 1.0
From: jboss-identity-commits at lists.jboss.org
To: jboss-identity-commits at lists.jboss.org
Subject: [jboss-identity-commits] JBoss Identity SVN: r800 - in
 authz/trunk/documentation/reference-guide/en: modules and 1 other directory.
Date: Fri, 18 Sep 2009 18:05:48 -0400
Message-ID: <200909182205.n8IM5m1X022773@svn01.web.mwc.hst.phx2.redhat.com>

--===============3547528126816379089==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: sohil.shah(a)jboss.com
Date: 2009-09-18 18:05:48 -0400 (Fri, 18 Sep 2009)
New Revision: 800

Added:
   authz/trunk/documentation/reference-guide/en/modules/getting-started.xml
Modified:
   authz/trunk/documentation/reference-guide/en/master.xml
   authz/trunk/documentation/reference-guide/en/modules/framework.xml
Log:
more documentation

Modified: authz/trunk/documentation/reference-guide/en/master.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- authz/trunk/documentation/reference-guide/en/master.xml	2009-09-17 18:1=
7:49 UTC (rev 799)
+++ authz/trunk/documentation/reference-guide/en/master.xml	2009-09-18 22:0=
5:48 UTC (rev 800)
@@ -17,9 +17,8 @@
    <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"module=
s/concepts.xml"/>
    <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"module=
s/architecture.xml"/>
    =

-   <!-- =

-   <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"module=
s/sample.xml"/>
-   -->
+   <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"module=
s/getting-started.xml"/>
+   =

    <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"module=
s/framework.xml"/>
    <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"module=
s/authz-component-spec.xml"/>
    <!--    =


Modified: authz/trunk/documentation/reference-guide/en/modules/framework.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- authz/trunk/documentation/reference-guide/en/modules/framework.xml	2009=
-09-17 18:17:49 UTC (rev 799)
+++ authz/trunk/documentation/reference-guide/en/modules/framework.xml	2009=
-09-18 22:05:48 UTC (rev 800)
@@ -178,6 +178,18 @@
    			is composed of. It is processed by the <emphasis>PolicyComposer</emp=
hasis> service. The <emphasis>PolicyComposer</emphasis> generates the low-l=
evel policy instance. =

    			The <emphasis>PolicyComposer</emphasis> shields the Application Deve=
loper from low-level policy processing and representation details.
    			</para>
+   			<para>
+	   			Provisioning is an open ended aspect of authorization. It spans fro=
m <emphasis>static xml based provisioning</emphasis> on one end to a fully =
dynamic/centralized management tool based provisioning.
+	   			Here are some of the provisioning scenarios that are possible:
+	   			<itemizedlist>
+	   				<listitem>
+	   				</listitem>
+	   				<listitem>
+	   				</listitem>
+	   				<listitem>
+	   				</listitem>
+	   			</itemizedlist>
+	   		</para>
    			<sect3>
    				<title>Provisioning Phase Life Cycle</title>
    				<para>

Added: authz/trunk/documentation/reference-guide/en/modules/getting-started=
.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- authz/trunk/documentation/reference-guide/en/modules/getting-started.xm=
l	                        (rev 0)
+++ authz/trunk/documentation/reference-guide/en/modules/getting-started.xm=
l	2009-09-18 22:05:48 UTC (rev 800)
@@ -0,0 +1,439 @@
+<?xml version=3D"1.0" encoding=3D"UTF-8"?>
+<chapter id=3D"getting-started">
+   <chapterinfo>
+      <author>
+         <firstname>Sohil</firstname>
+         <surname>Shah</surname>
+         <email>sshah(a)redhat.com</email>
+      </author>
+   </chapterinfo>
+   <title>Getting Started</title>
+   <sect1>
+   		<title>End-to-End Development Process</title>
+   		<para>
+   			The Development Process for the framework is split into three steps.
+   		</para>
+   		<sect2>
+	   		<title>Core Application/Infrastructure Development</title>
+	   		<para>
+	   			This is where the <emphasis role=3D"bold">Application Developers</e=
mphasis> develop their applications without any concern of embedding any se=
curity checking logic inside their implementation. =

+	   			Basically, think of it as developing an application that does not h=
ave any knowledge of security functionality.
+	   		</para>	   		=

+	   		<para>
+	   			<programlisting>
+		<![CDATA[
+public class Pojo
+{
+	private String sensitiveData;
+	=

+	public Pojo()
+	{
+		=

+	}
+
+	public String getSensitiveData()
+	{
+		return this.sensitiveData;
+	}
+
+	public void setSensitiveData(String sensitiveData)
+	{
+		this.sensitiveData =3D sensitiveData;
+	}	=

+}
+		]]>
+	   			</programlisting>
+	   		</para>
+	   		<para>
+	   			This shows a very simple POJO that carries some sensitive data with=
in one of its fields named: <emphasis>sensitiveData</emphasis>.
+	   			This data is private and is accessible via standard get/set methods.
+	   			<emphasis role=3D"bold">Note:</emphasis> This is simple application=
 code and it has no knowledge about the existence of a security service =

+	   		</para>
+	   	</sect2>   =

+	   	<sect2>	=

+	   		<title>Enforcement Layer</title>
+	   		<para>
+	   			This is the <emphasis>cross cutting</emphasis> layer of the applica=
tion that introduces <emphasis>authorization functionality</emphasis> to an=
 otherwise authorization agnostic application. This layer makes the "Enforc=
ement Phase" possible.
+	   		</para>	=

+	   		<para>
+	   			Development of this layer is primarily the responsibility of a <emp=
hasis role=3D"bold">System Integrator</emphasis> or a <emphasis role=3D"bol=
d">Platform Developer</emphasis>. =

+	   			The <emphasis role=3D"bold">Application Developer</emphasis> typica=
lly integrates it via
+	   			configuration as a <emphasis>container service</emphasis>.
+	   		</para>
+	   		<para>
+	   			The <emphasis>Enforcement Layer</emphasis> is integrated as a <emph=
asis>JBoss AOP Interceptor</emphasis>, for the POJO application in this exa=
mple.
+	   		</para>
+	   		<para>
+	   			<programlisting>
+	   				<![CDATA[
+<aop>
+	<bind pointcut=3D"execution(* org.jboss.security.authz.samples.pojo.Pojo-=
>*(..))">
+					<interceptor class=3D"org.jboss.security.authz.samples.pojo.enforceme=
nt.SecurityInterceptor"/>
+	</bind>
+</aop>
+	   				]]>
+	   			</programlisting>
+	   		</para>
+	   		<para>
+	   			This <emphasis>jboss-aop.xml</emphasis> specifies the scope of code=
 weaving to integrate the <emphasis>SecurityInterceptor</emphasis>. In this=
 case it says,
+	   			intercept all method calls on  <emphasis>org.jboss.security.authz.s=
amples.pojo.Pojo</emphasis>. The scope of interception can be increased/dec=
reased based
+	   			on application requirements/design
+	   		</para>
+	   		<para>
+	   			<emphasis role=3D"bold">Security Interceptor</emphasis> explanation:
+	   			<programlisting>
+	   				<![CDATA[
+MethodInvocation methodInvocation =3D (MethodInvocation)invocation;			=

+Object pojoBeingAccessed =3D methodInvocation.getTargetObject();
+Method methodBeingCalled =3D methodInvocation.getMethod();
+	   				]]>
+	   			</programlisting>
+	   		</para>
+	   		<para>
+	   			Gets information about the POJO instance being accessed <emphasis r=
ole=3D"bold">Resource</emphasis>, and the method being invoked <emphasis ro=
le=3D"bold">Action</emphasis>
+	   		</para>
+	   		<para>
+	   			<programlisting>
+	   				<![CDATA[
+Identity identity =3D new Identity();
+identity.setName(session.getUsername());
+
+Roles roles =3D new Roles();
+if(session.getRoles() !=3D null)
+{
+	for(String roleName: session.getRoles())
+	roles.addName(roleName);
+}
+
+//Resource Component
+URIResource resource =3D new URIResource();
+resource.setUri(new URI(pojoBeingAccessed.getClass().getName()));
+
+//Action Component
+Object action =3D null;
+if(methodBeingCalled.getName().startsWith("get"))
+{
+	action =3D new Read();
+}
+else if(methodBeingCalled.getName().startsWith("set"))
+{
+	action =3D new Write();
+}
+	   				]]>
+	   			</programlisting>
+	   			Populating <emphasis role=3D"bold">Authz Components</emphasis> with=
 runtime application state. In this example, its populating the Identity <e=
mphasis>(Subject)</emphasis>, Roles <emphasis>(Subject)</emphasis>,
+	   			URIResource <emphasis>(Resource)</emphasis>, and Read/Write <emphas=
is>(Action)</emphasis> components.
+	   		</para>
+	   		<para>
+	   			<programlisting>
+	   				<![CDATA[
+//Create an EnforcementContext and start the "Enforcement Phase" with the =
security framework
+EnforcementContext context =3D new EnforcementContext();
+context.setIgnoreCache(true);
+context.setAttribute("pojo", resource);
+context.setAttribute("method", action);
+context.setAttribute("identity", identity);
+context.setAttribute("roles", roles);
+				=

+//Process the result from Enforcement Phase execution
+EnforcementResponse response =3D this.getEnforcer().checkAccess(context);
+
+if(response.isAccessGranted())
+{
+	//Access to the Pojo is granted.....Proceed..
+	return invocation.invokeNext();
+}
+else
+{
+	//Throw appropriate exception or handle it according to what the requirem=
ents are.........
+	throw new IllegalAccessException("Pojo Access Denied!!!");
+}
+	   				]]>
+	   			</programlisting>
+	   			Creates an <emphasis role=3D"bold">EnforcementContext</emphasis> po=
pulated with the above <emphasis role=3D"bold">Authz Components</emphasis>,=
 uses the <emphasis role=3D"bold">Enforcer</emphasis> =

+	   			to perform a security check, and finally depending upon <emphasis>P=
ermit</emphasis> or <emphasis>Deny</emphasis> result, either propagates the=
 method call further or throws an <emphasis>IllegalAccessException</emphasi=
s>
+	   		</para>
+	   	</sect2>
+	   	<sect2>
+	   		<title>Provisioning Layer</title>
+	   		<para>
+	   			This is the provisioning aspect of authorization. This layer provid=
es <emphasis>policy management</emphasis> =

+	   			capabilities within the context of functional requirements of the a=
pplication in question. This layer makes the "Provisioning Phase" possible.
+	   		</para>
+	   		<para>
+	   			<programlisting>
+	   				<![CDATA[
+// SetUp Resource
+URIResource resource =3D new URIResource();
+resource.setUri(new URI(Pojo.class.getName()));
+
+Read read =3D new Read();
+Roles readRoles =3D new Roles();
+readRoles.setMustMatchAll(false);
+readRoles.addName("regular");
+readRoles.addName("/blah1/blah2/blah3");
+
+Write write =3D new Write();
+Roles writeRoles =3D new Roles();
+writeRoles.setMustMatchAll(false);
+writeRoles.addName("admin");
+	   				]]>
+	   			</programlisting>
+	   			The above code sets up the state of the <emphasis role=3D"bold">Aut=
hz Components</emphasis> used to generate a specific <emphasis>policy</emph=
asis>.
+	   			<itemizedlist>
+	   				<listitem>
+	   					Step 1: Specifies that the resource "org.jboss.security.authz.sam=
ples.pojo.POJO" needs to be protected
+	   				</listitem>
+	   				<listitem>
+	   					Step 2: Specfies that the "getSensitiveData" method should be acc=
essible <emphasis>only</emphasis> by the specified roles
+	   				</listitem>
+	   				<listitem>
+	   					Step 3: Specifies that the "setSensitiveData" method should be ac=
cessible <emphasis>only</emphasis> by the specified roles =

+	   				</listitem>
+	   			</itemizedlist>
+	   		</para>
+	   		<para>
+	   		<programlisting>
+	   			<![CDATA[
+// Setup the Context for the Composition with these components
+CompositionContext context =3D new CompositionContext();
+context.setPolicyTarget(resource);
+context.addPolicyRule(Effect.PERMIT, read, readRoles,"allowExpression");
+context.addPolicyRule(Effect.PERMIT, write, writeRoles,"allowExpression");
+
+// Store the policy into the Policy Server
+this.getProvisioner().deploy(context);
+	   			]]>
+	   		</programlisting>
+	   		Generates a <emphasis>CompositionContext</emphasis> populated with t=
he proper <emphasis role=3D"bold">Authz Components</emphasis>.
+	   		The <emphasis>CompositionContext</emphasis> is then handed over to t=
he policy deployer to provision the single policy rule, that meets the =

+	   		above criteria specified by the components.
+	   		</para>
+	   	</sect2>
+	   	<sect2>
+	   		<title>Full Picture</title>
+	   		<sect3>
+	   			<title>Sample Code: Core Application/Infrastructure Development</ti=
tle>
+	   			<para>
+	   				<programlisting>
+	   					<![CDATA[
+package org.jboss.security.authz.samples.pojo;
+
+/**
+ * This is the core application level component. =

+ * =

+ * Notice there is absolutely no security code here....It does not even kn=
ow the security service exists
+ * =

+ * @author <a href=3D"mailto:sshah(a)redhat.com">Sohil Shah</a>
+ */
+public class Pojo
+{
+	private String sensitiveData;
+	=

+	public Pojo()
+	{
+		=

+	}
+
+	public String getSensitiveData()
+	{
+		return this.sensitiveData;
+	}
+
+	public void setSensitiveData(String sensitiveData)
+	{
+		this.sensitiveData =3D sensitiveData;
+	}	=

+}
+	   					]]>
+	   				</programlisting>
+	   			</para>
+	   		</sect3>
+	   		<sect3>
+	   			<title>Sample Code: Enforcement Layer</title>
+	   			<para>
+	   				jboss-app.xml
+	   				<programlisting>
+	   				<![CDATA[
+<aop>
+	<bind pointcut=3D"execution(* org.jboss.security.authz.samples.pojo.Pojo-=
>*(..))">
+					<interceptor class=3D"org.jboss.security.authz.samples.pojo.enforceme=
nt.SecurityInterceptor"/>
+	</bind>
+</aop>
+	   				]]>
+	   			</programlisting>
+	   			</para>
+	   			<para>
+	   				<programlisting>
+	   				<![CDATA[
+/**
+ * A sample Enforcement Interceptor used to inject the security service in=
to the application
+ * =

+ * The scope of interception can be increased/decreased depending upon the=
 application's security requirements
+ * =

+ * @author <a href=3D"mailto:sshah(a)redhat.com">Sohil Shah</a>
+ */
+public class SecurityInterceptor implements Interceptor
+{
+	private static Logger log =3D Logger.getLogger(SecurityInterceptor.class);
+		=

+	public String getName()
+	{		=

+		return this.getClass().getName();
+	}
+	=

+	private PolicyEnforcementPoint getEnforcer()
+	{		=

+		return (PolicyEnforcementPoint)ServiceContainer.lookup("/agent/LocalEnfo=
rcementPoint");
+	}	=

+	public Object invoke(Invocation invocation) throws Throwable
+	{	=

+		try
+		{												=

+			MethodInvocation methodInvocation =3D (MethodInvocation)invocation;
+			=

+			Object pojoBeingAccessed =3D methodInvocation.getTargetObject();
+			Method methodBeingCalled =3D methodInvocation.getMethod();						=

+			=

+			//Get the runtime application state (AuthenticatedSession) from ThreadL=
ocal
+			AuthenticatedSession session =3D (AuthenticatedSession)AuthenticatedSes=
sion.activeSession.get();			=

+			if(session =3D=3D null)
+			{
+				//Anonymous access
+				session =3D new AuthenticatedSession();
+				session.setUsername("anonymous");
+				session.addRole("anonymous");
+			}
+			=

+			//Properly propagate runtime application state to the state of appropri=
ate "Authz Components"			=

+			//Subject Components
+			Identity identity =3D new Identity();
+			identity.setName(session.getUsername());
+			=

+			Roles roles =3D new Roles();
+			if(session.getRoles() !=3D null)
+			{
+				for(String roleName: session.getRoles())
+				roles.addName(roleName);
+			}
+			=

+			//Resource Component
+			URIResource resource =3D new URIResource();
+			resource.setUri(new URI(pojoBeingAccessed.getClass().getName()));
+			=

+			//Action Component
+			Object action =3D null;
+			if(methodBeingCalled.getName().startsWith("get"))
+			{
+				action =3D new Read();
+			}
+			else if(methodBeingCalled.getName().startsWith("set"))
+			{
+				action =3D new Write();
+			}
+							=

+			//Create an EnforcementContext and start the "Enforcement Phase" with t=
he security framework
+			EnforcementContext context =3D new EnforcementContext();
+			context.setIgnoreCache(true);
+			context.setAttribute("pojo", resource);
+			context.setAttribute("method", action);
+			context.setAttribute("identity", identity);
+			context.setAttribute("roles", roles);
+							=

+			//Process the result from Enforcement Phase execution------------------=
---------------------------------------------------------------------------=
----------------
+			EnforcementResponse response =3D this.getEnforcer().checkAccess(context=
);
+			=

+			if(response.isAccessGranted())
+			{
+				//Access to the Pojo is granted.....Proceed..
+				return invocation.invokeNext();
+			}
+			else
+			{
+				//Throw appropriate exception or handle it according to what the requi=
rements are.........
+				throw new IllegalAccessException("Pojo Access Denied!!!");
+			}
+		}
+		finally
+		{			=

+		}
+	}		=

+}
+	   				]]>
+	   			</programlisting>
+	   			</para>
+	   		</sect3>
+	   		<sect3>
+	   			<title>Sample Code: Provisioning Layer</title>
+	   			<para>
+	   			<programlisting>
+	   			<![CDATA[
+/**
+ * The Provisioning component that is in charge of managing the security p=
olicies of the application
+ * =

+ * This is usually accessed via a GUI tool or the application's security d=
ashboard etc
+ * =

+ * @author <a href=3D"mailto:sshah(a)redhat.com">Sohil Shah</a>
+ */
+public class SecurityProvisioning
+{
+	private static Logger log =3D Logger.getLogger(SecurityProvisioning.class=
);
+	=

+	public void bootup()
+	{
+		try
+		{
+			// Provision POJO Policy
+			this.provisionPOJOPolicy();
+			=

+			Set<Policy> policies =3D this.getProvisioner().readAllPolicies();
+			for(Policy policy: policies)
+			{
+				log.info("------------------------------------------------------------=
------------------");
+				log.info(policy.generateSystemPolicy());
+			}
+		}
+		catch(Exception e)
+		{
+			throw new RuntimeException(e);
+		}
+	}	=

+	private void provisionPOJOPolicy() throws Exception
+	{
+		// SetUp Resource
+		URIResource resource =3D new URIResource();
+		resource.setUri(new URI(Pojo.class.getName()));
+
+		Read read =3D new Read();
+		Roles readRoles =3D new Roles();
+		readRoles.setMustMatchAll(false);
+		readRoles.addName("regular");
+		readRoles.addName("/blah1/blah2/blah3");
+		=

+		Write write =3D new Write();
+		Roles writeRoles =3D new Roles();
+		writeRoles.setMustMatchAll(false);
+		writeRoles.addName("admin");
+		=

+		// Setup the Context for the Composition with these components
+		CompositionContext context =3D new CompositionContext();
+		context.setPolicyTarget(resource);
+		context.addPolicyRule(Effect.PERMIT, read, readRoles,"allowExpression");
+		context.addPolicyRule(Effect.PERMIT, write, writeRoles,"allowExpression"=
);
+
+		// Store the policy into the Policy Server
+		this.getProvisioner().deploy(context);
+	}		=

+	=

+	private PolicyProvisioner getProvisioner()
+	{		=

+		return (PolicyProvisioner) ServiceContainer.lookup("/agent/LocalPolicyPr=
ovisioner");
+	}
+}
+				]]>
+	   			</programlisting>
+	   			</para>
+	   		</sect3>
+	   	</sect2>
+   </sect1>     =

+</chapter>


--===============3547528126816379089==--