ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r814554 - in /websites/staging/ace/trunk/content: ./ dev-doc/design/ace-authentication.html
Date Thu, 26 Apr 2012 10:20:34 GMT
Author: buildbot
Date: Thu Apr 26 10:20:34 2012
New Revision: 814554

Log:
Staging update by buildbot for ace

Modified:
    websites/staging/ace/trunk/content/   (props changed)
    websites/staging/ace/trunk/content/dev-doc/design/ace-authentication.html

Propchange: websites/staging/ace/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Apr 26 10:20:34 2012
@@ -1 +1 @@
-1330699
+1330750

Modified: websites/staging/ace/trunk/content/dev-doc/design/ace-authentication.html
==============================================================================
--- websites/staging/ace/trunk/content/dev-doc/design/ace-authentication.html (original)
+++ websites/staging/ace/trunk/content/dev-doc/design/ace-authentication.html Thu Apr 26 10:20:34
2012
@@ -171,22 +171,22 @@
 </li>
 <li><a href="#configuring-the-connection-factory">Configuring the connection
factory</a></li>
 <li><a href="#configuring-the-management-agent">Configuring the management agent</a></li>
+<li><a href="#configuring-users">Configuring users</a></li>
 </ul>
 </li>
-<li><a href="#extending-the-authentication-mechanism">Extending the authentication
mechanism</a><ul>
-<li><a href="#authentication-processors">Authentication processors</a></li>
-</ul>
-</li>
+<li><a href="#troubleshooting">Troubleshooting</a></li>
+<li><a href="#notes">Notes</a></li>
 </ul>
 </div>
 <h2 id="introduction">Introduction</h2>
 <p>When provisioning software (partly) to targets, one has to rely upon the trustworthiness
of both the network and the target. Even if everything is under your control and governance,
one cannot entirely be sure that unwanted access takes place. A first step in order to prevent
unwanted access is <em>authentication</em>, which gives you the ability to verify
the identity of someone. Once the identity is known, one can apply <em>authorization</em>
in order to determine what actions are allowed and which are not.
-In this article, the recently added authentication layer of ACE is explained in more depth,
and some details on how extensions can be written for additional mechanisms are given. The
remainder of this article assumes the reader has basic knowledge of the principles behind
ACE, and has sufficient programming skills. For this article, the latest code of ACE (0.8.1-SNAPSHOT,
rev.1329269) was used.</p>
+In this article, the recently added authentication layer of ACE is explained in more depth
and how to configure authentication to your situation.<br />
+The remainder of this article assumes the reader has basic knowledge of the principles behind
ACE, and has sufficient programming skills. For this article, the latest code of ACE (0.8.1-SNAPSHOT,
rev.1329269) was used.</p>
 <h2 id="communication-paths">Communication paths</h2>
 <p>Before going in more detail on the design and configuration of the authentication
layer in ACE, we first need to pinpoint all places were authentication needs to be applied.
The following figure shows the main components in ACE and their communication paths, providing
a global overview of where authentication is applicable to ACE.</p>
 <p><img alt="Figure 1: Overview of components and communication paths in ACE" src="auth_main_components.svg"
title="Figure 1: Overview of components and communication paths" /><br />
-Figure 1: Overview of components and communication paths.</p>
-<p>Figure 1 represents several of the communication paths that can be identified (denoted
by the circled digits):</p>
+<strong>Figure 1</strong>: Overview of components and communication paths.</p>
+<p>In the above figure, several of the communication paths (denoted by the circled
digits) that can be identified in ACE are represented:</p>
 <ol>
 <li>the client communicates to the ACE server by means of both direct calls to its
services as well as remote (HTTP<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>)
calls;</li>
 <li>a management agent (representing the target) communicates to the ACE server through
remote calls;</li>
@@ -206,9 +206,9 @@ Figure 1: Overview of components and com
 <li>should be optional. If no authentication is desired, one should be able to remove
its services from the ACE distribution;</li>
 <li>should be pluggable. Various ways of authentication exist, and new ones can emerge.
Making the authentication mechanism pluggable allows new ways of authentication to be used
easily.</li>
 </ol>
-<p>Based on these requirements, the design of the authentication layer is represented
in the following figure:</p>
+<p id="fig2">Based on these requirements, the design of the authentication layer is
represented in the following figure:</p>
 <p><img alt="Figure 2: Authentication layer class diagram" src="auth_api.svg" title="Figure
2: Authentication layer class diagram" /><br />
-Figure 2: Authentication layer class diagram.</p>
+<strong>Figure 2</strong>: Authentication layer class diagram.</p>
 <p>The <tt>AuthenticationService</tt> is responsible for authenticating
a user based on some piece of information. This piece of information can be an array containing
a username/password combination, a <tt>HttpServletRequest</tt> containing authentication
request headers, or any other type of information capable of uniquely identifying a user.
The actual authentication itself is delegated to one or more <tt>AuthenticationProcessor</tt>s,
which know how to handle  a given set of information (e.g., <tt>HttpServletRequest</tt>)
and can map this information to a particular user. In more detail, the calling sequence of
<tt>AuthenticationService#authenticate</tt> would be:</p>
 <ol>
 <li><tt>AuthenticationService#authenticate</tt> is called with a blob of
data, for example a <tt>HttpServletRequest</tt>;</li>
@@ -221,7 +221,7 @@ Figure 2: Authentication layer class dia
 </ol>
 <p>This is only half the story for authentication. As stated before, ACE internally
also communicates through remote endpoints to access certain services. Without any changes,
all those remote calls will fail due to missing credentials. If we would leave those means
of communications as-is, we need to track down all places where remote calls are being made
and inject the proper credentials at each of those places. However, doing this is not only
<em>very</em> invasive and error prone but also not very developer friendly from
a service-oriented perspective. Alternatively, we could try to include the credentials in
the URL itself, making it self-contained. Not only would this approach limit our ability to
use any kind of authentication mechanism (it only works for username/password combos), it
also required us to supply the credentials manually each and every time we want to create
a remote connection. Instead, we would like to refrain from passing around credentials, and
leve
 rage the service oriented aspects of OSGi to create remote connections for us. This service
could then be responsible for adding the right credentials for us, leaving the calling party
totally unaware about the fact authentication might be used (or not). Such a service is denoted
in the following figure:</p>
 <p><img alt="Figure 3: Connection Factory class diagram" src="auth_connectionfactory.svg"
title="Figure 3: Connection Factory class diagram" /><br />
-Figure 3: Connection Factory class diagram.</p>
+<strong>Figure 3</strong>: Connection Factory class diagram.</p>
 <p>The <tt>ConnectionFactory</tt> is responsible for creating <tt>URLConnection</tt>s,
given a "plain" URL. So, instead of calling <tt>URL#openConnection()</tt> or <tt>URL#openStream()</tt>,
we'll now have to call <tt>ConnectionFactory#createConnection(url)</tt> instead.
But what advantage does this give us? In order to allow the connection factory to supply the
credentials to <tt>URLConnection</tt>s, it is also registered as <tt>ManagedServiceFactory</tt>
that enables us to provide multiple configurations of which credentials should be supplied
to what (sets of) URLs. The introduction of the connection factory thus allows us to abstract
the creation of a connection and passing of credentials to it from the URL. Internally, the
connection factory will match each URL given in <tt>createConnection</tt> with
the URLs it is configured with. If a matching URL is found, it will use the credentials in
that configuration to supply to the <tt>URLConnection</tt>.</p>
 <h3 id="remote-services">Remote services</h3>
 <p>We've now closed the circle: we not only have defined how remote endpoints can apply
authentication, but also how all calling parties can remain using these remote endpoints without
having to be aware of authentication. The only thing left, is a summary of which remote endpoints
currently exist in ACE.<br />
@@ -278,6 +278,12 @@ All remote services are configurable wit
 <td><tt>/ace</tt></td>
 <td><tt>o.a.a.webui.vaadin</tt></td>
 </tr>
+<tr>
+<td>&#160;</td>
+<td>&#160;</td>
+<td>&#160;</td>
+<td>&#160;</td>
+</tr>
 </tbody>
 </table>
 <h2 id="configuring-authentication">Configuring authentication</h2>
@@ -378,7 +384,8 @@ For accessing our <tt>BundleServlet</tt>
 </pre></div>
 
 
-<p>When this configuration is supplied to the <tt>ConnectionFactory</tt>,
it will provide a basic HTTP authentication header to each connection created for any URL
starting with "<tt>http://localhost:8080/obr/</tt>"<sup id="fnref:7"><a
href="#fn:7" rel="footnote">7</a></sup>. </p>
+<p>When this configuration is supplied to the <tt>ConnectionFactory</tt>,
it will provide a basic HTTP authentication header to each connection created for any URL
starting with "<tt>http://localhost:8080/obr/</tt>"<sup id="fnref:7"><a
href="#fn:7" rel="footnote">7</a></sup>.<br />
+To disable authentication for a particular URL, the <tt>authentication.type</tt>
option can be set to <tt>none</tt>. </p>
 <h3 id="configuring-the-management-agent">Configuring the management agent</h3>
 <p>The management agent itself also needs to use authentication to communicate with
the remote services of the ACE server. It reuses the <tt>ConnectionFactory</tt>
service for this, so it needs to obtain the same set of configurations as described in the
previous section. The only thing we need to do is tell the management agent were it can find
those configuration file(s):</p>
 <div class="codehilite"><pre><span class="o">[</span>localhost:~/<span
class="o">]</span><span class="nv">$ </span>java -jar org.apache.ace.launcher-0.8.1-SNAPSHOT.jar
<span class="se">\</span>
@@ -389,11 +396,23 @@ For accessing our <tt>BundleServlet</tt>
 
 
 <p>Alternatively, one could adapt the code of the management agent to use the <tt>ConfigAdmin</tt>
service directly for creating the individual configurations using the service factory PID
<tt>org.apache.ace.connectionfactory</tt>. </p>
-<h2 id="extending-the-authentication-mechanism">Extending the authentication mechanism</h2>
-<p>…</p>
-<h3 id="authentication-processors">Authentication processors</h3>
-<p>…</p>
-<h3></h3>
+<h3 id="configuring-users">Configuring users</h3>
+<p>In order to successfully authenticate a user, it needs a corresponding <tt>User</tt>
that can be obtained from the <tt>UserAdmin</tt> service. Initially, ACE imports
a small set of users and roles defined in the "<tt>org.apache.ace.server.repository.factory/ace-user.cfg</tt>"
configuration file. One could update this file in order to add users<sup id="fnref:8"><a
href="#fn:8" rel="footnote">8</a></sup>, or add them, for example, to an LDAP-service
and make the <tt>UserAdmin</tt> service retrieve users from this backend. The
exact details on how to configure this are beyond this article.</p>
+<h2 id="troubleshooting">Troubleshooting</h2>
+<p>If after configuring the authentication of ACE things no longer work, it can be
hard to find the exact cause of this. In this section, some pointers are given to help you
to find the probably cause of the problem.</p>
+<dl>
+<dt>I've enabled authentication, but I can still use all services without passing any
credentials!</dt>
+<dd>if you've updated the configuration files of a running server or management agent,
the configuration files are not automatically picked up by default. You need to stop the server/management
agent, clean its felix-cache folder and start it again.</dd>
+<dt>With authentication enabled, how can I test whether the endpoints accept my credentials?</dt>
+<dd>In order to test the remote endpoints of ACE, you can use a tool like <a href="http://code.google.com/p/rest-client/">REST
client</a>. It allows you to enter credentials for any given URL.</dd>
+<dt>After enabling authentication, I do not get any errors after starting the ACE server,
but it doesn't function correctly!</dt>
+<dd>Is the connection factory properly configured? Are <em>all</em> <tt>authentication.type</tt>
options correctly set to <tt>basic</tt> and are the username/passwords correctly
set? Are the configured base URLs not overlapping each other (e.g.: <tt>baseURL = http://localhost:8080/</tt>
and <tt>baseURL = http://localhost:8080/obr</tt>)?</dd>
+<dt>After enabling authentication, the management agent(s) no longer functions/I do
not see them added in the web UI.</dt>
+<dd>Did you pass the <tt>auth=/path/to/config/file(s)</tt> option to the
management agent to configure the connection factory? Are those files correctly stating the
"<tt>authentication.type = basic</tt>", including the username and password for
the desired URLs? Can you access the URLs mentioned in the configuration files with a tool
like <a href="http://code.google.com/p/rest-client/">REST client</a>?</dd>
+<dt>I do not want basic HTTP authentication, I want to use (fill in the kind of authentication)!</dt>
+<dd>The current implementation is quite simple and basic, but it can be extended by
means of custom authentication processors.</dd>
+</dl>
+<h2 id="notes">Notes</h2>
 <div class="footnote">
 <hr />
 <ol>
@@ -418,6 +437,9 @@ For accessing our <tt>BundleServlet</tt>
 <li id="fn:7">
 <p>Currently, a simple <tt>String#startsWith()</tt> is used to determine
whether or not a URL matches a configuration. This might change in the future when a more
sophisticated URL-matching strategy is needed.&#160;<a href="#fnref:7" rev="footnote"
title="Jump back to footnote 7 in the text">&#8617;</a></p>
 </li>
+<li id="fn:8">
+<p>Make sure to clean the <tt>felix-cache</tt> directory before restarting
the server, otherwise the new configuration files will not be picked up!&#160;<a href="#fnref:8"
rev="footnote" title="Jump back to footnote 8 in the text">&#8617;</a></p>
+</li>
 </ol>
 </div></div>
       <hr>



Mime
View raw message