Author: jsedding
Date: Wed Apr 5 14:50:52 2017
New Revision: 1790285
URL: http://svn.apache.org/viewvc?rev=1790285&view=rev
Log:
SLING-6273 - Document SLING-5135 - whitelist of legit login admin uses
Modified:
sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext
Modified:
sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext?rev=1790285&r1=1790284&r2=1790285&view=diff
==============================================================================
---
sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext
(original)
+++
sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext
Wed Apr 5 14:50:52 2017
@@ -182,3 +182,55 @@ support for these methods: If the method
is always thrown from these methods. The JavaDoc of the methods is
extended with this information.
+### Whitelisting bundles for administrative login
+
+In order to be able to manage few (hopefully legit) uses of the above
deprecated
+methods, a whitelisting mechanism was introduced.
+
+The recommended way to whitelist a bundle for administrative login is via a
+_whitelist fragment configuration_ is recommended. It can be created as an
OSGi factory
+configuration with the factoryPID
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment`.
+E.g. a typical configuration file might be called
+`org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config`
+and could look as follows:
+
+ whitelist.name="myapp"
+ whitelist.bundles=[
+ "com.myapp.core",
+ "com.myapp.commons"
+ ]
+
+| Property | Type | Default | Description |
+|---------------------|----------|-------------|-------------|
+| `whitelist.name` | String | "[unnamed]" | Purely informational property
that allows easy identification of different fragments. |
+| `whitelist.bundles` | String[] | [] | An array of bundle symbolic
names that should be allowed to make use of the administrative login
functionality. |
+
+All configured whitelist fragments are taken into account. This makes
+it easy to separate whitelists for different application layers and
+purposes.
+
+For example, some Sling bundles need to be whitelisted, which
+could be done in a whitelist fragment named `sling`. In addition `myapp`
+adds a whitelist fragment called `myapp`. For integration tests and
+additional whitelist fragment `myapp-integration-testing` may be added.
+
+Furthermore, there is a global configuration, which should
+only be used in exceptional cases. It has a switch to turn administrative
+login on globally (`whitelist.bypass`) and it allows supplying a regular
+expression to whitelist matching bundle symbolic names
(`whitelist.bundles.regexp`).
+
+The regular expression is most useful for running PaxExam based tests, where
+bundle symbolic names follow a set pattern but have randomly generated parts.
+
+Example: to whitelist all bundles generated by PaxExam a configuration file
named `org.apache.sling.jcr.base.internal.LoginAdminWhitelist.config` might
look as follows:
+
+ whitelist.bypass=B"false"
+ whitelist.bundles.regexp="^PAXEXAM.*$"
+
+The configuration PID is PID
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist`.
+It supports the following configuration properties.
+
+| Property | Type | Default | Description |
+|----------------------------|----------|-------------|-------------|
+| `whitelist.bypass` | Boolean | false | Allow all bundles to
use administrative login. This is __NOT__ recommended for production and
warnings will be logged. |
+| `whitelist.bundles.regexp` | String | "" | A regular expression
that whitelists all matching bundle symbolic names. This is __NOT__ recommended
for production and warnings will be logged. |
