svn commit: r1009864 - in /websites/staging/sling/trunk/content: ./ documentation/the-sling-engine/service-authentication.html

[bu...@apache.org]

Author: buildbot
Date: Wed Apr  5 14:51:07 2017
New Revision: 1009864

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/the-sling-engine/service-authentication.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Apr  5 14:51:07 2017
@@ -1 +1 @@
-1790270
+1790285

Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/service-authentication.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/service-authentication.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/service-authentication.html Wed Apr  5 14:51:07 2017
@@ -132,7 +132,10 @@ h2:hover > .headerlink, h3:hover > .head
 <li><a href="#service-user-mappings">Service User Mappings</a></li>
 </ul>
 </li>
-<li><a href="#deprecation-of-administrative-authentication">Deprecation of administrative authentication</a></li>
+<li><a href="#deprecation-of-administrative-authentication">Deprecation of administrative authentication</a><ul>
+<li><a href="#whitelisting-bundles-for-administrative-login">Whitelisting bundles for administrative login</a></li>
+</ul>
+</li>
 </ul>
 </div>
 <h2 id="problem">Problem<a class="headerlink" href="#problem" title="Permanent link">&para;</a></h2>
@@ -281,8 +284,94 @@ in the near future. But there will be a
 support for these methods: If the method is disabled, a <code>LoginException</code>
 is always thrown from these methods. The JavaDoc of the methods is
 extended with this information.</p>
+<h3 id="whitelisting-bundles-for-administrative-login">Whitelisting bundles for administrative login<a class="headerlink" href="#whitelisting-bundles-for-administrative-login" title="Permanent link">&para;</a></h3>
+<p>In order to be able to manage few (hopefully legit) uses of the above deprecated
+methods, a whitelisting mechanism was introduced.</p>
+<p>The recommended way to whitelist a bundle for administrative login is via a
+<em>whitelist fragment configuration</em> is recommended. It can be created as an OSGi factory
+configuration with the factoryPID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment</code>.
+E.g. a typical configuration file might be called
+<code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config</code>
+and could look as follows: </p>
+<div class="codehilite"><pre><span class="n">whitelist</span><span class="p">.</span><span class="n">name</span><span class="p">=</span>&quot;<span class="n">myapp</span>&quot;
+<span class="n">whitelist</span><span class="p">.</span><span class="n">bundles</span><span class="p">=[</span>
+    &quot;<span class="n">com</span><span class="p">.</span><span class="n">myapp</span><span class="p">.</span><span class="n">core</span>&quot;<span class="p">,</span>
+    &quot;<span class="n">com</span><span class="p">.</span><span class="n">myapp</span><span class="p">.</span><span class="n">commons</span>&quot;
+<span class="p">]</span>
+</pre></div>
+
+
+<table class="table">
+<thead>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>whitelist.name</code></td>
+<td>String</td>
+<td>"[unnamed]"</td>
+<td>Purely informational property that allows easy identification of different fragments.</td>
+</tr>
+<tr>
+<td><code>whitelist.bundles</code></td>
+<td>String[]</td>
+<td>[]</td>
+<td>An array of bundle symbolic names that should be allowed to make use of the administrative login functionality.</td>
+</tr>
+</tbody>
+</table>
+<p>All configured whitelist fragments are taken into account. This makes
+it easy to separate whitelists for different application layers and
+purposes.</p>
+<p>For example, some Sling bundles need to be whitelisted, which
+could be done in a whitelist fragment named <code>sling</code>. In addition <code>myapp</code>
+adds a whitelist fragment called <code>myapp</code>. For integration tests and
+additional whitelist fragment <code>myapp-integration-testing</code> may be added.</p>
+<p>Furthermore, there is a global configuration, which should
+only be used in exceptional cases. It has a switch to turn administrative
+login on globally (<code>whitelist.bypass</code>) and it allows supplying a regular
+expression to whitelist matching bundle symbolic names (<code>whitelist.bundles.regexp</code>).</p>
+<p>The regular expression is most useful for running PaxExam based tests, where
+bundle symbolic names follow a set pattern but have randomly generated parts.</p>
+<p>Example: to whitelist all bundles generated by PaxExam a configuration file named <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.config</code> might look as follows:</p>
+<div class="codehilite"><pre><span class="n">whitelist</span><span class="p">.</span><span class="n">bypass</span><span class="p">=</span><span class="n">B</span>&quot;<span class="n">false</span>&quot;
+<span class="n">whitelist</span><span class="p">.</span><span class="n">bundles</span><span class="p">.</span><span class="n">regexp</span><span class="p">=</span>&quot;^<span class="n">PAXEXAM</span><span class="o">.*</span>$&quot;
+</pre></div>
+
+
+<p>The configuration PID is PID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist</code>.
+It supports the following configuration properties.</p>
+<table class="table">
+<thead>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>whitelist.bypass</code></td>
+<td>Boolean</td>
+<td>false</td>
+<td>Allow all bundles to use administrative login. This is <strong>NOT</strong> recommended for production and warnings will be logged.</td>
+</tr>
+<tr>
+<td><code>whitelist.bundles.regexp</code></td>
+<td>String</td>
+<td>""</td>
+<td>A regular expression that whitelists all matching bundle symbolic names. This is <strong>NOT</strong> recommended for production and warnings will be logged.</td>
+</tr>
+</tbody>
+</table>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1784705 by kwin on Tue, 28 Feb 2017 09:28:03 +0000
+        Rev. 1790285 by jsedding on Wed, 5 Apr 2017 14:50:52 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project