incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling Website > Form Based AuthenticationHandler
Date Tue, 09 Feb 2010 10:18:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Form+Based+AuthenticationHandler">Form
Based AuthenticationHandler</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="FormBasedAuthenticationHandler-FormBasedAuthenticationHandler"></a>Form
Based AuthenticationHandler</h1>

<div class="panel" style="border-width: 1px;"><div class="panelContent">
<p>DRAFT - describing the implementation of the Form Based AuthenticationHandler of
SLING-1116</p>
</div></div>

<div><a href='#FormBasedAuthenticationHandler-AuthenticationHandlerimplementation'>AuthenticationHandler
implementation</a> | <a href='#FormBasedAuthenticationHandler-AuthenticationHandlerFeedbackimplementation'>AuthenticationHandlerFeedback
implementation</a> | <a href='#FormBasedAuthenticationHandler-Phase1%3AFormSubmission'>Phase
1: Form Submission</a> | <a href='#FormBasedAuthenticationHandler-Phase2%3AAuthenticatedRequests'>Phase
2: Authenticated Requests</a> | <a href='#FormBasedAuthenticationHandler-Configuration'>Configuration</a>
| <a href='#FormBasedAuthenticationHandler-SecurityConsiderations'>Security Considerations</a></div>

<p>The Form Based AuthenticationHandler has two authentication phases: The first phase
is presenting a login form to the user and passing the entered user name and password to the
server. The second phase is storing successful authentication in a Cookie or an HTTP Session.</p>

<p>The implementation of the Form Based Authentication handler follows the guidelines
of the Servlet API 2.4 specification for <em>Form Based Authentication</em> in
section SRV.12.5.3. Specifically the following requirements are implemented:</p>

<ul>
	<li>For the initial form submission, the request URL must end with <tt>/j_security_check</tt>
and the user name and password names must be <tt>j_username</tt> and <tt>j_password</tt>,
resp.</li>
	<li>The authentication type as returned by <tt>HttpServletRequest.getAuthType()</tt>
is set to <tt>HttpServletRequest.FORM_AUTH</tt>.</li>
</ul>



<h3><a name="FormBasedAuthenticationHandler-AuthenticationHandlerimplementation"></a>AuthenticationHandler
implementation</h3>


<ul>
	<li><tt>extractCredentials</tt> &#8211; Prepares credentials for the
form entered data or from the Cookie or HTTP Session attribute. Returns <tt>null</tt>
if neither data is provided in the request</li>
	<li><tt>requestCredentials</tt> &#8211; Redirects the client (browser)
to the login form</li>
	<li><tt>dropCredentials</tt> &#8211; Remove the Cookie or remove the
HTTP Session attribute</li>
</ul>



<h3><a name="FormBasedAuthenticationHandler-AuthenticationHandlerFeedbackimplementation"></a>AuthenticationHandlerFeedback
implementation</h3>

<ul>
	<li><tt>authenticationFailed</tt> &#8211; Remove the Cookie or remove
the HTTP Session attribute</li>
	<li><tt>authenticationSucceeded</tt> &#8211; Set (or update) the Cookie
or HTTP Session attribute</li>
</ul>



<h3><a name="FormBasedAuthenticationHandler-Phase1%3AFormSubmission"></a>Phase
1: Form Submission</h3>


<p>The login form submitted in phase 1 to validate the user name and password must be
provided in an HTTP <tt>POST</tt> request to an URL whose last segment is <tt>j_security_check</tt>.
The request is ignored as a form submission if either the method is not <tt>POST</tt>
or the last segment is no <tt>j_security_check</tt>.</p>

<p>The form is rendered by redirecting the client to the URL indicated by the <tt>form.login.form</tt>
configuration parameter. This redirection request may accompanyied by the following parameters:</p>

<ul>
	<li><tt>resource</tt> &#8211; The resource to which the user should
be redirected after successful login. This request parameter should be submitted back to the
server as the <tt>resource</tt> parameter.</li>
	<li><tt>j_reason</tt> &#8211; This parameter indicates the reason for
rendering the login form. If this parameter is set, it is set to <tt>INVALID_CREDENTIALS</tt>
indicating a previous form submission presented invalid username and password or <tt>TIMEOUT</tt>
indicating a login session has timed out. The login form servlet/script can present the user
with an appropriate message.</li>
</ul>


<p>The Form Based Authentication handlers supports the following request parameters
submitted by the HTML form:</p>

<ul>
	<li><tt>j_username</tt> &#8211; Name of the user to authenticate</li>
	<li><tt>j_password</tt> &#8211; Password to authenticate the user</li>
	<li><tt>j_validate</tt> &#8211; Flag indicating whether to just validate
the credentials</li>
	<li><tt>resource</tt> &#8211; The location to go to on successful login</li>
	<li><tt>sling.auth.redirect</tt> &#8211; The location to redirect to
on successful login</li>
</ul>


<p>The <tt>j_username</tt> and <tt>j_password</tt> parameters
are used to create a JCR <tt>SimpleCredentials</tt> object to log into the JCR
Repository.</p>

<p>The <tt>j_validate</tt> parameter may be used to implement login form
submission using AJAX. If this parameter is set to <tt>true</tt> (case-insensitive)
the credentials are used to login and after success or failure to return a status code:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Status </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>200 OK</tt> </td>
<td class='confluenceTd'> Authentication succeeded; credentials are valid for login;
the Cookie or HTTP Session attribute is now set </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>403 FORBIDDEN</tt> </td>
<td class='confluenceTd'> Authentication failed; credentials are invalid for login;
the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared) </td>
</tr>
</tbody></table>

<p>If the <tt>j_validate</tt> parameter is not set or is set to any value
other than <tt>true</tt>, the request processing depends on authentication success
or failure:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Authentication </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> Success </td>
<td class='confluenceTd'> Client is redirected to the authenticated resource; the Cookie
or HTTP Session attribute is now set. </td>
</tr>
<tr>
<td class='confluenceTd'> Failure </td>
<td class='confluenceTd'> The request is redirected to the login form again; the Cookie
or HTTP Session attribute is not set (if it was set, it is now cleared) </td>
</tr>
</tbody></table>

<p>The <tt>resource</tt> and <tt>sling.auth.redirect</tt> parameters
provide similar functionality but with differing historical backgrounds. The <tt>resource</tt>
parameter is based on the <tt>resource</tt> request attribute which is set by
the login servlet to indicate the original target resource the client desired when it was
forced to authenticate. The <tt>sling.auth.redirect</tt> parameter can be used
by clients (applications like cURL or plain HTML forms) to request being redirected after
successful login. If both parameters are set, the <tt>sling.auth.redirect</tt>
parameter takes precedence.</p>

<p>The Form Based AuthenticationHandler contains a <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/formauth/src/main/java/org/apache/sling/formauth/AuthenticationFormServlet.java"
rel="nofollow">default form servlet</a> and <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/formauth/src/main/resources/org/apache/sling/formauth/login.html"
rel="nofollow">HTML form template from</a>.</p>


<h3><a name="FormBasedAuthenticationHandler-Phase2%3AAuthenticatedRequests"></a>Phase
2: Authenticated Requests</h3>


<p>After the successful authentication of the user in phase 1, the authentication state
is stored in a Cookie or an HTTP Session. The stored value is a security token with the following
contents:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
HmacSHA1(securetoken, &lt;securetokennumber&gt;&lt;expirytime&gt;@&lt;userID&gt;)@&lt;securetokennumber&gt;&lt;expirytime&gt;@&lt;userID&gt;
</pre>
</div></div>

<p>The <tt>securetoken</tt> and <tt>securetokennumber</tt> are
related in that an table of secure tokens is maintained where the <tt>securetoken</tt>
is an entry in the table and the <tt>securetokennumber</tt> is the index in of
the token in the table.</p>

<p>The secure tokens are refreshed periodically causing the authentication state stored
in the Cookie or the HTTP Session to be updated peridocally. This periodic update has two
advantages:</p>

<ul>
	<li>Login sessions time out after some period of inactivity: If a request is handled
for an authentication state whose expiry time has passed, the request is considered unauthenticated.</li>
	<li>If a Cookie would be stolen or an HTTP Session be hijacked, the authentication
state expires within a reasonable amount of time to try to prevent stealing the authentication.</li>
</ul>


<p>The authentication state maya be transmitted with a Cookie which is configured as
follows:</p>

<ul>
	<li><b>Cookie Path</b> &#8211; Set to the servlet context path</li>
	<li><b>Domain</b> &#8211; Not expressely set, thus bound to the host
requested by the client</li>
	<li><b>Age</b> &#8211; Set to -1 to indicate a session Cookie</li>
	<li><b>Secure</b> &#8211; Set to the value returned by the <tt>ServletRequest.isSecure()</tt>
method</li>
</ul>


<p>If the authentication state is kept in an HTTP Session the setup of the session ID
cookie is maintained by the servlet container and is outside of the control of the Form Based
AuthenticationHandler.</p>


<h3><a name="FormBasedAuthenticationHandler-Configuration"></a>Configuration</h3>

<p>The Form Based AuthenticationHandler is configured with configuration provided by
the OSGi Configuration Admin Service using the <tt>org.apache.sling.formauth.FormAuthenticationHandler</tt>
service PID.</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>form.login.form</tt> </td>
<td class='confluenceTd'> <tt>/system/sling/form/login</tt> </td>
<td class='confluenceTd'> The URL (without any context path prefix) to redirect the
client to to present the login form. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>form.auth.storage</tt> </td>
<td class='confluenceTd'> <tt>cookie</tt> </td>
<td class='confluenceTd'> The type of storage used to provide the authentication state.
Valid values are <tt>cookie</tt> and <tt>session</tt>. The default
value also applies if any setting other than the supported values is configured. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>form.auth.name</tt> </td>
<td class='confluenceTd'> <tt>sling.formauth</tt> </td>
<td class='confluenceTd'> The name of the Cookie or HTTP Session attribute providing
the authentication state. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>form.auth.timeout</tt> </td>
<td class='confluenceTd'> <tt>30</tt> </td>
<td class='confluenceTd'>The number of minutes after which a login session times out.
This value is used as the expiry time set in the authentication data. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>form.credentials.name</tt> </td>
<td class='confluenceTd'> <tt>sling.formauth</tt> </td>
<td class='confluenceTd'> The name of the <tt>SimpleCredentials</tt> attribute
used to provide the authentication data to the <tt>LoginModulePlugin</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>form.token.file</tt> </td>
<td class='confluenceTd'> <tt>cookie-tokens.bin</tt> </td>
<td class='confluenceTd'> The name of the file used to persist the security tokens.
</td>
</tr>
</tbody></table>

<p><em>Note:</em> The <tt>form.token.file</tt> parameter currently
refers to a file stored in the file system. If the path is a relative path, the file is either
stored in the Authentication Handler bundle private data area or &#8211; if not possible
&#8211; below the location indicated by the <tt>sling.home</tt> framework
property or &#8211; if <tt>sling.home</tt> is not set &#8211; the current
working directory. In the future this file may be store in the JCR Repository to support clustering
scenarios.</p>


<h3><a name="FormBasedAuthenticationHandler-SecurityConsiderations"></a>Security
Considerations</h3>

<p>Form Based Authentication has some limitations in terms of security:</p>

<ol>
	<li>User name and password are transmitted in plain text in the initial form submission.</li>
	<li>The Cookie used to provide the authentication state or the HTTP Session ID may
be stolen.</li>
</ol>


<p>To prevent eavesdroppers from sniffing the credentials or stealing the Cookie a secure
transport layer should be used such as TLS/SSL, VPN or IPSec.</p>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Form+Based+AuthenticationHandler">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=13271672&revisedVersion=6&originalVersion=5">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Form+Based+AuthenticationHandler?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message