This is an automated email from the ASF dual-hosted git repository.
bdelacretaz pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-capabilities.git
The following commit(s) were added to refs/heads/master by this push:
new 2f20578 README
2f20578 is described below
commit 2f20578b54dea42f9934775630d9a577c5460912
Author: Bertrand Delacretaz <[email protected]>
AuthorDate: Mon Oct 15 17:03:36 2018 +0200
README
---
README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 85 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index 512f115..75ef9fd 100644
--- a/README.md
+++ b/README.md
@@ -5,20 +5,19 @@ The servlet provided by this module allows for creating
Capabilities HTTP endpoi
on a Sling instance: Resources that provide information on which services are
available,
version levels etc.
-For now, a single type of endpoint is provided: all Resources which have the
-`sling/capabilities` resource type will return the same set of Capabilities,
generated
-by aggregating the output of all active `CapabilitiesSource` services.
+To avoid exposing more information than strictly needed, this module provides
two mechanisms,
+described below, to control where resources that expose capabilities can be
found in the Sling
+resource tree, as well as which `CapabilitiesSource` services are considered
by those resources.
-This can be easily expanded to multiple sets of Capabilities if needed later
on,
-by changing the code to use service properties to group or tag the
`CapabilitiesSource` services.
-
-These capabilities are _not_ the same as OSGi capabilities: they can be
application-related, indicate
-the availability of external services, etc.
+The example configuration below shows the JSON vocabulary used to expose
capabilities.
CapabilitiesSource services
----------------------------
-The tests provide simple `CapabilitiesSource` examples, that API is as follows:
+Services that implement the `CapabilitiesSource` interface provide
capabilities.
+
+Each service must have its own unique namespace, used to split the
capabilities in
+categories that can be provided separately (see below):
@ProviderType
public interface CapabilitiesSource {
@@ -34,24 +33,88 @@ The tests provide simple `CapabilitiesSource` examples,
that API is as follows:
*/
Map<String, Object> getCapabilities() throws Exception;
}
+
+The sling/capabilities resource type
+------------------------------------
+
+To act as an endpoint for capabilities a resource must have the
`sling/capabilities`
+resource type.
+
+A required property named `namespace_patterns` must be present, containing
1..N Java
+regexp patterns to select which capabilities namespaces are exposed by this
resource.
+
+Write access to such resources should be strictly controlled to avoid leaking
unwanted
+information, along with the CapabilitiesServlet path restrictions described
below.
+
+CapabilitiesServlet configuration
+---------------------------------
+To restrict access to capabilities, the `CapabilitiesServlet` requires a
configuration
+(see example below) that specifies which paths patterns are acceptable for
`sling/capabilities`
+resources.
+
+The idea is to strictly control write access to these paths, so that even if
users can create
+`sling/capabilities` resources elsewhere they will not expose capabilities
data.
-CapabilitiesServlet output
---------------------------
+If the path of a `sling/capabilities` resource does not match any of the
configured patterns,
+the servlet returns a 403 status code saying `Invalid path`.
-The `CapabilitiesServlet` produces output as in the example below, where two
-`CapabilitiesSource` services are available:
+Example configuration
+---------------------
+This module does not provide any active `CapabilitiesSource` out of the box,
but it provides a
+`SlingServletsSource` that can be used to exposes which Sling servlets are
active, including their
+`sling.servlet.*` properties for reference.
+
+With the example configuration below a `sling/capabilities` resource with
+`namespace_patterns='servlets\.[A|B]'` and a path that matches
`/var/capabilities/.*`
+produces the following output:
- $ curl -s -u admin:admin http://localhost:8080/tmp/cap.json | jq .
{
"org.apache.sling.capabilities": {
- "org.apache.sling.capabilities.osgi": {
- "framework.bundle.symbolic.name": "org.apache.felix.framework",
- "framework.bundle.version": "5.6.10"
- },
- "org.apache.sling.capabilities.jvm": {
- "java.specification.version": "1.8",
- "java.vm.version": "25.171-b11",
- "java.vm.vendor": "Oracle Corporation"
+ "data": {
+ "servlets.A": {
+ "GetAclServlet_23102540": {
+ "sling.servlet.extensions": "json",
+ "sling.servlet.selectors": [
+ "acl",
+ "tidy.acl"
+ ],
+ "sling.servlet.resourceTypes": "sling/servlet/default",
+ "sling.servlet.methods": "GET"
+ }
+ },
+ "servlets.B": {
+ "ChangeUserPasswordServlet_2134633768": {
+ "sling.servlet.selectors": "changePassword",
+ "sling.servlet.resourceTypes": "sling/user",
+ "sling.servlet.methods": "POST"
+ }
+ }
}
}
}
+
+The configured `servlets.C` namespace is omitted due to the
`namespace_patterns` property.
+
+Here's the required configuration, excerpted from
`/system/console/status-Configurations`:
+
+ PID = org.apache.sling.capabilities.internal.CapabilitiesServlet
+ resourcePathPatterns = [/var/capabilities/.*]
+
+ Factory PID =
org.apache.sling.capabilities.defaultsources.SlingServletsSource
+ capabilitiesNamespace = servlets.A
+ servletsLdapFilter =
(&(sling.servlet.extensions=json)(sling.servlet.selectors=acl))
+
+ Factory PID =
org.apache.sling.capabilities.defaultsources.SlingServletsSource
+ capabilitiesNamespace = servlets.B
+ servletsLdapFilter =
(&(sling.servlet.resourceTypes=sling/user)(sling.servlet.selectors=changePassword))
+
+ Factory PID =
org.apache.sling.capabilities.defaultsources.SlingServletsSource
+ capabilitiesNamespace = servlets.C
+ servletsLdapFilter = (sling.servlet.extensions=html)
+
+And a resource that then generates the above output can be created with
+
+ curl -u admin:admin \
+ -Fsling:resourceType=sling/capabilities \
+ -Fnamespace_patterns='servlets\.[A|B]' \
+ http://localhost:8080/var/capabilities/caps
\ No newline at end of file
