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 > Authentication - Framework
Date Wed, 25 Jan 2012 03:10:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Authentication+-+Framework">Authentication
- Framework</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~justinedelson">Justin
Edelson</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >  # If no handler returns a non-{{null}}
result, the request may be handled anonymously. In these cases, an empty {{AuthenticationInfo}}
object is passed to any {{AuthenticationInfoPostProcessor}} services. <br>  # (Try to)
log into the repository either with the provided credentials or anonymously. <br></td></tr>
            <tr><td class="diff-changed-lines" ># If there were credentials provided
and the login was successful, a login event is posted *if* the {{AuthenticationInfo}} object
contains a non-null object with the key {{$$auth.info.login$$}} ({{AuthConstants.AUTH_INFO_LOGIN}}).
This event is posted with the topic {{org/apache/sling/auth/core/Authenticator/LOGIN}}. (added
in Sling Auth Core <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">1.0.4)</span>
<span class="diff-added-words"style="background-color: #dfd;">1.1.0)</span> <br></td></tr>
            <tr><td class="diff-unchanged" >  # Set request attributes listed
below. <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Authentication-Framework-Framework"></a>Framework</h1>

<p>The core piece of functionality with respect to authentication in Sling is contained
in the Sling Commons Auth bundle. This bundle provides the API for Sling and Sling applications
to make use of authentication.</p>

<p>This support encompasses three parts:</p>

<ul>
	<li>The <tt>AuthenticationSupport</tt> service provided by the <tt>SlingAuthenticator</tt>
class. This service can be used by implementations of the OSGi <tt>HttpContext</tt>
interface to delegate authentication.</li>
	<li>The <tt>Authenticator</tt> service also provided by the <tt>SlingAuthenticator</tt>
class. This service may be used by Sling Applications to help clients login and logout.</li>
	<li>The <tt>AuthenticationHandler</tt> service interface. These services
may be implemented by extensions to support various ways for transporting credentials from
clients to the Sling server.</li>
</ul>


<p>This page describes how the <tt>SlingAuthenticator</tt> class provides
the <tt>AuthenticationSupport</tt> and  <tt>Authenticator</tt> services.
For a description of the <tt>AuthenticationHandler</tt> service interface and
the interaction between the <tt>SlingAuthenticator</tt> and the <tt>AuthenticationHandler</tt>
services refer to the <a href="/confluence/display/SLINGxSITE/Authentication+-+AuthenticationHandler"
title="Authentication - AuthenticationHandler">AuthenticationHandler</a> page.</p>

<p>The <tt>SlingAuthenticator</tt> class is an internal class of the <tt>org.apache.sling.commons.auth</tt>
bundle and implements the <tt>Authenticator</tt> and <tt>AuthenticationSupport</tt>
services.</p>


<h2><a name="Authentication-Framework-AuthenticationSupport"></a>AuthenticationSupport</h2>

<p>The <tt>AuthenticationSupport</tt> service interface defines a single
method: <tt>handleSecurity</tt>. This method is intended to be called by the <tt>handleSecurity</tt>
method of any <tt>HttpContext</tt> implementation wishing to make use of the Sling
Authentication Framework.</p>

<p>The Sling Authenticator implementation selects an <tt>AuthenticationHandler</tt>
service appropriate for the request and calls the <tt>AuthenticationHandler.extractCredentials</tt>
method to extract the credentials from the request. If no credentials could be extracted,
the Sling Authenticator either admits the request as an anonymous request or requests authentication
from the client by calling its own <tt>login</tt> method.</p>


<p>The implementation follows this algorithm:</p>

<ol>
	<li>Select one or more <tt>AuthenticationHandler</tt> for the request according
to the request URL's scheme and authorization part.</li>
	<li>Call the <tt>extractCredentials</tt> method of each authentication
handler, where the order of handler call is defined by the length of the registered path:
handlers registered with longer paths are called before handlers with shorter paths. The goal
is to call the handlers in order from longest request path match to shortest match. Handlers
not matching the request path at all are not called.</li>
	<li>The first handler returning a non-<tt>null</tt> <tt>AuthenticationInfo</tt>
result "wins" and the result is used for authentication.</li>
	<li>If any <tt>AuthenticationInfoPostProcessor</tt> services are registered,
the <tt>AuthenticationInfo</tt> object is passed to their <tt>postProcess()</tt>
method.</li>
	<li>If no handler returns a non-<tt>null</tt> result, the request may be
handled anonymously. In these cases, an empty <tt>AuthenticationInfo</tt> object
is passed to any <tt>AuthenticationInfoPostProcessor</tt> services.</li>
	<li>(Try to) log into the repository either with the provided credentials or anonymously.</li>
	<li>If there were credentials provided and the login was successful, a login event
is posted <b>if</b> the <tt>AuthenticationInfo</tt> object contains
a non-null object with the key <tt>$$auth.info.login$$</tt> (<tt>AuthConstants.AUTH_INFO_LOGIN</tt>).
This event is posted with the topic <tt>org/apache/sling/auth/core/Authenticator/LOGIN</tt>.
(added in Sling Auth Core 1.1.0)</li>
	<li>Set request attributes listed below.</li>
</ol>


<p>Extracting the credentials and trying to login to the repository may yield the following
results:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> Credentials </td>
<td class='confluenceTd'> Login </td>
<td class='confluenceTd'> Consequence </td>
</tr>
<tr>
<td class='confluenceTd'> present </td>
<td class='confluenceTd'> successfull </td>
<td class='confluenceTd'> Continue with an authenticated request </td>
</tr>
<tr>
<td class='confluenceTd'> present </td>
<td class='confluenceTd'> failed </td>
<td class='confluenceTd'> Select <tt>AuthenticationHandler</tt> and call
<tt>requestCredentials</tt> method </td>
</tr>
<tr>
<td class='confluenceTd'> missing </td>
<td class='confluenceTd'> anonymous allowed </td>
<td class='confluenceTd'> Continue with a non authenticated request using anonymous
access to the repository </td>
</tr>
<tr>
<td class='confluenceTd'> missing </td>
<td class='confluenceTd'> anonymous forbidden </td>
<td class='confluenceTd'> Select <tt>AuthenticationHandler</tt> and call
<tt>requestCredentials</tt> method </td>
</tr>
</tbody></table>
</div>


<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>Only one <tt>AuthenticationHandler</tt>
is able to provide credentials for a given request. If the credentials provided by the handler
cannot be used to login to the repository, authentication fails and no further <tt>AuthenticationHandler</tt>
is consulted.</td></tr></table></div>


<h4><a name="Authentication-Framework-RequestAttributesonSuccessfulLogin"></a>Request
Attributes on Successful Login</h4>

<p>The <tt>handleSecurity</tt> method gets credentials from the <tt>AuthenticationHandler</tt>
and logs into the JCR repository using those credentials. If the login is successful, the
<tt>SlingAuthenticator</tt> sets the following request attributes:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Attribute </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.osgi.service.http.authentication.remote.user</tt>
</td>
<td class='confluenceTd'> The user ID of the JCR Session. This attribute is used by
the HTTP Service implementation to implement the <tt>HttpServletRequest.getRemoteUser</tt>
method. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.osgi.service.http.authentication.type</tt>
</td>
<td class='confluenceTd'> The authentication type defined by the <tt>AuthenticationHandler</tt>.
This attribute is used by the HTTP Service implementation to implement the <tt>HttpServletRequest.getAuthType</tt>
method. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.auth.ResourceResolver</tt>
</td>
<td class='confluenceTd'> The <tt>ResourceResolver</tt> created from the
credentials and the logged in JCR Session. This attribute may be used by servlets to access
the repository. Namely the <tt>SlingMainServlet</tt> uses this request attribute
to provide the <tt>ResourceResolver</tt> to handle the request. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>javax.jcr.Session</tt> </td>
<td class='confluenceTd'> The JCR Session. This attribute is for backwards compatibility
only. <b>Its use is deprecated and the attribute will be removed in future versions</b>.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.auth.spi.AuthenticationInfo</tt>
</td>
<td class='confluenceTd'> The <tt>AuthenticationInfo</tt> object produced
from the <tt>AuthenticationHandler</tt>. </td>
</tr>
</tbody></table>
</div>


<p><b>NOTE</b>: Do <em>NOT</em> use the <tt>javax.jcr.Session</tt>
request attribute in your Sling applications. This attribute must be considered implementation
specific to convey the JCR Session to the <tt>SlingMainServlet</tt>. In future
versions of the Sling Commons Auth bundle, this request attribute will not be present anymore.
To get the JCR Session for the current request adapt the request's resource resolver to a
JCR Session:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Session session = request.getResourceResolver().adaptTo(Session.class);
</pre>
</div></div>


<h4><a name="Authentication-Framework-AnonymousLogin"></a>Anonymous Login</h4>

<p>The <tt>SlingAuthenticator</tt> provides high level of control with respect
to allowing anonymous requests or requiring authentication up front:</p>

<ul>
	<li>Global setting of whether anonymous requests are allowed or not. This is the value
of the <em>Allow Anonymous Access</em> (<tt>auth.annonymous</tt>)
property of the <tt>SlingAuthenticator</tt> configuration. This property is supported
for backwards compatibility and defaults to <tt>true</tt> (allowing anonymous
access).</li>
	<li>Specific configuration per URL. The <em>Authentication Requirements</em>
(<tt>sling.auth.requirements</tt>) property of the <tt>SlingAuthenticator</tt>
configuration may provide a list of URLs for which authentication may be required or not:
Any entry prefixed with a dash <tt>-</tt> defines a subtree for which authentication
is not required. Any entry not prefixed with a dash or prefixed with a plus <tt>+</tt>
defines a subtree for which authentication is required up front and thus anonymous access
is not allowed. This list is empty by default.</li>
	<li>Any OSGi service may provide a <tt>sling.auth.requirements</tt> registration
property which is used to dynamically extend the authentication requirements from the <em>Authentication
Requirements</em> configuration. This may for example be set by <tt>AuthenticationHandler</tt>
implementations providing a login form to ensure access to the login form does not require
authentication. The value of this property is a single string, an array of strings or a Collection
of strings and is formatted in the same way as the <em>Authentication Requirements</em>
configuration property.</li>
</ul>


<p>The URLs set on the <em>Authentication Requirements</em> configuration
property or the <tt>sling.auth.requirements</tt> service registration property
can be absolute paths or URLs like the <tt>path</tt> service registration property
of <tt>AuthenticationHandler</tt> services. This allows the limitation of this
setup to certain requests by scheme and/or virtual host address.</p>


<p><b>Examples</b></p>

<ul>
	<li>The <tt>LoginServlet</tt> contained in the Commons Auth bundle registers
itself with the service registration property <tt>sling.auth.requirements = "-/system/sling/login"</tt>
to ensure the servlet can be accessed without requiring authentication.</li>
</ul>


<ul>
	<li>An authentication handler may register itself with the service registration property
<tt>sling.auth.requirements = "-/apps/sample/loginform"</tt> to ensure the login
form can be rendered without requiring authentication.</li>
</ul>




<h2><a name="Authentication-Framework-Authenticatorimplementation"></a>Authenticator
implementation</h2>

<p>The implementation of the <tt>Authenticator</tt> interface is similar
for both methods:</p>

<p><b><tt>login</tt></b></p>

<ol>
	<li>Select one or more <tt>AuthenticationHandler</tt> for the request according
to the request URL's scheme and authorization part.</li>
	<li>Call the <tt>requestCredentials</tt> method of each authentication
handler, where the order of handler call is defined by the length of the registered path:
handlers registered with longer paths are called before handlers with shorter paths. The goal
is to call the handlers in order from longest request path match to shortest match. Handlers
not matching the request path at all are not called.</li>
	<li>As soon as the first handlers returns <tt>true</tt>, the process ends
and it is assumed credentials have been requested from the client.</li>
</ol>


<p>The <tt>login</tt> method has three possible exit states:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Exit State </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> Normal </td>
<td class='confluenceTd'> An <tt>AuthenticationHandler</tt> could be selected
to which the login request could be forwarded. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>NoAuthenticationHandlerException</tt> </td>
<td class='confluenceTd'> No <tt>AuthenticationHandler</tt> could be selected
to forward the login request to. In this case, the caller can proceed as appropriate. For
example a servlet, which should just login a user may send back a 403/FORBIDDEN status because
login is not possible. Or a 404/NOT FOUND handler, which tried to login as a fallback, may
continue and send back the regular 404/NOT FOUND response. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>IllegalStateException</tt> </td>
<td class='confluenceTd'> The response has already been committed and the login request
cannot be processed. Normally to request login, the current response must be reset and a new
response has to be prepared. This is only possible if the request has not yet been committed.
</td>
</tr>
</tbody></table>
</div>



<p><b><tt>logout</tt></b></p>
<ol>
	<li>Select one or more <tt>AuthenticationHandler</tt> for the request according
to the request URL's scheme and authorization part.</li>
	<li>Call the <tt>dropCredentials</tt> method of each authentication handler,
where the order of handler call is defined by the length of the registered path: handlers
registered with longer paths are called before handlers with shorter paths. The goal is to
call the handlers in order from longest request path match to shortest match. Handlers not
matching the request path at all are not called.</li>
</ol>


<p>Unlike for the <tt>login</tt> method in the <tt>logout</tt>
method case all <tt>AuthenticationHandler</tt> services selected in the first
step are called. If none can be selected or none can actually handle the <tt>dropCredentials</tt>
request, the <tt>logout</tt> silently returns.</p>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Authentication+-+Framework">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=12845344&revisedVersion=8&originalVersion=7">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Authentication+-+Framework?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message