This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 6fd26c6a6 Update documentation based on JCR Base 3.2.0 release
6fd26c6a6 is described below
commit 6fd26c6a6688015430c7993301c72b60841aa129
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Oct 9 07:38:14 2025 +0200
Update documentation based on JCR Base 3.2.0 release
---
.../the-sling-engine/service-authentication.md | 63 +++++++++++++---------
1 file changed, 38 insertions(+), 25 deletions(-)
diff --git
a/src/main/jbake/content/documentation/the-sling-engine/service-authentication.md
b/src/main/jbake/content/documentation/the-sling-engine/service-authentication.md
old mode 100644
new mode 100755
index 8c1476922..30d8b559f
---
a/src/main/jbake/content/documentation/the-sling-engine/service-authentication.md
+++
b/src/main/jbake/content/documentation/the-sling-engine/service-authentication.md
@@ -251,55 +251,68 @@ support for these methods: If the method is disabled, a
`LoginException`
is always thrown from these methods. The JavaDoc of the methods is
extended with this information.
-### Whitelisting bundles for administrative login
+### Allowlisting 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 with
[SLING-5153](https://issues.apache.org/jira/browse/SLING-5135) (*JCR Base
2.4.2*).
+methods, a allow list mechanism was introduced with
[SLING-5153](https://issues.apache.org/jira/browse/SLING-5135) (*JCR Base
2.4.2*) and further improved with
[11741](https://issues.apache.org/jira/browse/SLING-11741) (*JCR Base 3.2.0*).
-The recommended way to whitelist a bundle for administrative login is via a
-_whitelist fragment configuration_. It can be created as an OSGi factory
-configuration with the factoryPID
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment`.
+The recommended way to allowlist a bundle for administrative login is via a
+_allowlist fragment configuration_. It can be created as an OSGi factory
+configuration with the factoryPID
`org.apache.sling.jcr.base.LoginAdminAllowList.fragment`.
E.g. a typical configuration file might be called
-`org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config`
+`org.apache.sling.jcr.base.LoginAdminAllowList.fragment-myapp.config`
and could look as follows:
- whitelist.name="myapp"
- whitelist.bundles=[
+ allowlist.name="myapp"
+ allowlist.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. |
+| `allowlist.name` | String | `[unnamed]` | Purely informational property
that allows easy identification of different fragments. |
+| `allowlist.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
+All configured allowlist fragments are taken into account. This makes
+it easy to separate allowlists 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.
+For example, some Sling bundles need to be allowlisted, which
+could be done in a allowlist fragment named `sling`. In addition `myapp`
+adds a allowlist fragment called `myapp`. For integration tests and
+additional allowlist fragment `myapp-integration-testing` may be added.
-Furthermore, there is a global configuration with PID
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist`, which should
+Furthermore, there is a global configuration with PID
`org.apache.sling.jcr.base.LoginAdminAllowList`, 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`).
+login on globally (`allowlist.bypass`) and it allows supplying a regular
+expression to allowlist matching bundle symbolic names
(`allowlist.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:
+Example: to allowlist all bundles generated by PaxExam a configuration file
named `org.apache.sling.jcr.base.LoginAdminAllowList.config` might look as
follows:
- whitelist.bypass=B"false"
- whitelist.bundles.regexp="^PAXEXAM.*$"
+ allowlist.bypass=B"false"
+ allowlist.bundles.regexp="^PAXEXAM.*$"
-The configuration PID is
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist`.
+The configuration PID is `org.apache.sling.jcr.base.LoginAdminAllowList`.
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. |
+| `allowlist.bypass` | Boolean | false | Allow all bundles to
use administrative login. This is __NOT__ recommended for production and
warnings will be logged. |
+| `allowlist.bundles.regexp` | String | "" | A regular expression
that allowlists all matching bundle symbolic names. This is __NOT__ recommended
for production and warnings will be logged. |
+
+
+### Deprecated Approach to allowlist bundles for administrative login
+
+The mechanism introduced with *JCR Base 2.4.2* has been updated with *JCR Base
3.2.0* to use more inclusive language. It is recommended to use the above
mentioned configurations if needed.
+
+The older configurations are still partially supported, but should be upgraded
to use the new naming.
+
+The deprecated configurations supported are the factoryPID
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment` with the
configuration properties `whitelist.name` and `whitelist.bundles` for the
fragments. The deprecated configuration for the global settings is
`org.apache.sling.jcr.base.internal.LoginAdminWhitelist` with the properties
`whitelist.bypass` and `whitelist.bundles.regexp`.
+
+The deprecated fragments are still fully supported as they get merged with
fragments using the official way of configuring them. Still it is advised to
change to the new names.
+
+However, the global configuration will only be used if there is no new global
configuration available. Make sure that you do not have both! But as mentioned
the global configuration should only be used for cases like testing anyway.
Fragments is the better option.
