Author: jawi
Date: Thu Apr 26 10:20:29 2012
New Revision: 1330750
URL: http://svn.apache.org/viewvc?rev=1330750&view=rev
Log:
Finalized the article.
Modified:
ace/site/trunk/content/dev-doc/design/ace-authentication.mdtext
Modified: ace/site/trunk/content/dev-doc/design/ace-authentication.mdtext
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/design/ace-authentication.mdtext?rev=1330750&r1=1330749&r2=1330750&view=diff
==============================================================================
--- ace/site/trunk/content/dev-doc/design/ace-authentication.mdtext (original)
+++ ace/site/trunk/content/dev-doc/design/ace-authentication.mdtext Thu Apr 26
10:20:29 2012
@@ -9,7 +9,8 @@ Revision 0.9, last updated: April 26th,
## Introduction
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
*authentication*, which gives you the ability to verify the identity of
someone. Once the identity is known, one can apply *authorization* 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.
+In this article, the recently added authentication layer of ACE is explained
in more depth and how to configure authentication to your situation.
+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.
## Communication paths
@@ -17,9 +18,9 @@ In this article, the recently added auth
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.
-Figure 1: Overview of components and communication paths.
+**Figure 1**: Overview of components and communication paths.
-Figure 1 represents several of the communication paths that can be identified
(denoted by the circled digits):
+In the above figure, several of the communication paths (denoted by the
circled digits) that can be identified in ACE are represented:
1. the client communicates to the ACE server by means of both direct calls to
its services as well as remote (HTTP[^1]) calls;
2. a management agent (representing the target) communicates to the ACE server
through remote calls;
@@ -42,10 +43,10 @@ The high-level design for security in AC
2. should be optional. If no authentication is desired, one should be able to
remove its services from the ACE distribution;
3. 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.
-Based on these requirements, the design of the authentication layer is
represented in the following figure:
+Based on these requirements, the design of the authentication layer is
represented in the following figure: {#fig2}
-Figure 2: Authentication layer class diagram.
+**Figure 2**: Authentication layer class diagram.
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:
@@ -58,7 +59,7 @@ The <tt>AuthenticationService</tt> is re
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 *very*
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 leverage
the s
ervice 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:
-Figure 3: Connection Factory class diagram.
+**Figure 3**: Connection Factory class diagram.
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>.
@@ -77,7 +78,7 @@ Name | Description | Endpoint | Configur
<tt>RepositoryReplicationServlet</tt> | allows *relay nodes* to replicate the
internal repositories of ACE | <tt>/replication</tt> |
<tt>o.a.a.repository.servlet.<br/>RepositoryReplicationServlet</tt>
<tt>RESTClientServlet</tt> | provides the RESTful interface to ACE
|<tt>/client</tt> | <tt>o.a.a.client.rest</tt>
<tt>VaadinServlet</tt> | provides the Vaadin web interface | <tt>/ace</tt> |
<tt>o.a.a.webui.vaadin</tt>
-
+  |   |   |  
## Configuring authentication
@@ -188,7 +189,8 @@ For accessing our <tt>BundleServlet</tt>
# What is the base URL that these credentials apply to:
authentication.baseURL = http://localhost:8080/obr/
-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>"[^7].
+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>"[^7].
+To disable authentication for a particular URL, the
<tt>authentication.type</tt> option can be set to <tt>none</tt>.
### Configuring the management agent
@@ -202,15 +204,32 @@ The management agent itself also needs t
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>.
-## Extending the authentication mechanism
+### Configuring users
+
+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[^8], 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.
+
+
+## Troubleshooting
+
+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.
-â¦
+I've enabled authentication, but I can still use all services without passing
any credentials!
+: 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.
-### Authentication processors
+With authentication enabled, how can I test whether the endpoints accept my
credentials?
+: In order to test the remote endpoints of ACE, you can use a tool like [REST
client](http://code.google.com/p/rest-client/). It allows you to enter
credentials for any given URL.
-â¦
+After enabling authentication, I do not get any errors after starting the ACE
server, but it doesn't function correctly!
+: Is the connection factory properly configured? Are *all*
<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>)?
-###
+After enabling authentication, the management agent(s) no longer functions/I
do not see them added in the web UI.
+: 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 [REST
client](http://code.google.com/p/rest-client/)?
+
+I do not want basic HTTP authentication, I want to use (fill in the kind of
authentication)!
+: The current implementation is quite simple and basic, but it can be extended
by means of custom authentication processors.
+
+
+## Notes
[^1]: Other communication protocols could be used as well. However, currently,
only HTTP is natively supported by ACE. For the remainder of this article,
we'll assume HTTP as protocol.
@@ -225,3 +244,5 @@ Alternatively, one could adapt the code
[^6]: Note that we're using a configuration dependency for this service. This
way, the configuration **must** be present before the service itself is
registered, which allows us to determine if authentication should be used or
not.
[^7]: 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.
+
+[^8]: Make sure to clean the <tt>felix-cache</tt> directory before restarting
the server, otherwise the new configuration files will not be picked up!
\ No newline at end of file
