You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ace.apache.org by ja...@apache.org on 2014/11/25 11:59:30 UTC
svn commit: r1641565 - in /ace/site/trunk/content: ./ docs/ docs/design/
Author: jawi
Date: Tue Nov 25 10:59:30 2014
New Revision: 1641565
URL: http://svn.apache.org/r1641565
Log:
Split the authentication docs:
- added a configuration guide on using and configuring authentication
in ACE;
- moved the nitty-gritty details on the design and implementation to a
separate design document.
Added:
ace/site/trunk/content/docs/design/auth_api.svg (with props)
ace/site/trunk/content/docs/design/auth_connectionfactory.svg (with props)
ace/site/trunk/content/docs/design/auth_main_components.svg (with props)
ace/site/trunk/content/docs/design/authentication-design.mdtext (with props)
ace/site/trunk/content/docs/using-basic-auth.mdtext (with props)
Removed:
ace/site/trunk/content/docs/ace-authentication.mdtext
ace/site/trunk/content/docs/auth_api.svg
ace/site/trunk/content/docs/auth_connectionfactory.svg
ace/site/trunk/content/docs/auth_main_components.svg
Modified:
ace/site/trunk/content/docs.mdtext
Modified: ace/site/trunk/content/docs.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs.mdtext?rev=1641565&r1=1641564&r2=1641565&view=diff
==============================================================================
--- ace/site/trunk/content/docs.mdtext (original)
+++ ace/site/trunk/content/docs.mdtext Tue Nov 25 10:59:30 2014
@@ -26,15 +26,15 @@ background](/docs/history-and-background
Resources that go into more detail on using Apache ACE:
* read all about using Apache ACE in the [users guide](/docs/user-guide.html);
-* to manage users using ACE's web UI, read the [user management
+* all about managing users using ACE's web UI can be read in the [user management
guide](/docs/user-management-guide.html);
* [information about the various roles used in Apache ACE](/docs/ace-roles.html);
* accessing Apache ACE [using the Gogo shell](/docs/shell-api.html);
* accessing Apache ACE from [its REST API](/docs/rest-api.html);
* to handle a large number of targets, you can make use of [intermediate relay
servers](/docs/configuring-relay-servers.html);
-* configuring ACE authentication is described in the [authentication
- guide](/docs/ace-authentication.html);
+* configuring HTTP Basic authentication in ACE is described in the [authentication
+ guide](/docs/using-basic-auth.html);
* configuring ACE to use two-way SSL is described in [using client
certificates](/docs/using-client-certificates.html);
* various deployment strategies for Apache ACE are described in the [ACE deployment
@@ -62,11 +62,12 @@ There are several resources available on
* [adding support for new types of artifacts](/docs/adding-custom-artifact-types.html);
* detailed analysis documentation giving background information on some development
principles currently used:
- * [audit log analysis](/docs/analysis/auditlog-analysis.html);
- * [bundle repository analysis](/docs/analysis/bundlerepository-analysis.html);
- * [security analysis](/docs/analysis/security-analysis.html);
- * [template mechanism](/docs/analysis/template-mechanism.html).
+ - [audit log analysis](/docs/analysis/auditlog-analysis.html);
+ - [bundle repository analysis](/docs/analysis/bundlerepository-analysis.html);
+ - [security analysis](/docs/analysis/security-analysis.html);
+ - [template mechanism](/docs/analysis/template-mechanism.html).
* detailed design documentation:
- * [remote interface design](/docs/design/remote-interfaces.html);
- * [audit log details](/docs/design/auditlog-protocol.html);
+ - [authentication design](/docs/design/authentication-design.html);
+ - [remote interface design](/docs/design/remote-interfaces.html);
+ - [audit log details](/docs/design/auditlog-protocol.html);
Added: ace/site/trunk/content/docs/design/auth_api.svg
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/design/auth_api.svg?rev=1641565&view=auto
==============================================================================
--- ace/site/trunk/content/docs/design/auth_api.svg (added)
+++ ace/site/trunk/content/docs/design/auth_api.svg Tue Nov 25 10:59:30 2014
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg height="512" version="1.1" width="716" xmlns="http://www.w3.org/2000/svg">
+<rect fill="#ffffff" height="88" stroke="#ffffff" stroke-width="1" width="152" x="14" y="158"/>
+<rect fill="none" height="88" stroke="#000000" stroke-width="1" width="152" x="14" y="158"/>
+<text font-family="Lucida Grande" font-size="13" x="21" y="192">
+AuthenticationService</text>
+<text font-family="Lucida Grande" font-size="13" x="42" y="173">
+<<interface>></text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="152" x="14" y="202"/>
+<text font-family="Lucida Grande" font-size="13" x="18" y="217">
+authenticate() : User</text>
+<rect fill="#ffffff" height="88" stroke="#ffffff" stroke-width="1" width="168" x="366" y="158"/>
+<rect fill="none" height="88" stroke="#000000" stroke-width="1" width="168" x="366" y="158"/>
+<text font-family="Lucida Grande" font-size="13" x="373" y="192">
+AuthenticationProcessor</text>
+<text font-family="Lucida Grande" font-size="13" x="402" y="173">
+<<interface>></text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="168" x="366" y="202"/>
+<text font-family="Lucida Grande" font-size="13" x="370" y="217">
+canHandle() : Boolean</text>
+<text font-family="Lucida Grande" font-size="13" x="370" y="234">
+authenticate() : User</text>
+<rect fill="#ffffff" height="72" stroke="#ffffff" stroke-width="1" width="223" x="206" y="326"/>
+<rect fill="none" height="72" stroke="#000000" stroke-width="1" width="223" x="206" y="326"/>
+<text font-family="Lucida Grande" font-size="13" x="211" y="340">
+PasswordAuthenticationProcessor</text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="223" x="206" y="350"/>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="223" x="206" y="373"/>
+<rect fill="#ffffff" height="68" stroke="#ffffff" stroke-width="1" width="224" x="478" y="326"/>
+<rect fill="none" height="68" stroke="#000000" stroke-width="1" width="224" x="478" y="326"/>
+<text font-family="Lucida Grande" font-size="13" x="483" y="340">
+BasicHttpAuthenticationProcessor</text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="224" x="478" y="350"/>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="224" x="478" y="371"/>
+<rect fill="#ffffff" height="66" stroke="#ffffff" stroke-width="1" width="168" x="366" y="14"/>
+<rect fill="none" height="66" stroke="#000000" stroke-width="1" width="168" x="366" y="14"/>
+<text font-family="Lucida Grande" font-size="13" x="415" y="48">
+UserAdmin</text>
+<text font-family="Lucida Grande" font-size="13" x="402" y="29">
+<<interface>></text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="168" x="366" y="58"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="598" x2="598" y1="326" y2="321"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="598" x2="598" y1="316" y2="311"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="598" x2="598" y1="306" y2="301"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="598" x2="598" y1="296" y2="291"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="598" x2="593" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="588" x2="583" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="578" x2="573" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="568" x2="563" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="558" x2="553" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="548" x2="543" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="538" x2="533" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="528" x2="523" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="518" x2="513" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="508" x2="503" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="498" x2="493" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="488" x2="483" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="478" x2="473" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="468" x2="463" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="458" x2="454" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="286" y2="281"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="276" y2="271"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="266" y2="261"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="256" y2="251"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="246" y2="245"/>
+<polygon fill="#ffffff" points="454,245 461,257 447,257" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="454,245 461,257 447,257" stroke="#000000" stroke-width="1"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="310" x2="310" y1="326" y2="321"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="310" x2="310" y1="316" y2="311"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="310" x2="310" y1="306" y2="301"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="310" x2="310" y1="296" y2="291"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="310" x2="315" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="320" x2="325" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="330" x2="335" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="340" x2="345" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="350" x2="355" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="360" x2="365" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="370" x2="375" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="380" x2="385" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="390" x2="395" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="400" x2="405" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="410" x2="415" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="420" x2="425" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="430" x2="435" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="440" x2="445" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="450" x2="454" y1="286" y2="286"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="286" y2="281"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="276" y2="271"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="266" y2="261"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="256" y2="251"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="246" y2="245"/>
+<polygon fill="#ffffff" points="454,245 461,257 447,257" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="454,245 461,257 447,257" stroke="#000000" stroke-width="1"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="158" y2="153"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="148" y2="143"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="138" y2="133"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="128" y2="123"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="118" y2="113"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="108" y2="103"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="98" y2="93"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="88" y2="83"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="461" x2="454" y1="91" y2="79"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="447" x2="454" y1="91" y2="79"/>
+<text font-family="Lucida Grande" font-size="13" x="470" y="120">
+<<call>></text>
+<rect fill="#ffffff" height="68" stroke="#ffffff" stroke-width="1" width="227" x="342" y="430"/>
+<rect fill="none" height="68" stroke="#000000" stroke-width="1" width="227" x="342" y="430"/>
+<text font-family="Lucida Grande" font-size="13" x="347" y="444">
+ClientCertAuthenticationProcessor</text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="227" x="342" y="454"/>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="227" x="342" y="475"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="430" y2="425"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="420" y2="415"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="410" y2="405"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="400" y2="395"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="390" y2="385"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="380" y2="375"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="370" y2="365"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="360" y2="355"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="350" y2="345"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="340" y2="335"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="330" y2="325"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="320" y2="315"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="310" y2="305"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="300" y2="295"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="290" y2="285"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="280" y2="275"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="270" y2="265"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="260" y2="255"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="454" x2="454" y1="250" y2="245"/>
+<polygon fill="#ffffff" points="454,245 461,257 447,257" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="454,245 461,257 447,257" stroke="#000000" stroke-width="1"/>
+<polyline fill="none" points="165,206 366,206" stroke="#000000" stroke-width="1"/>
+<polygon fill="#ffffff" points="165,206 175,201 185,206 175,211" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="165,206 175,201 185,206 175,211" stroke="#000000" stroke-width="1"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="354" x2="366" y1="213" y2="206"/>
+<line fill="#000000" stroke="#000000" stroke-width="1" x1="354" x2="366" y1="199" y2="206"/>
+<text font-family="Lucida Grande" font-size="13" x="225" y="201">
+<<delegates>></text>
+<text font-family="Lucida Grande" font-size="13" x="349" y="225">
+*</text>
+</svg>
Propchange: ace/site/trunk/content/docs/design/auth_api.svg
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: ace/site/trunk/content/docs/design/auth_api.svg
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: ace/site/trunk/content/docs/design/auth_connectionfactory.svg
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/design/auth_connectionfactory.svg?rev=1641565&view=auto
==============================================================================
--- ace/site/trunk/content/docs/design/auth_connectionfactory.svg (added)
+++ ace/site/trunk/content/docs/design/auth_connectionfactory.svg Tue Nov 25 10:59:30 2014
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg height="226" version="1.1" width="262" xmlns="http://www.w3.org/2000/svg">
+<rect fill="#ffffff" height="70" stroke="#ffffff" stroke-width="1" width="234" x="14" y="142"/>
+<rect fill="none" height="70" stroke="#000000" stroke-width="1" width="234" x="14" y="142"/>
+<text font-family="Lucida Grande" font-size="13" x="72" y="176">
+ConnectionFactory</text>
+<text font-family="Lucida Grande" font-size="13" x="83" y="157">
+<<interface>></text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="234" x="14" y="186"/>
+<text font-family="Lucida Grande" font-size="13" x="18" y="201">
+createConnection() : URLConnection</text>
+<rect fill="#ffffff" height="72" stroke="#ffffff" stroke-width="1" width="232" x="14" y="14"/>
+<rect fill="none" height="72" stroke="#000000" stroke-width="1" width="232" x="14" y="14"/>
+<text font-family="Lucida Grande" font-size="13" x="57" y="48">
+ManagedServiceFactory</text>
+<text font-family="Lucida Grande" font-size="13" x="82" y="29">
+<<interface>></text>
+<rect fill="#000000" height="1" stroke="#000000" stroke-width="1" width="232" x="14" y="58"/>
+<polyline fill="none" points="131,142 131,85" stroke="#333399" stroke-width="1"/>
+<polygon fill="#ffffff" points="131,85 138,97 124,97" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="131,85 138,97 124,97" stroke="#333399" stroke-width="1"/>
+</svg>
Propchange: ace/site/trunk/content/docs/design/auth_connectionfactory.svg
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: ace/site/trunk/content/docs/design/auth_connectionfactory.svg
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: ace/site/trunk/content/docs/design/auth_main_components.svg
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/design/auth_main_components.svg?rev=1641565&view=auto
==============================================================================
--- ace/site/trunk/content/docs/design/auth_main_components.svg (added)
+++ ace/site/trunk/content/docs/design/auth_main_components.svg Tue Nov 25 10:59:30 2014
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg height="516" version="1.1" width="1006" xmlns="http://www.w3.org/2000/svg">
+<rect fill="#ffffff" height="180" stroke="#ffffff" stroke-width="1" width="200" x="14" y="122"/>
+<rect fill="none" height="180" stroke="#000000" stroke-width="1" width="200" x="14" y="122"/>
+<polygon fill="#ffffff" points="14,122 34,102 234,102 214,122" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="14,122 34,102 234,102 214,122" stroke="#000000" stroke-width="1"/>
+<polygon fill="#ffffff" points="234,102 234,282 214,302 214,122" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="234,102 234,282 214,302 214,122" stroke="#000000" stroke-width="1"/>
+<text font-family="Lucida Grande" font-size="13" x="22" y="137">
+Management Agent</text>
+<rect fill="#ffffff" height="300" stroke="#ffffff" stroke-width="1" width="516" x="334" y="122"/>
+<rect fill="none" height="300" stroke="#000000" stroke-width="1" width="516" x="334" y="122"/>
+<polygon fill="#ffffff" points="334,122 354,102 870,102 850,122" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="334,122 354,102 870,102 850,122" stroke="#000000" stroke-width="1"/>
+<polygon fill="#ffffff" points="870,102 870,402 850,422 850,122" stroke="#ffffff" stroke-width="1"/>
+<polygon fill="none" points="870,102 870,402 850,422 850,122" stroke="#000000" stroke-width="1"/>
+<text font-family="Lucida Grande" font-size="13" x="342" y="137">
+Management Server</text>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="672" y="174"/>
+<rect fill="none" height="80" stroke="#00ff" stroke-width="1" width="120" x="672" y="174"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="672" y="174"/>
+<rect fill="none" height="80" stroke="#000000" stroke-width="1" width="120" x="672" y="174"/>
+<rect fill="#ffffff" height="0" stroke="#ffffff" stroke-width="1" width="108" x="683" y="175"/>
+<text font-family="Lucida Grande" font-size="13" x="718" y="189">
+Client</text>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="662" y="195"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="662" y="195"/>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="662" y="222"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="662" y="222"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="56" y="174"/>
+<rect fill="none" height="80" stroke="#00ff" stroke-width="1" width="120" x="56" y="174"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="56" y="174"/>
+<rect fill="none" height="80" stroke="#000000" stroke-width="1" width="120" x="56" y="174"/>
+<rect fill="#ffffff" height="0" stroke="#ffffff" stroke-width="1" width="108" x="67" y="175"/>
+<text font-family="Lucida Grande" font-size="13" x="101" y="189">
+Target</text>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="46" y="195"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="46" y="195"/>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="46" y="222"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="46" y="222"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="672" y="310"/>
+<rect fill="none" height="80" stroke="#00ff" stroke-width="1" width="120" x="672" y="310"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="672" y="310"/>
+<rect fill="none" height="80" stroke="#000000" stroke-width="1" width="120" x="672" y="310"/>
+<rect fill="#ffffff" height="0" stroke="#ffffff" stroke-width="1" width="108" x="683" y="311"/>
+<text font-family="Lucida Grande" font-size="13" x="692" y="325">
+REST Interface</text>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="662" y="331"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="662" y="331"/>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="662" y="358"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="662" y="358"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="376" y="174"/>
+<rect fill="none" height="80" stroke="#00ff" stroke-width="1" width="120" x="376" y="174"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="376" y="174"/>
+<rect fill="none" height="80" stroke="#000000" stroke-width="1" width="120" x="376" y="174"/>
+<rect fill="#ffffff" height="0" stroke="#ffffff" stroke-width="1" width="108" x="387" y="175"/>
+<text font-family="Lucida Grande" font-size="13" x="422" y="189">
+Server</text>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="366" y="195"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="366" y="195"/>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="366" y="222"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="366" y="222"/>
+<polygon fill="#ffffff" points="758,14 981,14 991,24 991,77 758,77 758,14" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="758,14 981,14 991,24 991,77 758,77 758,14" stroke="#000000" stroke-width="1"/>
+<polygon fill="#ffffff" points="981,14 991,24 981,24 981,14" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="981,14 991,24 981,24 981,14" stroke="#000000" stroke-width="1"/>
+<text font-family="Lucida Grande" font-size="13" x="761" y="30">
+Provides client-side interfaces for </text>
+<text font-family="Lucida Grande" font-size="13" x="761" y="46">
+deployment packages, audit logs, </text>
+<text font-family="Lucida Grande" font-size="13" x="761" y="62">
+OBR access and so on.</text>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="77" y2="82"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="87" y2="92"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="97" y2="102"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="107" y2="112"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="117" y2="122"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="127" y2="132"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="137" y2="142"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="147" y2="152"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="157" y2="162"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="167" y2="172"/>
+<polygon fill="#ffffff" points="462,14 679,14 689,24 689,77 462,77 462,14" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="462,14 679,14 689,24 689,77 462,77 462,14" stroke="#000000" stroke-width="1"/>
+<polygon fill="#ffffff" points="679,14 689,24 679,24 679,14" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="679,14 689,24 679,24 679,14" stroke="#000000" stroke-width="1"/>
+<text font-family="Lucida Grande" font-size="13" x="465" y="30">
+Provides the real services for</text>
+<text font-family="Lucida Grande" font-size="13" x="465" y="46">
+deployment packages, audit logs,</text>
+<text font-family="Lucida Grande" font-size="13" x="465" y="62">
+OBR access and so on.</text>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="77" y2="82"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="87" y2="92"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="97" y2="102"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="107" y2="112"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="117" y2="122"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="127" y2="132"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="137" y2="142"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="147" y2="152"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="157" y2="162"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="167" y2="172"/>
+<polygon fill="#ffffff" points="758,446 939,446 949,456 949,501 758,501 758,446" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="758,446 939,446 949,456 949,501 758,501 758,446" stroke="#000000" stroke-width="1"/>
+<polygon fill="#ffffff" points="939,446 949,456 939,456 939,446" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="939,446 949,456 939,456 939,446" stroke="#000000" stroke-width="1"/>
+<text font-family="Lucida Grande" font-size="13" x="761" y="462">
+Provides a REST API for the </text>
+<text font-family="Lucida Grande" font-size="13" x="761" y="478">
+entire client-API.</text>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="446" y2="441"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="436" y2="431"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="426" y2="421"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="416" y2="411"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="406" y2="401"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="774" x2="774" y1="396" y2="391"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="376" y="310"/>
+<rect fill="none" height="80" stroke="#00ff" stroke-width="1" width="120" x="376" y="310"/>
+<rect fill="#ffffff" height="80" stroke="#ffffff" stroke-width="1" width="120" x="376" y="310"/>
+<rect fill="none" height="80" stroke="#000000" stroke-width="1" width="120" x="376" y="310"/>
+<rect fill="#ffffff" height="0" stroke="#ffffff" stroke-width="1" width="108" x="387" y="311"/>
+<text font-family="Lucida Grande" font-size="13" x="419" y="325">
+Web UI</text>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="366" y="331"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="366" y="331"/>
+<rect fill="#ffffff" height="10" stroke="#ffffff" stroke-width="1" width="20" x="366" y="358"/>
+<rect fill="none" height="10" stroke="#000000" stroke-width="1" width="20" x="366" y="358"/>
+<polygon fill="#ffffff" points="462,446 624,446 634,456 634,501 462,501 462,446" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="462,446 624,446 634,456 634,501 462,501 462,446" stroke="#000000" stroke-width="1"/>
+<polygon fill="#ffffff" points="624,446 634,456 624,456 624,446" stroke="#ffffff" stroke-width="1"/>
+<polyline fill="none" points="624,446 634,456 624,456 624,446" stroke="#000000" stroke-width="1"/>
+<text font-family="Lucida Grande" font-size="13" x="465" y="462">
+Provides a web interface </text>
+<text font-family="Lucida Grande" font-size="13" x="465" y="478">
+for the entire client-API.</text>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="446" y2="441"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="436" y2="431"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="426" y2="421"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="416" y2="411"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="406" y2="401"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="478" x2="478" y1="396" y2="391"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="672" x2="667" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="662" x2="657" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="652" x2="647" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="642" x2="637" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="632" x2="627" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="622" x2="617" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="612" x2="607" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="602" x2="597" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="592" x2="587" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="582" x2="577" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="572" x2="567" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="562" x2="557" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="552" x2="547" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="542" x2="537" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="532" x2="527" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="522" x2="517" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="512" x2="507" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="502" x2="497" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="507" x2="495" y1="207" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="507" x2="495" y1="221" y2="214"/>
+<text font-family="Lucida Grande" font-size="13" x="531" y="201">
+â direct + remote</text>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="726" x2="726" y1="310" y2="305"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="726" x2="726" y1="300" y2="295"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="726" x2="726" y1="290" y2="285"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="726" x2="726" y1="280" y2="275"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="726" x2="726" y1="270" y2="265"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="726" x2="726" y1="260" y2="255"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="733" x2="726" y1="265" y2="253"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="719" x2="726" y1="265" y2="253"/>
+<text font-family="Lucida Grande" font-size="13" x="734" y="287">
+⢠direct + remote</text>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="495" x2="499" y1="310" y2="309"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="504" x2="509" y1="307" y2="306"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="514" x2="518" y1="304" y2="303"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="523" x2="528" y1="301" y2="300"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="533" x2="538" y1="298" y2="297"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="542" x2="547" y1="295" y2="294"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="552" x2="557" y1="292" y2="290"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="561" x2="566" y1="289" y2="287"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="571" x2="576" y1="286" y2="284"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="581" x2="585" y1="283" y2="281"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="590" x2="595" y1="280" y2="278"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="600" x2="605" y1="277" y2="275"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="609" x2="614" y1="274" y2="272"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="619" x2="624" y1="270" y2="269"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="628" x2="633" y1="267" y2="266"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="638" x2="643" y1="264" y2="263"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="648" x2="652" y1="261" y2="260"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="657" x2="662" y1="258" y2="257"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="667" x2="672" y1="255" y2="253"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="662" x2="672" y1="263" y2="253"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="658" x2="672" y1="250" y2="253"/>
+<text font-family="Lucida Grande" font-size="13" x="556" y="305">
+⣠direct + remote</text>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="175" x2="180" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="185" x2="190" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="195" x2="200" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="205" x2="210" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="215" x2="220" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="225" x2="230" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="235" x2="240" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="245" x2="250" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="255" x2="260" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="265" x2="270" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="275" x2="280" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="285" x2="290" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="295" x2="300" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="305" x2="310" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="315" x2="320" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="325" x2="330" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="335" x2="340" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="345" x2="350" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="355" x2="360" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="365" x2="370" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="375" x2="376" y1="214" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="364" x2="376" y1="221" y2="214"/>
+<line fill="#333399" stroke="#333399" stroke-width="1" x1="364" x2="376" y1="207" y2="214"/>
+<text font-family="Lucida Grande" font-size="13" x="258" y="200">
+â¡ remote</text>
+</svg>
Propchange: ace/site/trunk/content/docs/design/auth_main_components.svg
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: ace/site/trunk/content/docs/design/auth_main_components.svg
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: ace/site/trunk/content/docs/design/authentication-design.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/design/authentication-design.mdtext?rev=1641565&view=auto
==============================================================================
--- ace/site/trunk/content/docs/design/authentication-design.mdtext (added)
+++ ace/site/trunk/content/docs/design/authentication-design.mdtext Tue Nov 25 10:59:30 2014
@@ -0,0 +1,279 @@
+Title: ACE authentication design
+
+
+[TOC]
+
+## Communication paths
+
+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.
+
+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;
+3. the REST API exposes the entire client and server APIs in a RESTful way. Communication
+ to the client occurs by both direct and remote calls;
+4. the Vaadin Web UI exposes the entire client API as web application. Similar as the REST
+ API, it communicates both directly as remotely with the client.
+
+As can be seen from the above figure, most of the communication paths are remoted. The
+reason for this is twofold:
+
+1. It allows reuse of components; for example access to the OBR-servlet is used by the
+ both the client-API as well the web UI to upload new artifacts;
+2. it enables scalability by allowing components to be deployed on different machines; for
+ example, one does not need to run the client on the same machine as the server. This
+ could be useful for working on high-latency networks.
+
+All direct (i.e., non remoted) communication paths do not need to be authenticated, as
+they require that both caller and callee run in the same virtual machine, making it
+impossible to be used outside the virtual machine[^2]. Hence, we only need to add an
+authentication layer to the remote endpoints. However, adding authentication to all remote
+endpoints poses us with the challenge to let the "internal" communication paths that use
+remote calls to authenticate themselves as well. Not doing so would prevent ACE from
+functioning correctly. A disadvantage of this approach is that it is an all-or-nothing
+approach, either all users of the remote endpoints use authentication, or none of them.
+However, the way users authenticate themselves can be different, meaning that one set of
+users can use basic authentication to identify themselves, while another set uses client
+certificates to identify themselves.
+
+
+## Design
+
+The high-level design for security in ACE is explained in the [remote interface
+design](/docs/design/remote-interfaces.html). From this design, we can derive several
+requirements for the design of ACE's authentication layer:
+
+1. should be applicable and configurable for all remoted endpoints. If a new endpoint is
+ added to ACE, it should be easy to add and configure authentication for it;
+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: {#fig2}
+
+
+**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:
+
+1. <tt>AuthenticationService#authenticate</tt> is called with a blob of data, for example
+ a <tt>HttpServletRequest</tt>;
+2. for each known <tt>AuthenticationProcessor</tt>:
+ - <tt>AuthenticationProcessor#canHandle</tt> is called with that blob of data. In this
+ method, an authentication processor can decide whether the given blob is something
+ it can handle or not;
+ - if it can be handled, the <tt>AuthenticationProcessor#authenticate</tt> is called
+ with that blob of data, along with an instance of the <tt>UserAdmin</tt> service.
+ The authentication processor is now responsible for converting the blob of data to
+ an authenticated user, if possible.
+3. if a <tt>User</tt> object is returned from the authentication service[^3], the
+ authentication phase will be regarded as successful. If *no* <tt>User</tt> object is
+ returned, the authentication phase will be regarded unsuccessful.
+
+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 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:
+
+
+**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>.
+
+
+### Remote services
+
+In the section on the design of the authentication layer, we've mentioned that if a remote
+service wants to make use of authentication, it can make use of the
+<tt>AuthenticationService</tt>. However, one of the design requirements was that
+authentication should be optional as well. In order to enable or disable authentication,
+each remote service needs to do the following:
+
+1. add a **mandatory** configuration property <tt>authentication.enabled = false|true</tt>
+ to their configuration. Although any kind of name for this configuration property can
+ be used, it is *strongly* advised to stick to the same name for all services;
+2. when the configuration of a remote service is updated, it should add a service
+ dependency to the <tt>AuthenticationService</tt>. By making this service **required**
+ if authentication is *enabled*, and **optional** when authentication is *disabled*, we
+ can adhere to the requirement of optionality for authentication;
+3. in case authentication is *enabled*, each request the service obtains needs to be
+ passed to the <tt>AuthenticationService</tt> first, and depending on its outcome, the
+ request can continue or not.
+
+To make this more concrete, we walk through an example of how the <tt>BundleServlet</tt>
+is to be configured. As this is a servlet (as almost all other remote endpoints in ACE),
+we can intercept all service requests by overriding the <tt>Servlet#service()</tt> method
+and perform our authentication check there. If this check is successful, we continue
+passing the service request, and return a "401 - Unauthorized" when the check is
+unsuccessful.
+
+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. All remote services are configurable with
+respect to the endpoint they can be accessed. The following table shows an overview of the
+remote services, including the default endpoint they use:
+
+Name | Description | Endpoint | Configuration PID[^4]
+------- | --------------- | ------------ | ---------------------
+<tt>BundleServlet</tt> | provides access to the OBR (bundle repository) of ACE | <tt>/obr</tt> | <tt>o.a.a.obr.servlet</tt>
+<tt>DeploymentServlet</tt> | handles the actual provisioning of deployment packages to a target | <tt>/deployment</tt> |<tt>o.a.a.deployment.servlet</tt>
+<tt>LogServlet</tt> | allows any number of logs for a target to be synchronized and accessed | <tt>/auditlog</tt>[^5] | <tt>o.a.a.server.log.servlet.factory</tt><br/>**note: this is a configuration factory!**
+<tt>RepositoryServlet</tt> | provides access to the various (artifact/feature/distribution/target) internal repositories of ACE | <tt>/repository</tt> | <tt>o.a.a.repository.servlet.<br/>RepositoryServlet</tt>
+<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>
+  |   |   |  
+
+More information on configuration authentication can be found in [ACE authentication
+guide](/docs/ace-authentication.html) and [user guide](/docs/user-guide.html).
+
+
+### Implementing the authentication check
+
+If you want to use the <tt>AuthenticationService</tt> in your own code, you first need to
+obtain a reference to this service. Using a dependency manager such as Felix
+DependencyManager makes this trivial:
+
+ :::java
+ private volatile AuthenticationService m_authService;
+
+ // ...
+
+ /**
+ * Called by Dependency Manager upon initialization of this component.
+ */
+ protected void init(Component comp) {
+ comp.add(m_dm.createServiceDependency()
+ .setService(AuthenticationService.class)
+ .setRequired(true)
+ );
+ }
+
+To implement the actual authentication in your servlet, we simple intercept all incoming
+requests in our Servlet and verify whether it is valid (for example, whether we have valid
+credentials or a valid certificate):
+
+ :::java
+ @Override
+ protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
+ if (!authenticate(req)) {
+ // Authentication failed; don't proceed with the original request...
+ m_log.log(LogService.LOG_INFO, "Authentication failure!");
+ resp.sendError(SC_UNAUTHORIZED);
+ } else {
+ // Authentication successful, proceed with original request...
+ super.service(req, resp);
+ }
+ }
+
+ private boolean authenticate(HttpServletRequest request) {
+ User user = m_authService.authenticate(request);
+ return (user != null);
+ }
+
+Note that this implementation does not tell *how* the authentication should occur, only
+that it *must* occur. How the authentication is performed, is determined internally by the
+<tt>AuthenticationService</tt>, with the help of the registered
+<tt>AuthenticationProcessor</tt>s. Also note that the <tt>authenticate</tt> method itself
+uses the previously defined field (<tt>m_useAuth</tt>) to determine whether or not the
+authentication check should be performed. If it is *not* performed, we consider the
+request to be always authenticated, in order to obtain the same semantics as we would have
+without this check.
+
+<!-- TODO: explain how to implement a custom AuthenticationProcessor -->
+
+## 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.
+
+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)!
+: Instead, you can also use [two-way SSL using client
+certificates](/docs/using-client-certificates.html), but you can add your own
+authentication processor as well.
+
+
+## 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.
+
+[^2]: Assuming that all components in the ACE server are trusted and obtained from trusted sources. If untrusted components would be allowed, we need to add authentication to these communication paths as well.
+
+[^3]: It is up to the implementation of <tt>AuthenticationService</tt> whether the *first* found user is returned, or whether it checks if all authentication processors yield the *same* user, or any other strategy that is desired.
+
+[^4]: The common prefix of the shown configuration PIDs are abbreviated, so "<tt>o.a.a</tt>" stands for "<tt>org.apache.ace</tt>".
+
+[^5]: Amongst others, any number of log-endpoints can be defined, at least one is needed for the audit log to be synchronized between target and ACE server.
+
+[^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!
Propchange: ace/site/trunk/content/docs/design/authentication-design.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/using-basic-auth.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/using-basic-auth.mdtext?rev=1641565&view=auto
==============================================================================
--- ace/site/trunk/content/docs/using-basic-auth.mdtext (added)
+++ ace/site/trunk/content/docs/using-basic-auth.mdtext Tue Nov 25 10:59:30 2014
@@ -0,0 +1,180 @@
+Title: ACE Authentication
+
+[TOC]
+
+## 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 how to configure
+authentication to your situation.
+More details on the design of the authentication mechanism in ACE can be found in the
+[design documentation](/docs/design/authentication-design.mdtext).
+
+
+## Configuring authentication
+
+By default, ACE has no form of authentication enabled. While this is sufficient for
+demonstration purposes, you might want to change this prior to putting ACE into
+production. There are three parts that need to be configured:
+
+1. the "remote services" exposed by the ACE server need to enable authentication;
+2. the internal client(s) (which covers the ACE server itself!) need to know what
+ authentication mechanism should be used. For convenience, the client(s) can make use of
+ the <tt>ConnectionFactory</tt> to create authenticated connections to the ACE server;
+3. the management agent, which also needs to know what credentials it can use to access
+ the ACE server.
+
+One of the easiest forms of authentication to use in ACE is HTTP BASIC authentication,
+which means that username/password credentials are sent with each request to the server.
+Note that this is done in clear text, so you might want to add an additional layer of
+security by using TLS/SSL encryption as well.
+
+### Remote services
+
+There are several endpoints exposed by the ACE server as listed in the following table,
+along with the endpoint(s) they expose:
+
+Name | Description | Endpoint | Configuration PID[^1]
+------- | --------------- | ------------ | ---------------------
+<tt>BundleServlet</tt> | provides access to the OBR (bundle repository) of ACE | <tt>/obr</tt> | <tt>o.a.a.obr.servlet</tt>
+<tt>DeploymentServlet</tt> | handles the actual provisioning of deployment packages to a target | <tt>/deployment</tt> |<tt>o.a.a.deployment.servlet</tt>
+<tt>LogServlet</tt> | allows any number of logs for a target to be synchronized and accessed | <tt>/auditlog</tt>[^2] | <tt>o.a.a.server.log.servlet.factory</tt><br/>**note: this is a configuration factory!**
+<tt>RepositoryServlet</tt> | provides access to the various (artifact/feature/distribution/target) internal repositories of ACE | <tt>/repository</tt> | <tt>o.a.a.repository.servlet.<br/>RepositoryServlet</tt>
+<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>
+  |   |   |  
+
+To configure authentication, for example, for the OBR servlet, you need to edit
+<tt>conf/org.apache.ace.obr.servlet.cfg</tt> to edit/include the following:
+
+ :::properties
+ # Endpoint for this servlet
+ org.apache.ace.server.servlet.endpoint = /obr
+ # Whether or not authentication is to be used
+ authentication.enabled = true
+
+Note that the <tt>authentication.enabled</tt> property allows us to enable or disable the
+authentication check for this servlet.
+This is the *only* thing that is needed to enable authentication for remote services.
+What authentication mechanism is to be used is up to the caller/client: it should provide
+the right credentials in order to pass the authentication check, see also the [design
+documentation](/docs/design/authentication-design.html).
+
+### The connection factory
+
+Now that the remote services no longer accepting unauthenticated requests, we need to
+configure the client(s) in order to make use of authentication as well. Note that due to
+the modular architecture of the ACE server, the server itself is also regarded a client
+meaning that it needs to be configured to use authentication as well! For convenience, the
+client(s) can use the <tt>ConnectionFactory</tt> supplied by ACE for creating a connection
+with the proper authentication credentials already configured. This also simplies the
+configuration at the client side significantly, as we only need to configure a single
+service.
+
+The <tt>ConnectionFactory</tt> service can be configured using the PID
+<tt>org.apache.ace.connectionfactory</tt> (**note** that it is a configuration factory,
+accepting multiple configurations!). To configure the authentication credentials for the
+OBR servlet, you need to edit or create a file named <tt>obr.cfg</tt> and place it in the
+<tt>org.apache.ace.connectionfactory</tt> directory. For HTTP BASIC authentication, the
+following key/values need to be present:
+
+ :::properties
+ # What kind of authentication should we supply
+ authentication.type = basic
+ # The actual credentials for basic authentication
+ authentication.user.name = d
+ authentication.user.password = f
+ # 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>"[^3]. To disable authentication for a particular URL,
+the <tt>authentication.type</tt> option can be set to <tt>none</tt>.
+
+### The management agent
+
+The management agent itself also needs to use authentication to communicate with the
+remote services of the ACE server. Although it would be possible to reuse the same
+<tt>ConnectionFactory</tt> implementation as the server, the current implementation uses a
+different approach to minimize the number of dependencies. To configure authentication for
+the management agent, you need to supply one or more system properties[^4]:
+
+ :::sh
+ [localhost:~/]$ java -Dagent.connection.authtype=BASIC \
+ -Dagent.connection.username=d -Dagent.connection.password=f \
+ -Dagent.identification.agentid=target-1 \
+ target.jar
+
+
+### 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[^5], or add them, for example, [by
+hand](/docs/user-management-guide.html). Alternatively, you can also use another backend
+for the used UserAdmin service, that connects to a LDAP server.
+
+
+## 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.
+
+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)!
+: Instead, you can also use [two-way SSL using client
+certificates](/docs/using-client-certificates.html), but you can add your own
+authentication processor as well. See the [design
+documentation](/docs/design/authentication-design.html) for more details.
+
+
+## Notes
+
+[^1]: The common prefix of the shown configuration PIDs are abbreviated, so
+"<tt>o.a.a</tt>" stands for "<tt>org.apache.ace</tt>".
+
+[^2]: Amongst others, any number of log-endpoints can be defined, at least one is needed
+for the audit log to be synchronized between target and ACE server.
+
+[^3]: 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.
+
+[^4]: You probably do not want to specify the credentials using the commandline, see also
+[ACE-496](https://issues.apache.org/jira/browse/ACE-496).
+
+[^5]: Make sure to clean the <tt>bundle-cache</tt> directory before restarting the server,
+otherwise the new configuration files will not be picked up!
+
Propchange: ace/site/trunk/content/docs/using-basic-auth.mdtext
------------------------------------------------------------------------------
svn:eol-style = native