README
authorBertrand Delacretaz <bdelacretaz@apache.org>
Mon, 15 Oct 2018 15:03:36 +0000 (17:03 +0200)
committerBertrand Delacretaz <bdelacretaz@apache.org>
Mon, 15 Oct 2018 15:03:36 +0000 (17:03 +0200)
README.md

index 512f115..75ef9fd 100644 (file)
--- 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