Reorganized quickstart tutorial.

2 files changed, 171 insertions, 0 deletions

diff --git a/demos/quickstart/protected/pages/Advanced/Auth.page b/demos/quickstart/protected/pages/Advanced/Auth.page
new file mode 100644
index 00000000..ec876f54
--- /dev/null
+++ b/demos/quickstart/protected/pages/Advanced/Auth.page
@@ -0,0 +1,92 @@
+<com:TContent ID="body" >

+

+<h1>Authentication and Authorization</h1>

+<p>

+Authentication is a process of verifying whether someone is who he claims he is. It usually involves a username and a password, but may include any other methods of demonstrating identity, such as a smart card, fingerprints, etc.

+</p>

+<p>

+Authorization is finding out if the person, once identified, is permitted to manipulate specific resources. This is usually determined by finding out if that person is of a particular role that has access to the resources.

+</p>

+

+<h2>How PRADO Auth Framework Works</h2>

+<p>

+PRADO provides an extensible authentication/authorization framework. As described in <a href="?page=Fundamentals.Applications">application lifecycles</a>, <tt>TApplication</tt> reserves several lifecycles for modules responsible for authentication and authorization. PRADO provides the <tt>TAuthManager</tt> module for such purposes. Developers can plug in their own auth modules easily. <tt>TAuthManager</tt> is designed to be used together with <tt>TUserManager</tt> module, which implements a read-only user database.

+</p>

+<p>

+When a page request occurs, <tt>TAuthManager</tt> will try to restore user information from session. If no user information is found, the user is considered as an anonymous or guest user. To facilitate user identity verification, <tt>TAuthManager</tt> provides two commonly used methods: <tt>login()</tt> and <tt>logout()</tt>. A user is logged in (verified) if his username and password entries match a record in the user database managed by <tt>TUserManager</tt>. A user is logged out if his user information is cleared from session and he needs to re-login if he makes new page requests.

+</p>

+<p>

+During <tt>Authorization</tt> application lifecycle, which occurs after <tt>Authentication</tt> lifecycle, <tt>TAuthManager</tt> will verify if the current user has access to the requested page according to a set of authorization rules. The authorization is role-based, i.e., a user has access to a page if 1) the page explicitly states that the user has access; 2) or the user is of a particular role that has access to the page. If the user does not have access to the page, <tt>TAuthManager</tt> will redirect user browser to the login page which is specified by <tt>LoginPage</tt> property.

+</p>

+

+<h2>Using PRADO Auth Framework</h2>

+<p>

+To enable PRADO auth framework, add the <tt>TAuthManager</tt> module and <tt>TUserManager</tt> module to <a href="?page=Configurations.AppConfig">application configuration</a>,

+</p>

+<com:TTextHighlighter Language="xml" CssClass="source">

+&lt;service id="page" class="TPageService"&gt;

+  &lt;modules&gt;

+    &lt;module id="auth" class="System.Security.TAuthManager"

+               UserManager="users" LoginPage="UserLogin" /&gt;

+    &lt;module id="users" class="System.Security.TUserManager"

+               PasswordMode="Clear"&gt;

+      &lt;user name="demo" password="demo" /&gt;

+      &lt;user name="admin" password="admin" /&gt;

+    &lt;/module&gt;

+  &lt;/modules&gt;

+&lt;/service&gt;

+</com:TTextHighlighter>

+<p>

+In the above, the <tt>UserManager</tt> property of <tt>TAuthManager</tt> is set to the <tt>users</tt> module which is <tt>TUserManager</tt>. Developers may replace it with a different user management module that is derived from <tt>TUserManager</tt>.

+</p>

+<p>

+Authorization rules for pages are specified in <a href="?page=Configurations.PageConfig">page configurations</a> as follows,

+</p>

+<com:TTextHighlighter Language="xml" CssClass="source">

+&lt;authorization&gt;

+    &lt;allow pages="PageID1,PageID2"

+              users="User1,User2"

+              roles="Role1" /&gt;

+    &lt;deny pages="PageID1,PageID2"

+              users="?"

+              verb="post" /&gt;

+&lt;/authorization&gt;

+</com:TTextHighlighter>

+<p>

+An authorization rule can be either an <tt>allow</tt> rule or a <tt>deny</tt> rule. Each rule consists of four optional properties:

+</p>

+<ul>

+<li><tt>pages</tt> - list of comma-separated page names that this rule applies to. If empty or not set, this rule will apply to all pages under the current directory and all its subdirectories recursively.</li>

+<li><tt>users</tt> - list of comma-separated user names that this rule applies to. A character * refers to all users including anonymous/guest user. And a character ? refers to anonymous/guest user.</li>

+<li><tt>roles</tt> - list of comma-separated user roles that this rule applies to.</li>

+<li><tt>verb</tt> - page access method that this rule applies to. It can be either <tt>get</tt> or <tt>post</tt>. If empty or not set, the rule applies to both methods.</li>

+</ul>

+

+<p>

+When a page request is being processed, a list of authorization rules may be available. However, only the <i>first effective</i> rule <i>matching</i> the current user will render the authorization result.

+</p>

+<ul>

+<li>Rules are ordered bottom-up, i.e., the rules contained in the configuration of current page folder go first. Rules in configurations of parent page folders go after.</li>

+<li>A rule is effective if the current page is in the listed pages of the rule AND the current user action (<tt>get</tt> or <tt>post</tt>) is in the listed actions.</li>

+<li>A rule matching occurs if the current user name is in the listed user names of an <i>effective</i> rule OR if the user's role is in the listed roles of that rule.</li>

+<li>If no rule matches, the user is authorized.</li>

+</ul>

+<p>

+In the above example, anonymous users will be denied from posting to <tt>PageID1</tt> and <tt>PageID2</tt>, while <tt>User1</tt> and <tt>User2</tt> and all users of role <tt>Role1</tt> can access the two pages (in both <tt>get</tt> and <tt>post</tt> methods).

+</p>

+

+<h2>Using <tt>TUserManager</tt></h2>

+<p>

+As aforementioned, <tt>TUserManager</tt> implements a read-only user database. The user information are specified in either application configuration or an external XML file.

+</p>

+<p>

+We have seen in the above example that two users are specified in the application configuration. Complete syntax of specifying the user and role information is as follows,

+</p>

+<com:TTextHighlighter Language="xml" CssClass="source">

+&lt;user name="demo" password="demo" roles="demo,admin" /&gt;

+&lt;role name="admin" users="demo,demo2" /&gt;

+</com:TTextHighlighter>

+<p>

+where the <tt>roles</tt> attribute in <tt>user</tt> element is optional. User roles can be specified in either the <tt>user</tt> element or in a separate <tt>role</tt> element.

+</p>

+</com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/Advanced/Security.page b/demos/quickstart/protected/pages/Advanced/Security.page
new file mode 100644
index 00000000..b6de7251
--- /dev/null
+++ b/demos/quickstart/protected/pages/Advanced/Security.page
@@ -0,0 +1,79 @@
+<com:TContent ID="body" >

+

+<h1>Security</h1>

+

+<h2>Viewstate Protection</h2>

+<p>

+Viewstate lies at the heart of PRADO. Viewstate represents data that can be used to restore pages to the state that is last seen by end users before making the current request. By default, PRADO uses hidden fields to store viewstate information.

+</p>

+<p>

+It is extremely important to ensure that viewstate is not tampered by end users. Without protection, malicious users may inject harmful code into viewstate and unwanted instructions may be performed when page state is being restored on server side.

+</p>

+<p>

+To prevent viewstate from being tampered, PRADO enforces viewstate HMAC (Keyed-Hashing for Message Authentication) check before restoring  viewstate. Such a check can detect if the viewstate has been tampered or not by end users. Should the viewstate is modified, PRADO will stop restoring the viewstate and return an error message.

+</p>

+<p>

+HMAC check requires a private key that should be secret to end users. Developers can either manually specify a key or let PRADO automatically generate a key. Manually specified key is useful when the application runs on a server farm. To do so, configure <tt>TSecurityManager</tt> in application configuration,

+</p>

+<com:TTextHighlighter Language="xml" CssClass="source">

+&lt;modules&gt;

+    &lt;module id="security"

+        class="TSecurityManager"

+        ValidationKey="my private key" /&gt;

+&lt;/modules&gt;

+</com:TTextHighlighter>

+<p>

+HMAC check does not prevent end users from reading the viewstate content. An added security measure is to encrypt the viewstate information so that end users cannot decipher it. To enable viewstate encryption, set the <tt>EnableStateEncryption</tt> of pages to true. This can be done in <a href="?page=Configurations.PageConfig">page configurations</a> or in page code. Note, encrypting viewstate may degrade the application performance. A better strategy is to store viewstate on the server side, rather than the default hidden field.

+</p>

+

+<h2>Cross Site Scripting Prevention</h2>

+<p>

+Cross site scripting (also known as XSS) occurs when a web application gathers malicious data from a user. Often attackers will inject JavaScript, VBScript, ActiveX, HTML, or Flash into a vulnerable application to fool other application users and gather data from them. For example, a poorly design forum system may display user input in forum posts without any checking. An attacker can then inject a piece of malicious JavaScript code into a post so that when other users read this post, the JavaScript runs unexpectedly on their computers.

+</p>

+<p>

+One of the most important measures to prevent XSS attacks is to check user input before displaying them. One can do HTML-encoding with the user input to achieve this goal. However, in some situations, HTML-encoding may not be preferrable because it disables all HTML tags.

+</p>

+<p>

+PRADO incorporates the work of <a href="http://pixel-apes.com/safehtml/">SafeHTML</a> and provides developers with a useful component called <tt>TSafeHtml</tt>. By enclosing content within a <tt>TSafeHtml</tt> component tag, the enclosed content are ensured to be safe to end users. In addition, the commonly used <tt>TTextBox</tt> has a <tt>SafeText</tt> property which contains user input that are ensured to be safe if displayed directly to end users.

+</p>

+

+<h2>Cookie Attack Prevention</h2>

+<p>

+Protecting cookies from being attacked is of extreme important, as session IDs are commonly stored in cookies. If one gets hold of a session ID, he essentially owns all relevant session information.

+</p>

+<p>

+There are several countermeasures to prevent cookies from being attacked.

+</p>

+<ul>

+  <li>An application can use SSL to create a secure communication channel and only pass the authentication cookie over an HTTPS connection. Attackers are thus unable to decipher the contents in the transferred cookies.</li>

+  <li>Expire sessions appropriately, including all cookies and session tokens, to reduce the likelihood of being attacked.</li>

+  <li>Prevent <a href="?page=Security.XSS">cross-site scripting (XSS)</a> which causes arbitrary code to run in a user's browser and expose his cookies.</li>

+  <li>Validate cookie data and detect if they are altered.</li>

+</ul>

+<p>

+Prado implements a cookie validation scheme that prevents cookies from being modified. In particular, it does HMAC check for the cookie values if cookie validation is enable.

+</p>

+<p>

+Cookie validation is disabled by default. To enable it, configure the <tt>THttpRequest</tt> module as follows,

+</p>

+<com:TTextHighlighter Language="xml" CssClass="source">

+<modules>

+  <module id="request" class="THttpRequest" EnableCookieValidation="true" />

+</modules>

+</com:TTextHighlighter>

+<p>

+To make use of cookie validation scheme provided by Prado, you also need to retrieve cookies through the <tt>Cookies</tt> collection of <tt>THttpRequest</tt> by using the following PHP statements,

+</p>

+<com:TTextHighlighter CssClass="source">

+foreach($this->Request->Cookies as $cookie)

+    // $cookie is of type THttpCookie

+</com:TTextHighlighter>

+<p>

+To send cookie data encoded with validation information, create new <tt>THttpCookie</tt> objects and add them to the <tt>Cookies</tt> collection of <tt>THttpResponse</tt>,

+</p>

+<com:TTextHighlighter CssClass="source">

+$cookie=new THttpCookie($name,$value);

+$this->Response->Cookies[]=$cookie;

+</com:TTextHighlighter>

+

+</com:TContent>
\ No newline at end of file