You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2010/11/28 13:49:01 UTC
svn commit: r1039874 [1/5] - in /incubator/isis/trunk: ./
alternatives/remoting/src/docbkx/guide/
alternatives/security/file/src/docbkx/guide/
alternatives/security/ldap/src/docbkx/guide/ applib/src/docbkx/guide/
core/metamodel/src/test/java/org/apache...
Author: danhaywood
Date: Sun Nov 28 12:49:00 2010
New Revision: 1039874
URL: http://svn.apache.org/viewvc?rev=1039874&view=rev
Log:
split out the original NOF docs into trunk (the docs still need lots of work, but at least the raw material that we have to work from is in the right place)
Added:
incubator/isis/trunk/core/metamodel/src/test/java/org/apache/isis/core/metamodel/config/loader/ConfigurationBuilderFileSystemTest.java
- copied, changed from r1039231, incubator/isis/trunk/core/metamodel/src/test/java/org/apache/isis/core/metamodel/config/loader/ConfigurationLoaderFileSystemTest.java
incubator/isis/trunk/core/src/docbkx/guide/images/PersistenceSession.png (with props)
incubator/isis/trunk/core/src/docbkx/guide/images/PersistenceSession.pptx (with props)
incubator/isis/trunk/core/src/docbkx/guide/images/architecture.gif (with props)
incubator/isis/trunk/core/src/docbkx/guide/images/architecture.pptx (with props)
incubator/isis/trunk/src/docbkx/guide/
incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml
Removed:
incubator/isis/trunk/core/metamodel/src/test/java/org/apache/isis/core/metamodel/config/loader/ConfigurationLoaderFileSystemTest.java
incubator/isis/trunk/src/site/apt/background-material.apt
Modified:
incubator/isis/trunk/alternatives/remoting/src/docbkx/guide/isis-remoting.xml
incubator/isis/trunk/alternatives/security/file/src/docbkx/guide/isis-file-security.xml
incubator/isis/trunk/alternatives/security/ldap/src/docbkx/guide/isis-ldap-security.xml
incubator/isis/trunk/applib/src/docbkx/guide/isis-applib.xml
incubator/isis/trunk/core/src/docbkx/guide/images/HexagonalArchitectureOverview.png
incubator/isis/trunk/core/src/docbkx/guide/isis-core.xml
incubator/isis/trunk/pom.xml
incubator/isis/trunk/src/site/apt/contributors-building.apt
incubator/isis/trunk/src/site/apt/contributors-deploying.apt
incubator/isis/trunk/src/site/apt/contributors-devenv.apt
incubator/isis/trunk/src/site/site.xml
incubator/isis/trunk/viewer/dnd/src/docbkx/guide/isis-dnd-viewer.xml
incubator/isis/trunk/viewer/html/src/docbkx/guide/isis-html-viewer.xml
Modified: incubator/isis/trunk/alternatives/remoting/src/docbkx/guide/isis-remoting.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/alternatives/remoting/src/docbkx/guide/isis-remoting.xml?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/alternatives/remoting/src/docbkx/guide/isis-remoting.xml (original)
+++ incubator/isis/trunk/alternatives/remoting/src/docbkx/guide/isis-remoting.xml Sun Nov 28 12:49:00 2010
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -22,12 +22,15 @@
<book>
<bookinfo>
<title><?eval ${docbkxGuideTitle}?></title>
+
<subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
<releaseinfo><?eval ${project.version}?></releaseinfo>
<authorgroup>
<author>
<firstname>Dan</firstname>
+
<surname>Haywood</surname>
</author>
</authorgroup>
@@ -50,14 +53,12 @@
rapidly develop domain-driven applications following the <ulink
url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
pattern. It is made up of a core framework plus a number of alternate
- implementations, and supports various viewers and object stores. Apache
- Isis is hosted at the
- <ulink url="http://incubator.apache.org/isis">Apache Foundation</ulink>,
- and is licensed under <ulink
+ implementations, and supports various viewers and object stores. Apache
+ Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+ Foundation</ulink>, and is licensed under <ulink
url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
License v2</ulink>.</para>
-
<para>This guide is written for ...</para>
</preface>
@@ -70,10 +71,300 @@
<para>*** yada yada</para>
</abstract>
+ <para></para>
+
+ <note>
+ <para>TODO: tidy up the following paras, were just copied/pasted in from
+ APT</para>
+ </note>
+
+ <para></para>
+
+ <para>[[NAME]] allows remote clients to interact with a server by passing
+ requests over a communication for another VM to deal with instead of
+ user's VM as would happen in the standalone version. Each request starts
+ by passing over authentication details to ensure the user is valid and to
+ allow request to be authorised (altough requests are never passed from the
+ client when the client knows it is not authorised, this guards against
+ malicious access). Following that is the data for the request and here
+ references are passed (using the <classname>Oid</classname> class) for
+ persistent object, while graphs of data are passed for transient
+ objects.</para>
+
+ <para>Requests are routed to the <classname>ServerFacade</classname>
+ object, where each specific request results in a calls to a specific
+ method. For example a find request goes to the
+ <methodname>findInstances</methodname> method while a change to an objects
+ property goes to the <methodname>setAssociation</methodname> method. The
+ facade then decodes the parameters of the request into objectst that
+ [[NAME]] Objects can deal with. So, for example, an
+ <classname>IdentityData</classname> is used to look up a persistent
+ instance, while a identifier string is used to find a
+ <classname>ObjectMember</classname>. With the details of the request
+ converted to [[NAME]] objects the requisite call is made into the [[NAME]]
+ system. After that call is made two things are returned to the client,
+ this time by converting [[NAME]] objects to transferable data objects.
+ First, the result of the call into [[NAME]] is return and, second, any
+ changes made to any objects involved (the object changed set) are passed
+ back for the client to update the objects that it has.</para>
+
+ <para>Connections from the client are accepted by the ServerListener,
+ which in the case the</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>Client/server deployments require a transport protocol for network
+ interactions. The core API and a basic
+ <classname>java.net.Socket</classname> based implementation is defined in
+ {{{../core/runtime/index.html}runtime}}. An alternative HTTP-based
+ implementation is available in
+ {{{./http-remoting/index.html}http-remoting}}.</para>
+
+ <para></para>
+
+ <para>In addition to a transport, client/server remoting also requires a
+ marshalling mechanism. This is used to "take apart" the domain objects and
+ then reassemble them. The core API and standard implementation for
+ marshalling is defined in {{{../core/runtime/index.html}runtime}}; an
+ alternative Xstream-based implementation is available in
+ {{{./xstream-marshalling/index.html}xstream-marshalling}}.</para>
+
<sect1>
- <title>***</title>
+ <title>Transports</title>
<para><emphasis>*** yada yada</emphasis></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Marshalling</title>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Sockets Transport</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>Configuring the Server</title>
+
+ <para></para>
+
+ <para></para>
+
+ <sect2>
+ <title>Setting up Security</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para>x-ref Core documentation.</para>
+
+ <para></para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Configuring the Client</title>
+
+ <para></para>
+
+ <sect2>
+ <title>Setting up Security</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para>x-ref Core documentation.</para>
+
+ <para></para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Running Client-Server over Sockets</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect2>
+ <title>Running [[NAME]] as a socket server</title>
+
+ <screen format="linespecific">$ isis.sh --type server --viewer xstream-sockets --persistor xml</screen>
+
+ <para>This command runs [[NAME]] as a socket server. The
+ <methodname>viewer</methodname> command line option specifies that the
+ server will listen for requests using basic TCP/IP plain sockets with
+ the XStream marshalling mechanism. The
+ <methodname>persistor</methodname> command line option indicates to
+ use XML object store as the persistence mechanism.</para>
+ </sect2>
+
+ <sect2>
+ <title>Running [[NAME]] as a socket client</title>
+
+ <screen format="linespecific">$ isis.sh --type client --viewer dnd --connector xstream-sockets </screen>
+
+ <para>This commands starts up [[NAME]] as a client, using the DND
+ viewer. The <methodname>connector</methodname> command line option
+ indicates to use the XStream marshalling mechanism over basic TCP/IP
+ sockets. As we are now running a multi-user system more than one
+ client can be started up.</para>
+
+ <para>To allow the client to connect to a remote server the
+ <methodname>address</methodname> property needs to be specified. For
+ simplicity this can be added the <filename class="directory"
+ moreinfo="none">isis.properties</filename> file, but it may
+ alternatively be placed in a separate file called <filename
+ class="directory"
+ moreinfo="none">transport_sockets.properties</filename>.</para>
+
+ <programlisting format="linespecific">isis.transport.sockets.host = server.mycompanyname.com</programlisting>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Server monitoring</title>
+
+ <para>The NO server can be monitored via a web browser using <ulink
+ url="http://localhost:8081/">http://localhost:8081/</ulink>.</para>
+
+ <para>The port can be changed from its default of 8081 using the port
+ property like this:</para>
+
+ <programlisting>isis.monitor.http.port=9000</programlisting>
+
+ <para>The NO server can also be monitored using telnet on port
+ 8009.</para>
+
+ <para>The port can be changed from its default of 8009 using the port
+ property like this:</para>
+
+ <programlisting>isis.monitor.telnet.port=9000</programlisting>
+
+ <para>Commands include: Overview, Authenticator, Configuration,
+ Reflector, Listeners, Events, Contexts, shutdown and bye.</para>
+
+ <para>Shutdown terminate the NO server.</para>
+
+ <para>Bye disconnects the telnet session.</para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Http Transport</title>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>Configuring the Server</title>
+
+ <para></para>
+
+ <para></para>
+
+ <sect2>
+ <title>Setting up Security</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para>x-ref Core documentation.</para>
+
+ <para></para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Configuring the Client</title>
+
+ <para></para>
+
+ <sect2>
+ <title>Setting up Security</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para>x-ref Core documentation.</para>
+
+ <para></para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Running Client-Server over HTTP</title>
+
+ <sect2>
+ <title>Running [[NAME]] as a HTTP server</title>
+
+ <screen format="linespecific">$ isis.sh --type server --viewer encoding-http --persistor xml</screen>
+
+ <para>This command runs [[NAME]] as a server. The
+ <methodname>viewer</methodname> command line parameter specifies that
+ the server will listen using http using the encoding marshalling
+ mechanism. The <methodname>persistor</methodname> property XML object
+ store as the persistence mechanism - a very simple persistence
+ mechanism useful for initial prototyping. (In fact, the XML object
+ store is the default persistence mechanism, so this property may be
+ omitted from the command).</para>
+
+ <para>Alternatively the remoting servlet
+ <classname>EncodingOverHttpRemotingServlet</classname> can be added to
+ the <filename>web.xml</filename> in the webapp project and the
+ [[NAME]] run as a web app, see below.</para>
+ </sect2>
+
+ <sect2>
+ <title>Running [[NAME]] as socket client</title>
+
+ <screen format="linespecific">$ isis.sh --type client --viewer dnd --connector encoding-http </screen>
+
+ <para>This commands starts up [[NAME]] as a client, using the DND
+ viewer. The <methodname>connector</methodname> command line option
+ indicates to use submit requests using http and with the encoding
+ marshalling mechanism. Again, as we are now running a multi-user
+ system more than one client can be started up.</para>
+
+ <para>To allow the client to connect to a remote server the
+ <methodname>address</methodname> property needs to be specified. For
+ simplicity this can be added the <filename class="directory"
+ moreinfo="none">isis.properties</filename> file, but it may
+ alternatively be placed in a separate file called <filename
+ class="directory"
+ moreinfo="none">transport_http.properties</filename>.</para>
+
+ <programlisting format="linespecific">isis.transport.http.url = http://server.mycompanyname.com:8080/remoting.svc</programlisting>
+ </sect2>
</sect1>
</chapter>
Modified: incubator/isis/trunk/alternatives/security/file/src/docbkx/guide/isis-file-security.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/alternatives/security/file/src/docbkx/guide/isis-file-security.xml?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/alternatives/security/file/src/docbkx/guide/isis-file-security.xml (original)
+++ incubator/isis/trunk/alternatives/security/file/src/docbkx/guide/isis-file-security.xml Sun Nov 28 12:49:00 2010
@@ -17,21 +17,26 @@
specific language governing permissions and limitations
under the License.
-->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
<book>
<bookinfo>
<title><?eval ${docbkxGuideTitle}?></title>
+
<subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
<releaseinfo><?eval ${project.version}?></releaseinfo>
<authorgroup>
<author>
<firstname>Robert</firstname>
+
<surname>Matthews</surname>
</author>
+
<author>
<firstname>Kevin</firstname>
+
<surname>Meyer</surname>
</author>
</authorgroup>
@@ -54,10 +59,9 @@
rapidly develop domain-driven applications following the <ulink
url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
pattern. It is made up of a core framework plus a number of alternate
- implementations, and supports various viewers and object stores. Apache
- Isis is hosted at the
- <ulink url="http://incubator.apache.org/isis">Apache Foundation</ulink>,
- and is licensed under <ulink
+ implementations, and supports various viewers and object stores. Apache
+ Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+ Foundation</ulink>, and is licensed under <ulink
url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
License v2</ulink>.</para>
@@ -78,6 +82,404 @@
<para><emphasis>*** yada yada</emphasis></para>
</sect1>
+
+ <sect1>
+ <title>Adding Security (Authentication and Authorization)</title>
+
+ <para><remark></remark></para>
+
+ <para>x-ref Core documentation.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>... also, move into the next chapters</para>
+
+ <para></para>
+
+ <para>Starting [[NAME]] requires a user name and password . (The
+ exception is when running in exploration mode, which uses default
+ values). The simplest way to specify the list of user names and
+ passwords is in a passwords file.</para>
+
+ <sect2>
+ <title>Authentication using a passwords file</title>
+
+ <para>Create a file called <filename class="directory"
+ moreinfo="none">password</filename>s, and place into the <filename
+ class="directory" moreinfo="none">config</filename> directory as the
+ following example shows.</para>
+
+ <screen format="linespecific">config/
+ passwords
+</screen>
+
+ <para>The following example shows how user names (sven and dick) and
+ corresponding passwords (passwd1 and passwd2) should be specified in
+ the password file.</para>
+
+ <programlisting format="linespecific">sven:passwd1
+dick:passwd2</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Authentication through a passwords file</title>
+
+ <para>To explicitly use file-based authentication set the following
+ property. (Note, however, that if this property is absent, the
+ framework will anyway assume file-based authentication as the
+ default).</para>
+
+ <programlisting format="linespecific">isis.authentication=file</programlisting>
+
+ <para>The location and name of the passwords file may be specified
+ explicitly - if not it defaults to the <filename class="directory"
+ moreinfo="none">passwords</filename> file, assumed to be in the
+ <filename class="directory" moreinfo="none">config</filename>
+ directory (or under WEB-INF if running as a web application).</para>
+
+ <programlisting format="linespecific">isis.authentication.file.location= passwords </programlisting>
+
+ <para>The <filename class="directory"
+ moreinfo="none">passwords</filename> file contains users, passwords
+ and any roles, as follows.</para>
+
+ <programlisting format="linespecific"><user>:<password>:<role>|<role>|...</programlisting>
+
+ <para>For example, user 'sven', with password 'pass' and roles 'role1'
+ and 'role2' would be</para>
+
+ <programlisting format="linespecific">sven:pass:role1|role2 </programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Authorization using Allow and/or Disallow files</title>
+
+ <para>Authorization allows access to actions and properties to be
+ controlled by configuration. Authorization is entirely optional and is
+ disabled by default - in which case every user is given access to all
+ actions and properties. A prerequisite for authorization is for users
+ to have roles. These should be added to the password file as
+ follows.</para>
+
+ <programlisting format="linespecific">sven:passwd1:ordinary_user
+dick:passwd2:special_user|admin</programlisting>
+
+ <para>Sven has the role 'ordinary_user', dick has the two roles
+ 'special_user' and 'admin'.</para>
+
+ <para>[[NAME]] needs to be told which actions and properties are
+ authorised for which roles. The simplest way to do this is in a file
+ i.e. <filename class="directory" moreinfo="none">allow</filename> in
+ the config directory.</para>
+
+ <screen format="linespecific">config/
+ <emphasis role="strong">password</emphasis>
+ <emphasis role="strong">allow</emphasis>
+ </screen>
+
+ <para>Each entry in the <filename class="directory"
+ moreinfo="none">allow</filename> file specifies either a class, or a
+ particular action or property within a class, together with the roles
+ that are allowed to access it. E.g.</para>
+
+ <screen format="linespecific">example.dom.PhoneNumber#Number:ordinary_user|special_user
+example.dom.Contact#Phones:ordinary_user|special_user
+example.dom.Contact#FullName:ordinary_user|special_user
+org.apache.isis.nof.core.service.SimpleRepository#FindByTitle(java.lang.String):ordinary_user|special_user
+example.dom.PhoneNumber#Type:ordinary_user|special_user
+example.dom.Contact#KnownAs:ordinary_user|special_user
+org.apache.isis.nof.core.service.SimpleRepository#NewPersistentInstance():ordinary_user|special_user
+example.dom.Contact#CreatePhone():special_user
+org.apache.isis.nof.core.service.SimpleRepository#NewTransientInstance():ordinary_user|special_user
+org.apache.isis.nof.core.service.SimpleRepository#AllInstances():ordinary_user|special_user
+</screen>
+
+ <para>The above file allows 'example.dom.Contact#CreatePhone()' only
+ for users with role 'special_user' all other actions and properties
+ are allowed for roles 'ordinary_user' and 'special_user'. A different,
+ terser implementation of this would be to use separate <filename
+ class="directory" moreinfo="none">allow</filename> and <filename
+ class="directory" moreinfo="none">disallow</filename> files, or
+ example, the <filename class="directory"
+ moreinfo="none">allow</filename> file:</para>
+
+ <screen format="linespecific">example.dom.PhoneNumber:ordinary_user|special_user
+example.dom.Contact:ordinary_user|special_user
+org.apache.isis.nof.core.service.SimpleRepository:ordinary_user|special_user
+</screen>
+
+ <para>and the <filename class="directory"
+ moreinfo="none">disallow</filename> file:</para>
+
+ <screen format="linespecific">example.dom.Contact#CreatePhone():ordinary_user</screen>
+
+ <para>For more details, see the section on Managing Security.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
+
+ <sect2>
+ <title>Authentication through a passwords file</title>
+
+ <para>from the "managing security" section</para>
+
+ <para></para>
+
+ <para>To explicitly use file-based authentication set the following
+ property. (Note, however, that if this property is absent, the
+ framework will anyway assume file-based authentication as the
+ default).</para>
+
+ <programlisting format="linespecific">isis.authentication=file</programlisting>
+
+ <para>The location and name of the passwords file may be specified
+ explicitly - if not it defaults to the <filename class="directory"
+ moreinfo="none">passwords</filename> file, assumed to be in the
+ <filename class="directory" moreinfo="none">config</filename>
+ directory (or under WEB-INF if running as a web application).</para>
+
+ <programlisting format="linespecific">isis.authentication.file.location= passwords </programlisting>
+
+ <para>The <filename class="directory"
+ moreinfo="none">passwords</filename> file contains users, passwords
+ and any roles, as follows.</para>
+
+ <programlisting format="linespecific"><user>:<password>:<role>|<role>|...</programlisting>
+
+ <para>For example, user 'sven', with password 'pass' and roles 'role1'
+ and 'role2' would be</para>
+
+ <programlisting format="linespecific">sven:pass:role1|role2 </programlisting>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
+
+ <sect2>
+ <title>Authorization through 'allow' and 'disallow' files</title>
+
+ <para>To enable authorization by file including the facet and
+ specifying the authorization implementation in the settings</para>
+
+ <programlisting format="linespecific">isis.reflector.facets.include=\
+ org.apache.isis.runtime.authorization.standard.AuthorizationFacetFactoryImpl
+isis.authorization=file</programlisting>
+
+ <para>With file authorization the current user's role will be
+ authorised against a white and (optionally) a black list for each
+ method possibly available to them. The files are identified by
+ properties, e.g.</para>
+
+ <programlisting format="linespecific">isis.authorization.file.whitelist=allow
+isis.authorization.file.blacklist=disallow </programlisting>
+
+ <para>The white list file is mandatory, if there is no property it
+ defaults to 'allow' (picked up from the config directory or from
+ WEB-INF if running as a webapp). The black list file is optional. The
+ presence of the property indicates it is being used. If the white list
+ file default is being used then 'disallow' is suggested as a setting
+ for the black list.</para>
+
+ <para>Each file contains a signature to match against and a list of
+ roles. A match in the white list file permits the method and match in
+ the black list forbids it. The black list overrides the white list.
+ Matching occurs at three levels class, method (or property) and
+ parameters. Property matches are to the bean property name e.g.
+ 'phone' for getPhone and setPhone.</para>
+
+ <para>Formatted as follows:</para>
+
+ <para>If only class is to be matched: <fully qualified class>
+ :role1|role2|..</para>
+
+ <para>Class and method: <fully qualified
+ class>#<method>:role1|role2|..</para>
+
+ <para>Class and property: <fully qualified
+ class>#<property>:role1|role2|..</para>
+
+ <para>Parameters where method takes no parameters: <fully qualified
+ class>#<method>():role1|role2|...</para>
+
+ <para>Parameters where method takes one parameter: <fully qualified
+ class>#<method>(fully qualified parameter
+ class):role1|role2|...</para>
+
+ <para>Parameters where method takes two or more:</para>
+
+ <para><fully qualified class>#<method>(fully qualified
+ parameter class1, fully qualified parameter class2,
+ ...):role1|role2|...</para>
+
+ <para>Each line in the file is a separate match.</para>
+
+ <para>So, for example, in the white list file</para>
+
+ <programlisting format="linespecific">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate:role1 </programlisting>
+
+ <para>will permit all actions/properties on <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate</literal>
+ for role1</para>
+
+ <programlisting format="linespecific">com.isisgroup.expenses.services.hibernate.
+ ClaimantRepositoryHibernate#findClaimantByName:role1|role2</programlisting>
+
+ <para>will permit all overloaded methods named <literal
+ moreinfo="none">findClaimantByName</literal> on <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimantRepositoryHibernate</literal>
+ for role1 and role2 and</para>
+
+ <programlisting format="linespecific">com.isisgroup.expenses.services.hibernate.ClaimantRepositoryHibernate#findClaimantByIdentifier(java.lang.String):role3</programlisting>
+
+ <para>will permit <literal
+ moreinfo="none">findClaimantByIdentifier</literal> with parameter
+ <literal moreinfo="none">java.lang.String</literal> on <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimantRepositoryHibernate</literal>
+ for role3. In each case an identical entry in the black list file will
+ instead make the action or property unavailable. The combination of
+ white and black list allows some economy in the settings. For example,
+ if all but one method of a large class is to be allowed, that could be
+ configured with one entry per method in the white list file or,
+ better, a single entry for the class in the white list and a single
+ entry for the unavailable method in the black list.</para>
+ </sect2>
+
+ <sect2>
+ <title>Authorization through 'allow' and 'disallow' files</title>
+
+ <para>To enable authorization by file including the facet and
+ specifying the authorization implementation in the settings</para>
+
+ <programlisting format="linespecific">isis.reflector.facets.include=\
+ org.apache.isis.runtime.authorization.standard.AuthorizationFacetFactoryImpl
+isis.authorization=file</programlisting>
+
+ <para>With file authorization the current user's role will be
+ authorised against a white and (optionally) a black list for each
+ method possibly available to them. The files are identified by
+ properties, e.g.</para>
+
+ <programlisting format="linespecific">isis.authorization.file.whitelist=allow
+isis.authorization.file.blacklist=disallow </programlisting>
+
+ <para>The white list file is mandatory, if there is no property it
+ defaults to 'allow' (picked up from the config directory or from
+ WEB-INF if running as a webapp). The black list file is optional. The
+ presence of the property indicates it is being used. If the white list
+ file default is being used then 'disallow' is suggested as a setting
+ for the black list.</para>
+
+ <para>Each file contains a signature to match against and a list of
+ roles. A match in the white list file permits the method and match in
+ the black list forbids it. The black list overrides the white list.
+ Matching occurs at three levels class, method (or property) and
+ parameters. Property matches are to the bean property name e.g.
+ 'phone' for getPhone and setPhone.</para>
+
+ <para>Formatted as follows:</para>
+
+ <para>If only class is to be matched: <fully qualified class>
+ :role1|role2|..</para>
+
+ <para>Class and method: <fully qualified
+ class>#<method>:role1|role2|..</para>
+
+ <para>Class and property: <fully qualified
+ class>#<property>:role1|role2|..</para>
+
+ <para>Parameters where method takes no parameters: <fully qualified
+ class>#<method>():role1|role2|...</para>
+
+ <para>Parameters where method takes one parameter: <fully qualified
+ class>#<method>(fully qualified parameter
+ class):role1|role2|...</para>
+
+ <para>Parameters where method takes two or more:</para>
+
+ <para><fully qualified class>#<method>(fully qualified
+ parameter class1, fully qualified parameter class2,
+ ...):role1|role2|...</para>
+
+ <para>Each line in the file is a separate match.</para>
+
+ <para>So, for example, in the white list file</para>
+
+ <programlisting format="linespecific">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate:role1 </programlisting>
+
+ <para>will permit all actions/properties on <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate</literal>
+ for role1</para>
+
+ <programlisting format="linespecific">com.isisgroup.expenses.services.hibernate.
+ ClaimantRepositoryHibernate#findClaimantByName:role1|role2</programlisting>
+
+ <para>will permit all overloaded methods named <literal
+ moreinfo="none">findClaimantByName</literal> on <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimantRepositoryHibernate</literal>
+ for role1 and role2 and</para>
+
+ <programlisting format="linespecific">com.isisgroup.expenses.services.hibernate.ClaimantRepositoryHibernate#findClaimantByIdentifier(java.lang.String):role3</programlisting>
+
+ <para>will permit <literal
+ moreinfo="none">findClaimantByIdentifier</literal> with parameter
+ <literal moreinfo="none">java.lang.String</literal> on <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimantRepositoryHibernate</literal>
+ for role3. In each case an identical entry in the black list file will
+ instead make the action or property unavailable. The combination of
+ white and black list allows some economy in the settings. For example,
+ if all but one method of a large class is to be allowed, that could be
+ configured with one entry per method in the white list file or,
+ better, a single entry for the class in the white list and a single
+ entry for the unavailable method in the black list.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>There is an optional capability to authorise the visibility and
+ usability of fields independently. Thus a field may be visible to
+ certain roles but not editable. In order to configure this against a
+ authorization a flag must be added as follows.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>As a tool for helping to configure the initial security settings
+ there is a 'learn' property.</para>
+
+ <programlisting format="linespecific">isis.authorization.learn=true</programlisting>
+
+ <para>When this is present and set, all methods will be authorised for
+ all roles. However as each method is accessed through the user
+ interface authorization will be configured for that method and the
+ current role. Configuration will be saved in either the file (saved on
+ shutdown), database table or LDAP security settings depending upon the
+ reflector setup.</para>
+
+ <para>The settings can then be modified to conform to the required
+ security settings.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
+ </sect1>
</chapter>
<chapter>
Modified: incubator/isis/trunk/alternatives/security/ldap/src/docbkx/guide/isis-ldap-security.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/alternatives/security/ldap/src/docbkx/guide/isis-ldap-security.xml?rev=1039874&r1=1039873&r2=1039874&view=diff
==============================================================================
--- incubator/isis/trunk/alternatives/security/ldap/src/docbkx/guide/isis-ldap-security.xml (original)
+++ incubator/isis/trunk/alternatives/security/ldap/src/docbkx/guide/isis-ldap-security.xml Sun Nov 28 12:49:00 2010
@@ -17,21 +17,26 @@
specific language governing permissions and limitations
under the License.
-->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
<book>
<bookinfo>
<title><?eval ${docbkxGuideTitle}?></title>
+
<subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
<releaseinfo><?eval ${project.version}?></releaseinfo>
<authorgroup>
<author>
<firstname>Robert</firstname>
+
<surname>Matthews</surname>
</author>
+
<author>
<firstname>Kevin</firstname>
+
<surname>Meyer</surname>
</author>
</authorgroup>
@@ -54,10 +59,9 @@
rapidly develop domain-driven applications following the <ulink
url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
pattern. It is made up of a core framework plus a number of alternate
- implementations, and supports various viewers and object stores. Apache
- Isis is hosted at the
- <ulink url="http://incubator.apache.org/isis">Apache Foundation</ulink>,
- and is licensed under <ulink
+ implementations, and supports various viewers and object stores. Apache
+ Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+ Foundation</ulink>, and is licensed under <ulink
url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
License v2</ulink>.</para>
@@ -77,6 +81,181 @@
<title>***</title>
<para><emphasis>*** yada yada</emphasis></para>
+
+ <sect2>
+ <title>Authentication through an LDAP server</title>
+
+ <para>To authenticate through LDAP set</para>
+
+ <programlisting format="linespecific">isis.authentication=ldap</programlisting>
+
+ <para>LDAP needs a URL for the server and a 'dn' of the root of the
+ users on the server. For example,</para>
+
+ <programlisting format="linespecific">isis.authentication.ldap.dn= dc=isis, dc=org </programlisting>
+
+ <programlisting format="linespecific">isis.authentication.ldap.server=ldap://localhost:10389</programlisting>
+
+ <para>The logon password check will be on uid='username', <dn> -
+ For example, attempting to logon with user 'sven' with the above
+ settings will check against the server on localhost, port = 10389,
+ uid=sven, dc=isis, dc=org, using the password in the standard <literal
+ moreinfo="none">userpassword</literal> attribute in that entry. Once
+ logged in, roles will be picked up from cn='rolename' where
+ objectclass =organizationalRole in child entries of the user
+ entry.</para>
+ </sect2>
+
+ <sect2>
+ <title>Authorization through LDAP server</title>
+
+ <para>To enable authorization by LDAP server include facet for
+ authorization and specifying the <literal
+ moreinfo="none">ldap</literal> implementation for
+ authorization.</para>
+
+ <programlisting format="linespecific">isis.reflector.facets.include=\
+ org.apache.isis.runtime.authorization.standard.AuthorizationFacetFactoryImpl
+isis.authorization=ldap</programlisting>
+
+ <para>With LDAP authorization the current user's role will be
+ authorised against an entry in the LDAP server for each method
+ possibly available to them. The URL of the server is obtained from the
+ same property as for authentication.</para>
+
+ <para>The authorization entries should exist under a DN configured in
+ the property file. For example.</para>
+
+ <programlisting format="linespecific">isis.authorization.ldap.application.dn= cn=expenses, dc=apps, dc=isis, dc=org </programlisting>
+
+ <para>This will be checked anonymously.</para>
+
+ <para>Entries to be matched against should exist under this dn.
+ Expected configuration is a hierarchy of class, method and parameters.
+ The cn of each entry is expected to be the fully qualified class name,
+ method or parameter list ('()' for an empty parameter list). If an
+ entry has a 'uniquemember' attribute equal to 'role' then that entry
+ and all sub-entries are authorised.</para>
+
+ <para>For example</para>
+
+ <para>DN:
+ cn=com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate,
+ cn=expenses, dc=apps, dc=isis, dc=org</para>
+
+ <para>with uniquemember = role1 will authorise all members of <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate</literal>
+ for users with role1.</para>
+
+ <para>DN: cn=(com.isisgroup.expenses.claimant.Claimant,
+ java.lang.String),</para>
+
+ <para>cn=createNewClaim,
+ cn=com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate,
+ cn=expenses, dc=apps, dc=isis, dc=org</para>
+
+ <para>with uniquemember = role1 will authorise the <literal
+ moreinfo="none">createNewClaim(com.isisgroup.expenses.claimant.Claimant,
+ String)</literal> member of <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate</literal>
+ for users with role1.</para>
+ </sect2>
+
+ <sect2>
+ <title>Authorization through LDAP server</title>
+
+ <para>To enable authorization by LDAP server include facet for
+ authorization and specifying the <literal
+ moreinfo="none">ldap</literal> implementation for
+ authorization.</para>
+
+ <programlisting format="linespecific">isis.reflector.facets.include=\
+ org.apache.isis.runtime.authorization.standard.AuthorizationFacetFactoryImpl
+isis.authorization=ldap</programlisting>
+
+ <para>With LDAP authorization the current user's role will be
+ authorised against an entry in the LDAP server for each method
+ possibly available to them. The URL of the server is obtained from the
+ same property as for authentication.</para>
+
+ <para>The authorization entries should exist under a DN configured in
+ the property file. For example.</para>
+
+ <programlisting format="linespecific">isis.authorization.ldap.application.dn= cn=expenses, dc=apps, dc=isis, dc=org </programlisting>
+
+ <para>This will be checked anonymously.</para>
+
+ <para>Entries to be matched against should exist under this dn.
+ Expected configuration is a hierarchy of class, method and parameters.
+ The cn of each entry is expected to be the fully qualified class name,
+ method or parameter list ('()' for an empty parameter list). If an
+ entry has a 'uniquemember' attribute equal to 'role' then that entry
+ and all sub-entries are authorised.</para>
+
+ <para>For example</para>
+
+ <para>DN:
+ cn=com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate,
+ cn=expenses, dc=apps, dc=isis, dc=org</para>
+
+ <para>with uniquemember = role1 will authorise all members of <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate</literal>
+ for users with role1.</para>
+
+ <para>DN: cn=(com.isisgroup.expenses.claimant.Claimant,
+ java.lang.String),</para>
+
+ <para>cn=createNewClaim,
+ cn=com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate,
+ cn=expenses, dc=apps, dc=isis, dc=org</para>
+
+ <para>with uniquemember = role1 will authorise the <literal
+ moreinfo="none">createNewClaim(com.isisgroup.expenses.claimant.Claimant,
+ String)</literal> member of <literal
+ moreinfo="none">com.isisgroup.expenses.services.hibernate.ClaimRepositoryHibernate</literal>
+ for users with role1.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>There is an optional capability to authorise the visibility and
+ usability of fields independently. Thus a field may be visible to
+ certain roles but not editable. In order to configure this against a
+ authorization a flag must be added as follows.</para>
+
+ <para></para>
+
+ <para>Add a flags attribute to the entry with the role. If it's set to
+ 'rw' editing will be allowed, any other value (typically 'ro') will
+ disallow editing.</para>
+
+ <para>In each case absence of the flag will mean that visibility and
+ usability and are always the same.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>As a tool for helping to configure the initial security settings
+ there is a 'learn' property.</para>
+
+ <programlisting format="linespecific">isis.authorization.learn=true</programlisting>
+
+ <para>When this is present and set, all methods will be authorised for
+ all roles. However as each method is accessed through the user
+ interface authorization will be configured for that method and the
+ current role. Configuration will be saved in either the file (saved on
+ shutdown), database table or LDAP security settings depending upon the
+ reflector setup.</para>
+
+ <para>The settings can then be modified to conform to the required
+ security settings.</para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
</sect1>
</chapter>