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 > OpenID AuthenticationHandler
Date Wed, 25 May 2011 14:07: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/OpenID+AuthenticationHandler">OpenID
AuthenticationHandler</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Fix SVN URL (Thanks Steve Tibbett for noting)<br />
    </div>
        <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" >_NOTE:_ 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
{{UserManager}} to find users by a user property value. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The OpenID Authentication Handler
is maintained in the [Sling <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">SVN|http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/openidauth]</span>
<span class="diff-added-words"style="background-color: #dfd;">SVN|http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/openid/]</span>
<br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="OpenIDAuthenticationHandler-OpenIDAuthenticationHandler"></a>OpenID
AuthenticationHandler</h1>

<div><a href='#OpenIDAuthenticationHandler-CredentialsExtraction'>Credentials
Extraction</a> | <a href='#OpenIDAuthenticationHandler-Phase1%3AFormSubmission'>Phase
1: Form Submission</a> | <a href='#OpenIDAuthenticationHandler-Configuration'>Configuration</a>
| <a href='#OpenIDAuthenticationHandler-AuthenticationHandlerimplementation'>AuthenticationHandler
implementation</a> | <a href='#OpenIDAuthenticationHandler-AuthenticationFeedbackHandlerimplementation'>AuthenticationFeedbackHandler
implementation</a> | <a href='#OpenIDAuthenticationHandler-IntegrationwithJackrabbit'>Integration
with Jackrabbit</a> | <a href='#OpenIDAuthenticationHandler-SecurityConsiderations'>Security
Considerations</a></div>

<p>The OpenID Authentication Handler supports authentication of request users using
the <a href="http://www.openid.net" class="external-link" rel="nofollow">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 <tt>UserManager</tt>
to find users by a user property value.</p>

<p>The OpenID Authentication Handler is maintained in the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/openid/"
class="external-link" rel="nofollow">Sling SVN</a></p>


<h3><a name="OpenIDAuthenticationHandler-CredentialsExtraction"></a>Credentials
Extraction</h3>

<p>Theoretically each request with the <tt>openid_identifier</tt> 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 <tt>/system/sling/logout.html</tt>
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><a name="OpenIDAuthenticationHandler-Phase1%3AFormSubmission"></a>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 <tt>form.login.form</tt> configuration
parameter. This redirection request may accompanied by the following parameters:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Request Parameter </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>resource</tt> </td>
<td class='confluenceTd'> The location to which the user initially requested access
and that caused the <tt>requestCredentials</tt> method to be called. This may
not be set (or be set to an empty string). </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>j_reason</tt> </td>
<td class='confluenceTd'> 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 <tt>extractCredentials</tt> or the <tt>authenticationFailed</tt>
method. The value of the parameter is the name of one of the <tt>OpenIDFailure</tt>
constants. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>j_openid_identity</tt> </td>
<td class='confluenceTd'> The OpenID identity which could not successfully be associated
with an existing JCR user. This request parameter is only set if the <tt>authenticationFailed</tt>
method has been called due to inability to associate an existing and validated OpenID identity
with an existing JCR user. </td>
</tr>
</tbody></table>
</div>


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

<ul>
	<li><tt>openid_identifier</tt> &#8211; OpenID Claimed Identifier. This
may be any actual OpenID identity URL or the URL of OpenID Provider such as <a href="https://www.google.com/accounts/o8/id"
class="external-link" rel="nofollow">https://www.google.com/accounts/o8/id</a>, <a
href="https://me.yahoo.com" class="external-link" rel="nofollow">https://me.yahoo.com</a>,
or <a href="https://www.myopenid.com" class="external-link" rel="nofollow">https://www.myopenid.com</a>.</li>
	<li><tt>sling:authRequestLogin</tt> &#8211; 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><tt>resource</tt> &#8211; The <tt>resource</tt> 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 <tt>/system/sling/openid/login</tt>.</p>


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

<p>The OpenID AuthenticationHandler is configured with configuration provided by the
OSGi Configuration Admin Service using the <tt>org.apache.sling.openidauth.OpenIdAuthenticationHandler</tt>
service PID.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>path</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> 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 class='confluenceTd'> <tt>openid.login.form</tt> </td>
<td class='confluenceTd'> <tt>/system/sling/openid/login</tt> </td>
<td class='confluenceTd'> 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 class='confluenceTd'> <tt>openid.login.identifier</tt> </td>
<td class='confluenceTd'> <tt>openid_identifier</tt> </td>
<td class='confluenceTd'> The name of the form parameter that provides the user's OpenID
identifier. By convention this is <tt>openid_identifier</tt>. Only change this
if you have a very good reason to do so. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>openid.external.url.prefix</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> The prefix of URLs generated for the <tt>ReturnTo</tt>
and <tt>TrustRoot</tt> 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 class='confluenceTd'> <tt>openid.use.cookie</tt> </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'>  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 class='confluenceTd'> <tt>openid.cookie.domain</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> 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 class='confluenceTd'> <tt>openid.cookie.name</tt> </td>
<td class='confluenceTd'> <tt>sling.openid</tt> </td>
<td class='confluenceTd'> Name of cookie used to persist authentication. Only used if
'Use Cookie' is checked. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>openid.cookie.secret.key</tt> </td>
<td class='confluenceTd'> <tt>secret</tt> </td>
<td class='confluenceTd'> 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 class='confluenceTd'> <tt>openid.user.attr</tt> </td>
<td class='confluenceTd'> <tt>openid.user</tt> </td>
<td class='confluenceTd'> 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 class='confluenceTd'> <tt>openid.property.identity</tt> </td>
<td class='confluenceTd'> <tt>openid.identity</tt> </td>
<td class='confluenceTd'>  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>
</div>




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


<h4><a name="OpenIDAuthenticationHandler-extractCredentials"></a>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 <tt>openid.use.cookie</tt> configuration)</li>
	<li>Otherwise the <tt>openid_identifier</tt> request parameter (or a different
request parameter depending on the <tt>openid.login.identifier</tt> 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><a name="OpenIDAuthenticationHandler-requestCredentials"></a>requestCredentials</h4>

<p>If the <tt>sling:authRequestLogin</tt> parameter is set to a value other
than <tt>OpenID</tt> this method immediately returns <tt>false</tt>.</p>

<p>If the parameter is not set or is set to <tt>OpenID</tt> this method
continues with first invalidating any cached OpenID credentials (same as <tt>dropCredentials</tt>
does) and then redirecting the client to the login form configured with the <tt>openid.login.form</tt>
configuration property. The redirect is provided with up to three request parameters:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Request Parameter </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>resource</tt> </td>
<td class='confluenceTd'> The location to which the user initially requested access
and that caused the <tt>requestCredentials</tt> method to be called. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>j_reason</tt> </td>
<td class='confluenceTd'> 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 <tt>extractCredentials</tt> or the <tt>authenticationFailed</tt>
method. The value of the parameter is the name of one of the <tt>OpenIDFailure</tt>
constants. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>j_openid_identity</tt> </td>
<td class='confluenceTd'> The OpenID identity which could not successfully be associated
with an existing JCR user. This request parameter is only set if the <tt>authenticationFailed</tt>
method has been called due to inability to associate an existing and validated OpenID identity
with an existing JCR user. </td>
</tr>
</tbody></table>
</div>




<h4><a name="OpenIDAuthenticationHandler-dropCredentials"></a>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 <tt>Set-Cookie</tt>
header to remove the OpenID cookie if required) and does not commit the response.</p>


<h3><a name="OpenIDAuthenticationHandler-AuthenticationFeedbackHandlerimplementation"></a>AuthenticationFeedbackHandler
implementation</h3>

<h4><a name="OpenIDAuthenticationHandler-authenticationFailed"></a>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 <tt>authenticationFailed</tt>
method sets the <tt>j_reason</tt> request attribute to <tt>OpenIDFailure.REPOSITORY</tt>
and sets the <tt>j_openid_identity</tt> 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><a name="OpenIDAuthenticationHandler-authenticationSucceeded"></a>authenticationSucceeded</h4>

<p>The OpenID Authentication Handler implementation of the <tt>authenticationSucceeded</tt>
method just calls the <tt>DefaultAuthenticationFeedbackHandler.handleRedirect</tt>
method to redirect the user to the initially requested location.</p>


<h3><a name="OpenIDAuthenticationHandler-IntegrationwithJackrabbit"></a>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 <tt>LoginModule</tt>. One integration
is by means of a <tt>LoginModulePlugin</tt> which plugs into the extensible <tt>LoginModule</tt>
architecture supported by the Sling Jackrabbit Embedded Repository bundle.</p>

<p>The other integration option is the <tt>trusted_credentials_attribute</tt>
mechanism supported by the Jackrabbit <tt>DefaultLoginModule</tt>. By setting
the <tt>trusted_credentials_attribute</tt> parameter of the Jackrabbit <tt>DefaultLoginModule</tt>
and the <tt>openid.user.attr</tt> configuration property of the OpenID Authentication
Handler to the same value, the existence of an attribute of that name in the <tt>SimpleCredentials</tt>
instance provided to the <tt>Repository.login</tt> method signals pre-authenticated
credentials, which need not be further checked by the <tt>DefaultLoginModule</tt>.</p>


<h3><a name="OpenIDAuthenticationHandler-SecurityConsiderations"></a>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 <tt>trusted_credentials_attribute</tt> 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 <tt>LoginModulePlugin</tt> 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>
        <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/OpenID+AuthenticationHandler">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=13271694&revisedVersion=10&originalVersion=9">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/OpenID+AuthenticationHandler?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message