[cvs] expresso commit by lhamel: add info for public-to-private redirect to

[JCorporate Ltd]

Log Message:
-----------
add info for public-to-private redirect to referral URL

Modified Files:
--------------
    expresso/expresso-web/expresso/doc/edg:
        security.xml

Revision Data
-------------
Index: security.xml
===================================================================
RCS file: /home/javacorp/.cvs/expresso/expresso/expresso-web/expresso/doc/edg/security.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -Lexpresso-web/expresso/doc/edg/security.xml -Lexpresso-web/expresso/doc/edg/security.xml -u -r1.28 -r1.29
--- expresso-web/expresso/doc/edg/security.xml
+++ expresso-web/expresso/doc/edg/security.xml
@@ -122,11 +122,62 @@
 be written, remove the checkbox from the GUI. During repeated access, first
 the session is checked, and if that Authentication fails, the cookie is
 attempted. See com.jcorporate.expresso.core.servlet.CheckLogin for details.
-Also, if a user tries to access a page and fails because of a lack of login,
+        </para>
+        <para>
+            Also, if a user tries to access a page and fails because of a lack of login,
 Expresso from version 5.0 will automatically reroute the request to a login
 page, and subsequent to a successful login, reroute to the user's original
-destination.
-		</para>
+destination. This is useful when your webapp is 100% privileged--has no public
+            controllers. You can send a URL in email, and when someone clicks on it,
+            they will see the login 'in transit' before seeing the intended page.
+            However, if your webapp has, say, 50% public pages (no login needed),
+            then a user may already be on the site and then want to log in.
+            In that case, the user will probably access the login page directly,
+            clicking on a link to 'login',  rather than 'in transit' on the way
+            to a protected URL. You probably want to send the user back to the
+            same page, just this time with a privileged, logged-in view. You can
+            accomplish this by subclassing the SimpleLoginController and adding
+            some logic AFTER the state 'promptLogin' to do something like what follows:
+
+            <programlisting>
+            ServletControllerRequest sr = (ServletControllerRequest) request;
+            HttpServletRequest hreq = (HttpServletRequest) sr.getServletRequest();
+
+            String referrer = hreq.getHeader("Referer"); // nb: misspelling is part of standard
+
+            if (referrer != null) {
+                // this test for "/myapp/" is a little weak, but we don't know the server host name;
+                boolean isLocal = referrer.indexOf("/myapp/") != -1;
+                if (isLocal) {
+                    // do we already have a destination?
+                    boolean hasDestAlready = false;
+
+                    // check session
+                    PersistentSession session = request.getSession();
+                    if (session != null) {
+                        SerializableString originalURL = (SerializableString) session.getPersistentAttribute(
+                        ExpressoConstants.CONTROLLER_ORIGINAL_URL_KEY);
+
+                        if (originalURL != null) {
+                            hasDestAlready = true;
+                        }
+                     }
+
+                    // check params
+                    if (!hasDestAlready) {
+                        hasDestAlready = request.getParameter("next") != null;
+                    }
+
+                    // ok, now we know
+                    if (!hasDestAlready) {
+                        // set up destination in session
+                        session.setPersistentAttribute(ExpressoConstants.CONTROLLER_ORIGINAL_URL_KEY, referrer);
+                    }
+                } // local referrer
+            }
+            </programlisting>
+
+        </para>
 		<para>
 Authorization checks pertain to every user access if the Expresso application
 subclasses (Row)SecuredDBObject and DBController. In other words, if your
@@ -849,9 +900,16 @@
 only by group members. Here is a code snippet for using permissions to
 determine what to show:
 			</para>
-			<programlisting><![CDATA[// add link to edit if we have privileges if (myObject.canRequesterWrite()) { Transition trans = new Transition( PROMPT_EDIT_SCORING_MATRIX, "Edit matrix", MatrixAction.class, PROMPT_EDIT_SCORING_MATRIX); trans.addParam(Node.NODE_ID, nodeId); response.add(trans); }]]></programlisting>
+			<programlisting>
+			// add link to edit if we have privileges
+			if (myObject.canRequesterWrite()) {
+                Transition trans = new Transition( PROMPT_EDIT_SCORING_MATRIX, "Edit matrix", MatrixAction.class, PROMPT_EDIT_SCORING_MATRIX);
+                trans.addParam(Node.NODE_ID, nodeId);
+                response.add(trans);
+            }
+			</programlisting>
 		</sect2>
-	</sect1>
+    </sect1>
 	<sect1>
 		<title>Cookie Encryption</title>
 		<para>