Mailing-List: contact commits-help@sling.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@sling.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1510382 - in /sling/site/trunk/content/documentation:
 the-sling-engine.mdtext the-sling-engine/service-authentication.mdtext
Date: Mon, 05 Aug 2013 08:30:02 -0000
To: commits@sling.apache.org
From: fmeschbe@apache.org
Message-Id: <20130805083002.EC4EF2388900@eris.apache.org>

Author: fmeschbe
Date: Mon Aug  5 08:30:02 2013
New Revision: 1510382

URL: http://svn.apache.org/r1510382
Log:
SLING-2944 Some documentation on Service User Mapping

Added:
    sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext
Modified:
    sling/site/trunk/content/documentation/the-sling-engine.mdtext

Modified: sling/site/trunk/content/documentation/the-sling-engine.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine.mdtext?rev=1510382&r1=1510381&r2=1510382&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine.mdtext Mon Aug  5 08:30:02 2013
@@ -1,8 +1,10 @@
 Title: The Sling Engine
 
 ## General
+
 * [Architecture]({{ refs.architecture.path }})
 * [Authentication]({{ refs.authentication.path }})
+* [{{ refs.service-authentication.headers.title }}]({{ refs.service-authentication.path }})
 
 ## Request Handling
 

Added: 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=1510382&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext (added)
+++ sling/site/trunk/content/documentation/the-sling-engine/service-authentication.mdtext Mon Aug  5 08:30:02 2013
@@ -0,0 +1,176 @@
+Title: Service Authentication
+Excerpt: Introduce new service level authentication to replace `loginAdministrative`
+
+[TOC]
+
+## Problem
+
+To access the data storage in the Resource Tree and/or the JCR Repository
+authentication is required to properly setup access control and guard
+sensitive data from unauthorized access. For regular request processing
+this authentication step is handled by the Sling
+[{{ refs.authentication.headers.title }}]({{ refs.authentication.path }})
+subsystem.
+
+On the other hand there are also some background tasks to be executed
+with access to the resources. Such tasks cannot in general be configured
+with user names and passwords: Neither hard coding the passwords in the code
+nor having the passwords in &ndash; more or less &ndash; plain text in some
+configuration is considered good practice.
+
+To solve this problem for services to identify themselves and authenticate
+with special users properly configured to support those services.
+
+The solution presented here serves the following goals:
+
+* Prevent over-use and abuse of administrative ResourceResolvers and/ro JCR Sessions
+* Allow services access to ResourceResolvers and/or JCR Sessions without
+requiring to hard-code or configure passwords
+* Allow services to use *service users* which have been specially
+configured for service level access (as is usually done on unixish systems)
+* Allow administrators to configure the assignment of service users to
+services
+
+
+## Concept
+
+A *Service* is a piece or collection of functionality. Examples of services
+are the Sling queuing system, Tenant Administration, or some Message Transfer
+System. Each service is identified by a unique *Service Name*. Since a
+service will  be implemented in an OSGi bundle (or a collection of OSGi
+bundles), services are named by the bundles providing them.
+
+A Service may be comprised of multiple parts, so each part of the
+service may be further identified by a *Subservice Name*. This
+Subservice Name is optional, though. Examples of *Subservice Name*
+are names for subsystems in a Message Transfer System such as accepting
+messages, queueing messages, delivering messages.
+
+Ultimately, the combination of the *Service Name* and *Subservice Name*
+defines the *Service ID*. It is the *Service ID* which is finally mapped to
+a Resource Resolver and/or JCR Repository user ID for authentication.
+
+Thus the actual service identification (service ID) is defined as:
+
+    #!text
+    service-id = service-name [ ":" subservice-name ] .
+
+The `service-name` is the value of the `Sling-Service` bundle manifest
+header. This name can be any string valid as a manifest header but must
+not contain a colon `:` which is used to delimit the `service-name` from
+the `service-info` in the `service-id` string.
+
+If the bundle does not have a `Sling-Service` bundle manifest header or
+if the value is the empty string, the bundle's symbolic name is used as
+the `service-name`.
+
+
+### Example: Tenant Administration
+
+Tenant Administration mostly deals with creating and managing groups
+and some other user administration tasks. Instead of just using an
+administrative session for Tenant administration this feature could
+define itself as being the `tenant-admin` service and leverage a
+properly configured Tenant Administration account.
+
+### Example: Mail Transfer System
+
+Consider a Mail Transfer System which may be comprised of the following
+sub systems:
+
+* Accepting mail for processing &mdash; for example the SMTP server daemon
+* Queing and processing the messages
+* Delivering messages to mailboxes
+
+You could conceive that all these functions serve different purposes and
+thus should have different access rights to the repository to persist
+messages while they are being processed.
+
+Using the Service Authentication framework, the Mail Transfer System
+would be consituting the `mta` service. The sub systems would be called
+`smtp`, `queue`, and `deliver`.
+
+Thus the SMTP server daemon would be represented by a user for the
+`mta:smtp` Service.  queueing with `mta:queue`, and delivery with `mta:deliver`.  
+
+
+## Implementation
+
+The implementation in Sling of the *Service Authentication* concept
+described above consists of three parts:
+
+### `ServiceUserMapper`
+
+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
+such that system administrators are in full control of assigning users to services.
+
+The `ServiceUserMapper` defines the following API:
+
+    #!java
+    String getServiceID(Bundle bundle, String subServiceName);
+    String getServiceUserID(Bundle bundle, String subServiceName);
+    
+
+### `ResourceResolverFactory`
+
+The second part is support for service access to the Resource Tree. To this
+avail, the `ResourceResolverFactory` service is enhanced with a new factory
+method
+
+    #!java
+    ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo)
+        throws LoginException;
+    
+This method allows for access to the resource tree for services where the
+service bundle is the bundle actually using the `ResourceResolverFactory`
+service. The optional Subservice Name may be provided as an entry
+in the `authenticationInfo` map.
+
+In addition to having new API on the `ResourceResolverFactory` service to
+be used by services, the `ResourceProviderFactory` service is updated
+with support for Service Authentication: Now new API is required, though
+but additional properties are defined to convey the service to authenticate
+for.
+
+
+### `SlingRepository`
+
+The third part is an extension to the `SlingRepository`service interface
+to support JCR Repository access for services:
+
+    #!java
+    Session loginService(String subServiceName, String workspace)
+        throws LoginException, RepositoryException;
+
+This method allows for access to the JCR Repository for services where the
+service bundle is the bundle actually using the `SlingRepository`
+service. The additional Subservice Name may be provided with the
+`subServiceName` parameter.
+
+
+
+## Deprecation of administrative authentication
+
+Originally the `ResourceResolverFactory.getAdministrativeResourceResolver`
+and `SlingRepository.loginAdministrative` methods have been defined to
+provide access to the resource tree and JCR Repository. These methods
+proved to be inappropriate because they allow for much too broad access.
+
+Consequently these methods are being deprecated and will be removed in
+future releases of the service implementations.
+
+The following methods are deprecated:
+
+* `ResourceResolverFactory.getAdministrativeResourceResolver`
+* `ResourceProviderFactory.getAdministrativeResourceProvider`
+* `SlingRepository.loginAdministrative`
+
+The implementations we have in Sling's bundle will remain implemented 
+in the near future. But there will be a configuration switch to disable
+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.
+