[sling-site] branch master updated: SLING-8171 document principal-based mappings

[kw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kwin 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 4db71dd  SLING-8171 document principal-based mappings
4db71dd is described below

commit 4db71dd9b92d7c56aaebddee26202974dc4e86d5
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Wed Dec 12 10:07:41 2018 +0100

    SLING-8171 document principal-based mappings
---
 .../the-sling-engine/service-authentication.md             | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 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
index 1247f3f..e1b0eba 100644
--- a/src/main/jbake/content/documentation/the-sling-engine/service-authentication.md
+++ b/src/main/jbake/content/documentation/the-sling-engine/service-authentication.md
@@ -100,7 +100,7 @@ described above consists of three parts:
 The first part is a new OSGi Service `ServiceUserMapper`. The
 `ServiceUserMapper` service allows for mapping *Service IDs* comprised of
 the *Service Names* defined by the providing bundles and optional *Subservice Name*
-to ResourceResolver and/or JCR Repository user IDs. This mapping is configurable
+to ResourceResolver and/or JCR Repository user IDs or principals ([SLING-6939](https://issues.apache.org/jira/browse/SLING-6963)). This mapping is configurable
 such that system administrators are in full control of assigning users to services.
 
 The `ServiceUserMapper` defines the following API:
@@ -110,12 +110,12 @@ The `ServiceUserMapper` defines the following API:
     
 The implementation uses two fallbacks in case no mapping can be found for the given subServiceName
 
-1. Use user mapping for the serviceName only (not considering subServiceName)
+1. Use user/principal mapping for the serviceName only (not considering subServiceName)
 1. Use default user (if one is configured in the OSGi configuration for PID `	org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl`).
 1. Use default mapping (if it is enabled in the OSGi configuration for PID `	org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl`) which looks up a user with id `serviceuser--<bundleId>[--<subservice-name>]` (since Service User Mapper 1.3.0, [SLING-6227](https://issues.apache.org/jira/browse/SLING-6772)).
 
 In addition a service named `ServiceUserMapped` is registered for each bundle and subservice name for which a service user mapping is explicitly configured ([SLING-4312](https://issues.apache.org/jira/browse/SLING-4312)).  By explicitly defining a (static) reference towards `ServiceUserMapped` one can defer starting the service until that service user mapping is available.
-Please note, that the two last default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work.
+Please note, that the two last default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work prior to version 1.4.4 ([SLING-7930](https://issues.apache.org/jira/browse/SLING-7930)). Also since version 1.4.4 the `ServiceUserMapped` is only registered in case there is a valid user/principal found in the underlying repository which is given in the mapping ([SLING-7930](https://issues.apache.org/jira/browse/SLING-7930)).
 
 ### `ResourceResolverFactory`
 
@@ -158,12 +158,14 @@ service. The additional Subservice Name may be provided with the
 
 ### Service User Mappings
 
-For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user.
+For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user or a principal (since version 1.3.4, see [SLING-6939](https://issues.apache.org/jira/browse/SLING-6963)).
 This is configured through an OSGi configuration for the factory configuration with PID `org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended` (added in [SLING-3578](https://issues.apache.org/jira/browse/SLING-3578)). There you can set one configuration property named `user.mapping` getting a String array as value where each entry must stick to the following format:
 
-    <service-name>[:<subservice-name>]=<authorizable id of a JCR system user>
+    <service-name>[:<subservice-name>]=<authorizable id of a JCR system user>|"["<principal name>{","<principal name>}"]"
+    
+The principal based mapping (enclosed in square brackets) is in general faster than the authorizable id based one. Also it allows to directly reference multiple principals which are all considered to calculate the access rights for the configured service session/resource resolver. The principal based mapping does not consider group memberships of the underlying users, though.
 
-The according user must exist at the point in time where `ResourceResolverFactory.getServiceResourceResolver(...)` or `SlingRepository.loginService(...)` is called. If you rely on one of those methods in your `activate` method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service `ServiceUserMapped` (see Section `ServiceUserMapper` above), optionally with a ta [...]
+The according user/principal must exist at the point in time where `ResourceResolverFactory.getServiceResourceResolver(...)` or `SlingRepository.loginService(...)` is called. If you rely on one of those methods in your `activate` method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service `ServiceUserMapped` (see Section `ServiceUserMapper` above for details) [...]
 
 Example OSGi DS Component