You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2012/05/22 11:41:27 UTC
svn commit: r818667 [11/18] - in /websites/staging/sling/trunk/content: ./
authentication/ documentation/ documentation/bundles/
documentation/development/ documentation/getting-started/
documentation/the-sling-engine/ documentation/the-sling-engine/au...
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html Tue May 22 09:41:22 2012
@@ -0,0 +1,274 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - OpenID AuthenticationHandler</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a> » <a href="/documentation/the-sling-engine/authentication.html">Authentication</a> » <a href="/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html">Authentication - AuthenticationHandler</a>
+ </div>
+ <h1>OpenID AuthenticationHandler</h1>
+ <div class="toc">
+<ul>
+<li><a href="#credentials-extraction">Credentials Extraction</a></li>
+<li><a href="#phase-1-form-submission">Phase 1: Form Submission</a></li>
+<li><a href="#configuration">Configuration</a></li>
+<li><a href="#authenticationhandler-implementation">AuthenticationHandler implementation</a><ul>
+<li><a href="#extractcredentials">extractCredentials</a></li>
+<li><a href="#requestcredentials">requestCredentials</a></li>
+<li><a href="#dropcredentials">dropCredentials</a></li>
+</ul>
+</li>
+<li><a href="#authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</a><ul>
+<li><a href="#authenticationfailed">authenticationFailed</a></li>
+<li><a href="#authenticationsucceeded">authenticationSucceeded</a></li>
+</ul>
+</li>
+<li><a href="#integration-with-jackrabbit">Integration with Jackrabbit</a></li>
+<li><a href="#security-considerations">Security Considerations</a></li>
+</ul>
+</div>
+<p>The OpenID Authentication Handler supports authentication of request users using the <a href="">OpenID</a> authentication protocol. If the user has successfully authenticated with his OpenID provider a signed OpenID identity is further used to identify the user.</p>
+<p>Since generally an OpenID identity is an URL and URLs may not be used as JCR user names, an association mechanism is used by the OpenID authentication handler to associate an OpenID identity with an existing JCR user: The OpenID identity URL is set as the value of a JCR user property. When a user authenticates with his OpenID identity the matching user searched for by looking for a match in this property.</p>
+<p><em>NOTE:</em> This association currently only works with Jackrabbit (or Jackrabbit based repositories) because user management is not part of the JCR 2 specification and the OpenID authentication handler uses the Jackrabbit <code>UserManager</code> to find users by a user property value.</p>
+<p>The OpenID Authentication Handler is maintained in the <a href="">Sling SVN</a></p>
+<h3 id="credentials-extraction">Credentials Extraction</h3>
+<p>Theoretically each request with the <code>openid_identifier</code> request parameter set may initiate an OpenID authentication process which involves resolving the OpenID provider for the identifier and subsequently authentication with the provider authorizing the Sling instance to use the OpenID identity.</p>
+<p>This initiation, though, is not possible if the request already contains a valid and validated OpenID identifier either set as a request attribute or set in the HTTP Session or the OpenID cookie. In these situations, the current association of a client with an OpenID identity must first be removed by logging out, e.g. by requesting <code>/system/sling/logout.html</code> which causes the current OpenID user data to be removed by either removing it from the HTTP Session or by clearing the OpenID cookie.</p>
+<h3 id="phase-1-form-submission">Phase 1: Form Submission</h3>
+<p>Requesting an OpenID identifier is initiated by the Sling Authenticator deciding, that authentication is actually required to process a request and the OpenID Authentication Handler being selected to request credentials with.</p>
+<p>In this case the OpenID authenticator causes a form to be rendered by redirecting the client to the URL indicated by the <code>form.login.form</code> configuration parameter. This redirection request may accompanied by the following parameters:</p>
+<table>
+<thead>
+<tr>
+<th>Request Parameter</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>resource</code></td>
+<td>The location to which the user initially requested access and that caused the <code>requestCredentials</code> method to be called. This may not be set (or be set to an empty string).</td>
+</tr>
+<tr>
+<td><code>j_reason</code></td>
+<td>The reason why an earlier attempt at authentication with the OpenID authentication handler failed. This request parameter is only set if the same named request attribute has been set by the <code>extractCredentials</code> or the <code>authenticationFailed</code> method. The value of the parameter is the name of one of the <code>OpenIDFailure</code> constants.</td>
+</tr>
+<tr>
+<td><code>j*openid*identity</code></td>
+<td>The OpenID identity which could not successfully be associated with an existing JCR user. This request parameter is only set if the <code>authenticationFailed</code> method has been called due to inability to associate an existing and validated OpenID identity with an existing JCR user.</td>
+</tr>
+</tbody>
+</table>
+<p>The OpenID Authentication handlers supports the following request parameters submitted by the HTML form:</p>
+<ul>
+<li><code>openid_identifier</code> -- OpenID Claimed Identifier. This may be any actual OpenID identity URL or the URL of OpenID Provider such as https://www.google.com/accounts/o8/id, https://me.yahoo.com, or https://www.myopenid.com.</li>
+<li><code>sling:authRequestLogin</code> -- This request parameter is recommended to be set with a hidden field to the value <em>OpenID</em> to ensure the request is handled by the OpenID Authentication Handler.</li>
+<li><code>resource</code> -- The <code>resource</code> request parameter should be sent back to ensure the user is finally redirected to requested target resource after successful authentication. If this request parameter is not set, or is set to an empty string, it is assumed to be the request context root path.</li>
+</ul>
+<p>The OpenID Authentication Handler provides a default login form registered at <code>/system/sling/openid/login</code>.</p>
+<h3 id="configuration">Configuration</h3>
+<p>The OpenID AuthenticationHandler is configured with configuration provided by the OSGi Configuration Admin Service using the <code>org.apache.sling.openidauth.OpenIdAuthenticationHandler</code> service PID.</p>
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>path</code></td>
+<td>--</td>
+<td>Repository path for which this authentication handler should be used by Sling. If this is empty, the authentication handler will be disabled.</td>
+</tr>
+<tr>
+<td><code>openid.login.form</code></td>
+<td><code>/system/sling/openid/login</code></td>
+<td>This should provide a way to capture the user's OpenID identifier. This is not the OpenID Provider's login page, however, it does not have to be a local URL. If it is a local Sling URL, it must be accessible by the anonymous user. The user is HTTP Redirect'ed to this URL. This page should POST back the user's OpenID identifier (as named by the "OpenID identifier form field" property) to the originally requested URL set in the "resource" request parameter.</td>
+</tr>
+<tr>
+<td><code>openid.login.identifier</code></td>
+<td><code>openid*identifier</code></td>
+<td>The name of the form parameter that provides the user's OpenID identifier. By convention this is <code>openid*identifier</code>. Only change this if you have a very good reason to do so.</td>
+</tr>
+<tr>
+<td><code>openid.external.url.prefix</code></td>
+<td>--</td>
+<td>The prefix of URLs generated for the <code>ReturnTo</code> and <code>TrustRoot</code> properties of the OpenID request to the OpenID provider. Thus this URL prefix should bring back the authenticated user to this Sling instance. Configuring this property is usually necessary when running Sling behind a proxy (like Apache) since proxy mapping is not performed on the OpenID ReturnTo and TrustRoot URLs as they are sent to the OpenID Provider as form parameters. If this property is empty, the URLs are generated using the hostname found in the original request.</td>
+</tr>
+<tr>
+<td><code>openid.use.cookie</code></td>
+<td><code>true</code></td>
+<td>Whether to use a regular Cookie or an HTTP Session to cache the OpenID authentication details. By default a regular cookie is used to prevent use of HTTP Sessions.</td>
+</tr>
+<tr>
+<td><code>openid.cookie.domain</code></td>
+<td>--</td>
+<td>Domain of cookie used to persist authentication. This defaults to the host name of the Sling server but may be set to a different value to share the cookie amongst a server farm or if the server is running behind a proxy. Only used if 'Use Cookie' is checked.</td>
+</tr>
+<tr>
+<td><code>openid.cookie.name</code></td>
+<td><code>sling.openid</code></td>
+<td>Name of cookie used to persist authentication. Only used if 'Use Cookie' is checked.</td>
+</tr>
+<tr>
+<td><code>openid.cookie.secret.key</code></td>
+<td><code>secret</code></td>
+<td>Secret key used to create a signature of the cookie value to prevent tampering. Only used if 'Use Cookie' is true.</td>
+</tr>
+<tr>
+<td><code>openid.user.attr</code></td>
+<td><code>openid.user</code></td>
+<td>Name of the JCR SimpleCredentials attribute to to set with the OpenID User data. This attribute is used by the OpenID LoginModule to validate the OpenID user authentication data.</td>
+</tr>
+<tr>
+<td><code>openid.property.identity</code></td>
+<td><code>openid.identity</code></td>
+<td>The name of the JCR User attribute listing one or more OpenID Identity URLs with which a user is associated. The property may be a multi- or single-valued. To resolve a JCR user ID from an OpenID identity a user is searched who lists the identity in this property.</td>
+</tr>
+</tbody>
+</table>
+<h3 id="authenticationhandler-implementation">AuthenticationHandler implementation</h3>
+<h4 id="extractcredentials">extractCredentials</h4>
+<p>To extract authentication information from the request, the Sling OpenID Authentication handler considers the following information in order:</p>
+<ol>
+<li>The OpenID credentials cookie or OpenID User data in the HTTP Session (depending on the <code>openid.use.cookie</code> configuration)</li>
+<li>Otherwise the <code>openid_identifier</code> request parameter (or a different request parameter depending on the <code>openid.login.identifier</code> configuration)</li>
+</ol>
+<p>If the OpenID credentials already exist in the request, they are validated and returned if valid</p>
+<p>If the existing credentials fail to validate, authentication failure is assumed and the credentials are removed from the request, either by clearing the OpenID cookie or by removing the OpenID User data from the HTTP Session.</p>
+<p>If no OpenID credentials are found in the request, the request parameter is considered and if set is used to resolve the actual OpenID identity of the user. This involves redirecting the client to the OpenID provider resolved from the OpenID identifier supplied.</p>
+<p>If the supplied OpenID identifier fails to resolve to an OpenID provider or if the identifier fails to be resolved to a validated OpenID identity, authentication fails.</p>
+<h4 id="requestcredentials">requestCredentials</h4>
+<p>If the <code>sling:authRequestLogin</code> parameter is set to a value other than <code>OpenID</code> this method immediately returns <code>false</code>.</p>
+<p>If the parameter is not set or is set to <code>OpenID</code> this method continues with first invalidating any cached OpenID credentials (same as <code>dropCredentials</code> does) and then redirecting the client to the login form configured with the <code>openid.login.form</code> configuration property. The redirect is provided with up to three request parameters:</p>
+<table>
+<thead>
+<tr>
+<th>Request Parameter</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>resource</code></td>
+<td>The location to which the user initially requested access and that caused the <code>requestCredentials</code> method to be called.</td>
+</tr>
+<tr>
+<td><code>j_reason</code></td>
+<td>The reason why an earlier attempt at authentication with the OpenID authentication handler failed. This request parameter is only set if the same named request attribute has been set by the <code>extractCredentials</code> or the <code>authenticationFailed</code> method. The value of the parameter is the name of one of the <code>OpenIDFailure</code> constants.</td>
+</tr>
+<tr>
+<td><code>j*openid*identity</code></td>
+<td>The OpenID identity which could not successfully be associated with an existing JCR user. This request parameter is only set if the <code>authenticationFailed</code> method has been called due to inability to associate an existing and validated OpenID identity with an existing JCR user.</td>
+</tr>
+</tbody>
+</table>
+<h4 id="dropcredentials">dropCredentials</h4>
+<p>Invalidates the OpenID identity currently stored with the request. This means to either remove the OpenID cookie or to remove the OpenID information from the HTTP Session. This method does not write to the response (except setting the <code>Set-Cookie</code> header to remove the OpenID cookie if required) and does not commit the response.</p>
+<h3 id="authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</h3>
+<h4 id="authenticationfailed">authenticationFailed</h4>
+<p>This method is called, if the Credentials provided by the Authentication Handler could not be validated by the Jackrabbit authentication infrastructure. One cause may be that the integration with Jackrabbit has not been completed (see <em>Integration with Jackrabbit</em> below). Another, more probably cause, is that the validated OpenID identifier cannot be associated with an existing JCR user.</p>
+<p>The OpenID Authentication Handler implementation of the <code>authenticationFailed</code> method sets the <code>j*reason</code> request attribute to <code>OpenIDFailure.REPOSITORY</code> and sets the <code>j*openid_identity</code> request attribute to the OpenID identity of the authenticated user.</p>
+<p>A login form provider may wish to act upon this situation and provide a login form to the user to allow to his OpenID identity with an existing JCR user.</p>
+<p>In addition, the current OpenID identity is invalidated thus the cached OpenID information is removed from the HTTP Session or the OpenID cookie is cleaned. This will allow the user to present a different OpenID identifier to retry or it will require the OpenID identity to be revalidated with the OpenID provider if the identity is associated with a JCR user.</p>
+<h4 id="authenticationsucceeded">authenticationSucceeded</h4>
+<p>The OpenID Authentication Handler implementation of the <code>authenticationSucceeded</code> method just calls the <code>DefaultAuthenticationFeedbackHandler.handleRedirect</code> method to redirect the user to the initially requested location.</p>
+<h3 id="integration-with-jackrabbit">Integration with Jackrabbit</h3>
+<p>The OpenID authentication handler can be integrated in two ways into the Jackrabbit authentication mechanism which is based on JAAS <code>LoginModule</code>. One integration is by means of a <code>LoginModulePlugin</code> which plugs into the extensible <code>LoginModule</code> architecture supported by the Sling Jackrabbit Embedded Repository bundle.</p>
+<p>The other integration option is the <code>trusted*credentials*attribute</code> mechanism supported by the Jackrabbit <code>DefaultLoginModule</code>. By setting the <code>trusted*credentials*attribute</code> parameter of the Jackrabbit <code>DefaultLoginModule</code> and the <code>openid.user.attr</code> configuration property of the OpenID Authentication Handler to the same value, the existence of an attribute of that name in the <code>SimpleCredentials</code> instance provided to the <code>Repository.login</code> method signals pre-authenticated credentials, which need not be further checked by the <code>DefaultLoginModule</code>.</p>
+<h3 id="security-considerations">Security Considerations</h3>
+<p>OpenIDAuthentication 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>
+<li>When using the <code>trusted*credentials*attribute</code> mechanism, any intruder knowing the attribute name may log into the repository as any existing JCR user. The better option is to be based on the <code>LoginModulePlugin</code> mechanism.</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 class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-framework.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-framework.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-framework.html Tue May 22 09:41:22 2012
@@ -0,0 +1,216 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Authentication - Framework</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a> » <a href="/documentation/the-sling-engine/authentication.html">Authentication</a>
+ </div>
+ <h1>Authentication - 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 <code>AuthenticationSupport</code> service provided by the <code>SlingAuthenticator</code> class. This service can be used by implementations of the OSGi <code>HttpContext</code> interface to delegate authentication.</li>
+<li>The <code>Authenticator</code> service also provided by the <code>SlingAuthenticator</code> class. This service may be used by Sling Applications to help clients login and logout.</li>
+<li>The <code>AuthenticationHandler</code> 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 <code>SlingAuthenticator</code> class provides the <code>AuthenticationSupport</code> and <code>Authenticator</code> services. For a description of the <code>AuthenticationHandler</code> service interface and the interaction between the <code>SlingAuthenticator</code> and the <code>AuthenticationHandler</code> services refer to the <a href="/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html">AuthenticationHandler</a> page.</p>
+<p>The <code>SlingAuthenticator</code> class is an internal class of the <code>org.apache.sling.commons.auth</code> bundle and implements the <code>Authenticator</code> and <code>AuthenticationSupport</code> services.</p>
+<h2 id="authenticationsupport">AuthenticationSupport</h2>
+<p>The <code>AuthenticationSupport</code> service interface defines a single method: <code>handleSecurity</code>. This method is intended to be called by the <code>handleSecurity</code> method of any <code>HttpContext</code> implementation wishing to make use of the Sling Authentication Framework.</p>
+<p>The Sling Authenticator implementation selects an <code>AuthenticationHandler</code> service appropriate for the request and calls the <code>AuthenticationHandler.extractCredentials</code> 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 <code>login</code> method.</p>
+<p>The implementation follows this algorithm:</p>
+<ol>
+<li>Select one or more <code>AuthenticationHandler</code> for the request according to the request URL's scheme and authorization part.</li>
+<li>Call the <code>extractCredentials</code> 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-<code>null</code> <code>AuthenticationInfo</code> result "wins" and the result is used for authentication.</li>
+<li>If any <code>AuthenticationInfoPostProcessor</code> services are registered, the <code>AuthenticationInfo</code> object is passed to their <code>postProcess()</code> method.</li>
+<li>If no handler returns a non-<code>null</code> result, the request may be handled anonymously. In these cases, an empty <code>AuthenticationInfo</code> object is passed to any <code>AuthenticationInfoPostProcessor</code> 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 <em>if</em> the <code>AuthenticationInfo</code> object contains a non-null object with the key <code>$$auth.info.login$$</code> (<code>AuthConstants.AUTH*INFO*LOGIN</code>). This event is posted with the topic <code>org/apache/sling/auth/core/Authenticator/LOGIN</code>. (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>
+<p>| Credentials | Login | Consequence |
+| present | successfull | Continue with an authenticated request |
+| present | failed | Select <code>AuthenticationHandler</code> and call <code>requestCredentials</code> method |
+| missing | anonymous allowed | Continue with a non authenticated request using anonymous access to the repository |
+| missing | anonymous forbidden | Select <code>AuthenticationHandler</code> and call <code>requestCredentials</code> method |</p>
+<p>{note}
+Only one <code>AuthenticationHandler</code> 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 <code>AuthenticationHandler</code> is consulted.
+{note}</p>
+<h4 id="request-attributes-on-successful-login">Request Attributes on Successful Login</h4>
+<p>The <code>handleSecurity</code> method gets credentials from the <code>AuthenticationHandler</code> and logs into the JCR repository using those credentials. If the login is successful, the <code>SlingAuthenticator</code> sets the following request attributes:</p>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>org.osgi.service.http.authentication.remote.user</code></td>
+<td>The user ID of the JCR Session. This attribute is used by the HTTP Service implementation to implement the <code>HttpServletRequest.getRemoteUser</code> method.</td>
+</tr>
+<tr>
+<td><code>org.osgi.service.http.authentication.type</code></td>
+<td>The authentication type defined by the <code>AuthenticationHandler</code>. This attribute is used by the HTTP Service implementation to implement the <code>HttpServletRequest.getAuthType</code> method.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.auth.ResourceResolver</code></td>
+<td>The <code>ResourceResolver</code> created from the credentials and the logged in JCR Session. This attribute may be used by servlets to access the repository. Namely the <code>SlingMainServlet</code> uses this request attribute to provide the <code>ResourceResolver</code> to handle the request.</td>
+</tr>
+<tr>
+<td><code>javax.jcr.Session</code></td>
+<td>The JCR Session. This attribute is for backwards compatibility only. <em>Its use is deprecated and the attribute will be removed in future versions</em>.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.auth.spi.AuthenticationInfo</code></td>
+<td>The <code>AuthenticationInfo</code> object produced from the <code>AuthenticationHandler</code>.</td>
+</tr>
+</tbody>
+</table>
+<p><em>NOTE</em>: Do <em>NOT</em> use the <code>javax.jcr.Session</code> request attribute in your Sling applications. This attribute must be considered implementation specific to convey the JCR Session to the <code>SlingMainServlet</code>. 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="codehilite"><pre><span class="n">Session</span> <span class="n">session</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">getResourceResolver</span><span class="p">()</span><span class="o">.</span><span class="n">adaptTo</span><span class="p">(</span><span class="n">Session</span><span class="o">.</span><span class="n">class</span><span class="p">);</span>
+</pre></div>
+
+
+<h4 id="anonymous-login">Anonymous Login</h4>
+<p>The <code>SlingAuthenticator</code> 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> (<code>auth.annonymous</code>) property of the <code>SlingAuthenticator</code> configuration. This property is supported for backwards compatibility and defaults to <code>true</code> (allowing anonymous access).</li>
+<li>Specific configuration per URL. The <em>Authentication Requirements</em> (<code>sling.auth.requirements</code>) property of the <code>SlingAuthenticator</code> configuration may provide a list of URLs for which authentication may be required or not: Any entry prefixed with a dash <code>-</code> defines a subtree for which authentication is not required. Any entry not prefixed with a dash or prefixed with a plus <code>+</code> 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 <code>sling.auth.requirements</code> 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 <code>AuthenticationHandler</code> 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 <code>sling.auth.requirements</code> service registration property can be absolute paths or URLs like the <code>path</code> service registration property of <code>AuthenticationHandler</code> services. This allows the limitation of this setup to certain requests by scheme and/or virtual host address.</p>
+<p><em>Examples</em></p>
+<ul>
+<li>
+<p>The <code>LoginServlet</code> contained in the Commons Auth bundle registers itself with the service registration property <code>sling.auth.requirements = "-/system/sling/login"</code> to ensure the servlet can be accessed without requiring authentication.</p>
+</li>
+<li>
+<p>An authentication handler may register itself with the service registration property <code>sling.auth.requirements = "-/apps/sample/loginform"</code> to ensure the login form can be rendered without requiring authentication.</p>
+</li>
+</ul>
+<h2 id="authenticator-implementation">Authenticator implementation</h2>
+<p>The implementation of the <code>Authenticator</code> interface is similar for both methods:</p>
+<p><em><code>login</code></em></p>
+<ol>
+<li>Select one or more <code>AuthenticationHandler</code> for the request according to the request URL's scheme and authorization part.</li>
+<li>Call the <code>requestCredentials</code> 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 <code>true</code>, the process ends and it is assumed credentials have been requested from the client.</li>
+</ol>
+<p>The <code>login</code> method has three possible exit states:</p>
+<table>
+<thead>
+<tr>
+<th>Exit State</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Normal</td>
+<td>An <code>AuthenticationHandler</code> could be selected to which the login request could be forwarded.</td>
+</tr>
+<tr>
+<td><code>NoAuthenticationHandlerException</code></td>
+<td>No <code>AuthenticationHandler</code> 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><code>IllegalStateException</code></td>
+<td>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>
+<p><em><code>logout</code></em>
+1. Select one or more <code>AuthenticationHandler</code> for the request according to the request URL's scheme and authorization part.
+1. Call the <code>dropCredentials</code> 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.</p>
+<p>Unlike for the <code>login</code> method in the <code>logout</code> method case all <code>AuthenticationHandler</code> services selected in the first step are called. If none can be selected or none can actually handle the <code>dropCredentials</code> request, the <code>logout</code> silently returns.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341361 by fmeschbe on Tue, 22 May 2012 08:54:04 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-tasks.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-tasks.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-tasks.html Tue May 22 09:41:22 2012
@@ -0,0 +1,111 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Authentication - Tasks</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a> » <a href="/documentation/the-sling-engine/authentication.html">Authentication</a>
+ </div>
+ <h1>Authentication - Tasks</h1>
+ <p>Authentication of HTTP Requests is generally a two-step process: First the credentials must be extracted from the request and second the credentials must be validated. In the case of Sling this means acquiring a JCR Session.</p>
+<h2 id="extract-credentials-from-the-request">Extract Credentials from the Request</h2>
+<ul>
+<li>Implemented and controlled by the Sling Commons Auth bundle</li>
+<li>Takes <code>HttpServletRequest</code></li>
+<li>Provides credentials for futher processing (basically JCR <code>Credentials</code> and Workspace name)</li>
+<li>Extensible with the help of <code>AuthenticationHandler</code> services</li>
+</ul>
+<h2 id="login-to-the-jcr-repository">Login to the JCR Repository</h2>
+<ul>
+<li>Implemented and controlled by the JCR Repository</li>
+<li>Takes JCR <code>Credentials</code> and Workspace name</li>
+<li>Provides a JCR <code>Session</code></li>
+<li>Implementation dependent process. Jackrabbit provides extensibility based on <code>LoginModules</code>; Sling's Embedded Jackrabbit Repository bundle provides extensibility with <code>LoginModulePlugin</code> services.</li>
+</ul>
+<p>Currently the credentials are always verified by trying to login to the JCR repository. Once an <a href="">ResourceResolverFactory</a> API has been added, the process of validating the credentials and logging in is actualy replaced by a process of requesting a <code>ResourceResolver</code> from the <code>ResourceResolverFactory</code>. Of course, the JCR Repository will still be the main underlying repository and as such be used to validate the credentials and get a JCR Session.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341361 by fmeschbe on Tue, 22 May 2012 08:54:04 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/default-mapping-and-rendering.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/default-mapping-and-rendering.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/default-mapping-and-rendering.html Tue May 22 09:41:22 2012
@@ -0,0 +1,96 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Default Mapping and Rendering</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>Default Mapping and Rendering</h1>
+ <p>This page contained obsolete content, moved it to http://cwiki.apache.org/confluence/display/SLING/Default+Mapping+and+Rendering+%28OBSOLETE%29 in case it is useful to someone.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/dispatching-requests.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/dispatching-requests.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/dispatching-requests.html Tue May 22 09:41:22 2012
@@ -0,0 +1,170 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Dispatching Requests</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>Dispatching Requests</h1>
+ <h2 id="main-process">Main process</h2>
+<p>The following steps should give you an overview how a request is processed in Sling. Details can be found under provided links.</p>
+<h3 id="step-1">Step 1</h3>
+<p>The client sends the request</p>
+<h3 id="step-2">Step 2</h3>
+<p>This step applies only if a Servlet Container is installed and Sling is embedded:
+Servlet Container gets request and forwards to OSGi HttpService</p>
+<h3 id="step-3">Step 3</h3>
+<p>OSGi HttpService looks for responsible registered Servlet or resource (see 102.4 of the OSGi compendium)</p>
+<h3 id="step-4">Step 4</h3>
+<p>OSGi HttpService calls <code>handleSecurity</code> of the HttpContext associated with the servlet/resource. In case of Sling this calls into SlingMainServlet.handleSecurity and then into SlingAuthenticator.authenticate</p>
+<h3 id="step-4a">Step 4a</h3>
+<p>SlingAuthenticator selects an authentication handler for the request and forwards the authenticate call. On success a <code>javax.jcr.Session</code> is created, the request attributes required by the HTTP Service spec are set (like <code>org.osgi.service.http.authentication.remote.user</code> and <code>org.osgi.service.http.authentication.type</code>and also the <code>javax.jcr.Session</code> which is used later is set in the request attributes.
+On success, continue with step 5.</p>
+<h3 id="step-4b">Step 4b</h3>
+<p>If authentication fails either an anonymous session is acquired (if anonymous is allowed per configuration) or the login method is called.
+If anonymous is allowed, continue with step 5.</p>
+<h3 id="step-4c">Step 4c</h3>
+<p>The login method selects an AuthenticationHandler and forwards the login call to the AuthenticationHandler.requestAuthentication method to cause the client to authenticate. Request processing stops here (<code>SlingMainServlet.handleSecurity</code> returns false).</p>
+<h3 id="step-5">Step 5</h3>
+<p>After getting a response the HttpService either terminates the request (if authentication failed and <code>SlingMainServlet.handleSecurity</code> returned false) or continues by either spooling the resource or in the case of Sling calling the <code>SlingMainServlet.service</code> method.</p>
+<h3 id="step-6">Step 6</h3>
+<p>The <code>SlingMainServlet.service</code> method is the entry point into the Sling proper. This method sets up the request:
+<em> Wraps the <code>HttpServletRequest</code> and the <code>HttpServletResponse</code> into the <code>SlingHttpServletRequest</code> and the <code>SlingHttpServletResponse</code>
+</em> Checks if Sling is ready for processing the request (checks at the moment for an existing ResourceResolverFactory service, a ServletResolver service and a MimeTypeService)
+<em> Create the ResourceResolver based on the Session (by default creates a <code>JcrResourceResolver2</code>)
+</em> Locate the <a href="">Resource</a> on the basis of the request by calling <code>ResourceResovler.resolve</code> through <code>RequestData.initResource</code> (see also [URL decomposition])
+* Locate the servlet or script (see <a href="/documentation/the-sling-engine/servlets.html">Servlets</a>) by calling <code>ServletResolver.resolveServlet</code> through <code>RequestData.initServlet</code></p>
+<h3 id="step-7">Step 7</h3>
+<p>After this setup, the request level filters are called (the ones registered as <code>javax.servlet.Filter</code> with the property <code>filter.scope=request</code>, see <a href="/documentation/the-sling-engine/filters.html">Filters</a> for details).
+If any called filter doesn't call <code>FilterChain.doFilter</code> at the end of the <code>Filter.doFilter</code> method request processing stops here.</p>
+<h3 id="step-8">Step 8</h3>
+<p>After having called all request level filters, the component level filters (registered with the property <code>filter.scope=component</code>, see <a href="/documentation/the-sling-engine/filters.html">Filters</a> for details) are called.</p>
+<h3 id="step-9">Step 9</h3>
+<p>After having called the component level filters, the request servlet or script is finally called to process the request.</p>
+<h2 id="includeforward">Include/Forward</h2>
+<p>If a servlet or script is including another resource for processing through the <code>RequestDispatcher.include</code> or <code>RequestDispatcher.forward</code> (or any JSP or feature of another scripting language which relies on one of this two methods) the following processing takes place:</p>
+<h3 id="step-1_1">Step 1</h3>
+<p>Code in the processing servlet or script calls <code>RequestDispatcher.include</code> or <code>RequestDispatcher.forward</code>.</p>
+<h3 id="step-2_1">Step 2</h3>
+<p>The resource is resolved though ResourceResolver.getResource (if the RequestDispatcher has not been created with a resource already)</p>
+<h3 id="step-3_1">Step 3</h3>
+<p>The servlet or script to handle the resource is resolved calling the <code>ServletResolver.resolverServlet</code> method.</p>
+<h3 id="step-4_1">Step 4</h3>
+<p>The component level filters (registered with the property <code>filter.scope=component</code>) are called again (see <a href="/documentation/the-sling-engine/filters.html">Filters</a> for details).</p>
+<h3 id="step-5_1">Step 5</h3>
+<p>The servlet or script is called to process the request.</p>
+<p>Note that these steps are processed for every include or forward call.</p>
+<h2 id="included-request-attributes">Included Request Attributes</h2>
+<p>When servlet or script is called as a result of <code>RequestDispatcher.include</code> the following request attributes are set:</p>
+<p>| Attribute Name
+Attribute Type | Description |
+| <code>org.apache.sling.api.include.servlet</code>
+<code>javax.servlet.Servlet</code> | The name of the request attribute containing the <code>Servlet</code> which included the servlet currently being active. |
+| <code>org.apache.sling.api.include.resource</code>
+<code>org.apache.sling.api.resource.Resource</code> | The name of the request attribute containing the <code>Resource</code> underlying the <code>Servlet</code> which included the servlet currently being active. |
+| <code>org.apache.sling.api.include.request*path*info</code>
+<code>org.apache.sling.api.request.RequestPathInfo</code> | The name of the request attribute containing the <code>RequestPathInfo</code> underlying the <code>Servlet</code> which included the servlet currently being active |
+| <code>javax.servlet.include.request_uri</code>
+<code>String</code> | The name of the request attribute containing the <code>HttpServletRequest.getRequestURI()</code> of the request which included the servlet currently being active underlying the <code>Servlet</code> which included the servlet currently being active.
+<em>Note:</em> In Sling, the <code>HttpServletRequest.getRequestURI()</code> method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
+| <code>javax.servlet.include.context_path</code>
+<code>String</code> | The name of the request attribute containing the <code>HttpServletRequest.getContextPath()</code> of the request which included the servlet currently being active underlying the <code>Servlet</code> which included the servlet currently being active.
+<em>Note:</em> In Sling, the <code>HttpServletRequest.getContextPath()</code> method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
+| <code>javax.servlet.include.servlet_path</code>
+<code>String</code> | The name of the request attribute containing the <code>HttpServletRequest.getServletPath()</code> of the request which included the servlet currently being active underlying the <code>Servlet</code> which included the servlet currently being active.
+<em>Note:</em> In Sling, the <code>HttpServletRequest.getServletPath()</code> method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
+| <code>javax.servlet.include.path_info</code>
+<code>String</code> | The name of the request attribute containing the <code>HttpServletRequest.getPathInfo()</code> of the request which included the servlet currently being active underlying the <code>Servlet</code> which included the servlet currently being active.
+<em>Note:</em> In Sling, the <code>HttpServletRequest.getPathInfo()</code> method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification.
+| <code>javax.servlet.include.query_string</code>
+<code>String</code> | The name of the request attribute containing the <code>HttpServletRequest.getQueryString()</code> of the request which included the servlet currently being active underlying the <code>Servlet</code> which included the servlet currently being active.
+<em>Note:</em> In Sling, the <code>HttpServletRequest.getQueryString()</code> method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |</p>
+<p>Constants are defined in the <code>org.apache.sling.api.SlingConstants</code> class for these request attributes.</p>
+<p><em>Note:</em> These request attributes are not set if the servlet or script is called to handle the request or as a result of <code>RequestDispatcher.forward</code>.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/errorhandling.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/errorhandling.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/errorhandling.html Tue May 22 09:41:22 2012
@@ -0,0 +1,124 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Errorhandling</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>Errorhandling</h1>
+ <p>The Sling Engine includes support for handling uncaught <code>Throwable</code> as well as rendering custom HTTP status code pages. This is implemented by expecting a (single) <code>org.apache.sling.engine.servlets.ErrorHandler</code> service to which handling of uncaught <code>Throwable</code> and HTTP status responses are delegated.</p>
+<p>The Sling Servlet Resolver bundle implements this interface by providing an elaborate mechanism to find the correct error handling script or servlet using the same algorithms as are used to select the scripts or servlets to handle regular requests.</p>
+<p>This page provides more information on how error handler scripts are selected and what is provided out of the box.</p>
+<h2 id="http-status-codes">HTTP Status Codes</h2>
+<p>The Sling engine implements the <code>HttpServletResponse.sendError</code> methods by calling the <code>ErrorHandler.handleError(int status, String message, SlingHttpServletRequest request, SlingHttpServletResponse response)</code> method.</p>
+<p>The Servlet Resolver bundle implementation looks up a script to handle the status code as follows:</p>
+<ul>
+<li>The status code is converted to a string and used as the request extension. Any request extensions, selectors or suffixes from the actual request are ignored.</li>
+<li>The same resource type hierarchy is followed to find the script as for regular script resolution. The difference is that for error handler scripts <code>sling/servlet/errorhandler</code> is used as the implied base resource type (as opposed to <code>sling/servlet/default</code> for regular script resolution.</li>
+</ul>
+<p><em>Examples:</em></p>
+<ul>
+<li>An application provider my provide a default handler for the 404/NOT FOUND status. This script might be located in <code>/libs/sling/servlet/errorhandler/404.jsp</code>.</li>
+<li>An programmer might provide a handler for the 403/FORBIDDEN status in <code>/apps/sling/servlet/errorhandler/403.esp</code>.</li>
+</ul>
+<h2 id="uncaught-throwables">Uncaught Throwables</h2>
+<p>To handle uncaught Throwables the simple name (<code>Class.getSimpleName()</code>) of the <code>Throwable</code> class is used as request extension. Similarly to the Java try-catch clauses the class hierarchy is supported. That is to handle an uncaught <code>FileNotFoundException</code>, the names <code>FileNotFoundException</code>, <code>IOException</code>, <code>Exception</code>, <code>Throwable</code> are checked for a Servlet and the first one found is then used. Again, the Serlvet may be a Servlet registered as an OSGi service or may be a plain script stored in the JCR repository or provided through some custom Resource provider.</p>
+<p><em>Example:</em>
+To register a catch-all handler for any uncaught Throwables you might create a script <code>/apps/sling/servlet/errorhandler/Throwable.esp</code>.</p>
+<p><em>Note:</em> If no script or servlet to handle an uncaught <code>Throwable</code> is registered, the default handler kicks in, which sends back a 500/INTERNAL SERVER ERROR response containing the <code>Throwable</code> and the stack trace. This response is <em>not</em> handled by the HTTP Status Code handling described above because the response status is sent using <code>HttpServletResponse.setStatus(int, String)</code>. To prevent this default response you have to implement a catch-all handler for the <code>Throwable</code> class as shown in the example.</p>
+<h2 id="default-handler">Default Handler</h2>
+<p>The Sling Servlet Resolver bundle provides a default error handler servlet which is used if the algorithms described above do not resolve to a handler script or servlet. The provided error handler servlet does the following:</p>
+<ul>
+<li>Print a descriptive message, which is the <code>javax.servlet.error.message</code> request attribute by default</li>
+<li>Print a stacktrace if the <code>javax.servlet.error.exception</code> is set</li>
+<li>Dump the request progress tracker</li>
+</ul>
+<p>Starting with Sling Servlet Resolver version 2.0.10 the default error handler servlet is looked up using the string <code>default</code> as the request extension and the provided default servlet is registered as <code><prefix>/sling/servlet/errorhandler/default.servlet</code> where <prefix> is the last entry in the resource resolver search path, <code>/libs</code> by default.</p>
+<p>Thus to overwrite the default error handler servlet provide a servlet or script for the <code>default</code> extension, for example <code>/apps/sling/servlet/errorhandler/default.groovy</code>.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>