This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new f96eadb Automatic website deployment from
https://ci-builds.apache.org/job/Sling/job/modules/job/sling-site/job/master/150/
f96eadb is described below
commit f96eadb8be41ae343c6adbef793c345627d30137
Author: jenkins <[email protected]>
AuthorDate: Thu Apr 22 07:47:02 2021 +0000
Automatic website deployment from
https://ci-builds.apache.org/job/Sling/job/modules/job/sling-site/job/master/150/
---
.../the-sling-engine/service-authentication.html | 36 ++++++++++++++++------
1 file changed, 26 insertions(+), 10 deletions(-)
diff --git a/documentation/the-sling-engine/service-authentication.html
b/documentation/the-sling-engine/service-authentication.html
index 61be360..6228b22 100644
--- a/documentation/the-sling-engine/service-authentication.html
+++ b/documentation/the-sling-engine/service-authentication.html
@@ -124,7 +124,7 @@
<p>To solve this problem for services to identify themselves and authenticate
with special users properly configured to support those services.</p>
<p>The solution presented here serves the following goals:</p>
<ul>
-<li>Prevent over-use and abuse of administrative ResourceResolvers and/ro JCR
Sessions</li>
+<li>Prevent over-use and abuse of administrative ResourceResolvers and/or JCR
Sessions</li>
<li>Allow services access to ResourceResolvers and/or JCR Sessions without
requiring to hard-code or configure passwords</li>
<li>Allow services to use <em>service users</em> which have been specially
configured for service level access (as is usually done on unixish systems)</li>
<li>Allow administrators to configure the assignment of service users to
services</li>
@@ -152,17 +152,30 @@
<h2><a href="#implementation" id="implementation">Implementation</a></h2>
<p>The implementation in Sling of the <em>Service Authentication</em> concept
described above consists of three parts:</p>
<h3><a href="#serviceusermapper"
id="serviceusermapper"><code>ServiceUserMapper</code></a></h3>
-<p>The first part is a new OSGi Service <code>ServiceUserMapper</code>. The
<code>ServiceUserMapper</code> service allows for mapping <em>Service IDs</em>
comprised of the <em>Service Names</em> defined by the providing bundles and
optional <em>Subservice Name</em> to ResourceResolver and/or JCR Repository
user IDs or principals (<a
href="https://issues.apache.org/jira/browse/SLING-6963";>SLING-6939</a>). This
mapping is configurable such that system administrators are in full control of
[...]
+<p>The first part is a new OSGi Service <code>ServiceUserMapper</code>. The
<code>ServiceUserMapper</code> service allows for mapping <em>Service IDs</em>
comprised of the <em>Service Names</em> defined by the providing bundles and
optional <em>Subservice Name</em> to ResourceResolver and/or JCR Repository
principal names (<a
href="https://issues.apache.org/jira/browse/SLING-6963";>SLING-6963</a>) or user
IDs (<a
href="https://issues.apache.org/jira/browse/SLING-10321";>SLING-10321</a>). T
[...]
<p>The <code>ServiceUserMapper</code> defines the following API:</p>
-<pre><code><!-- TODO syntax marker (#!java) disabled -->String
getServiceUserID(Bundle bundle, String subServiceName);
+<pre><code><!-- TODO syntax marker (#!java) disabled -->Iterable<String>
getServicePrincipalNames(Bundle bundle, String subServiceName);
</code></pre>
-<p>The implementation uses two fallbacks in case no mapping can be found for
the given subServiceName</p>
+<p>The alternative API (getting service user ID as shown below) has been
deprecated for security reasons and will be removed in future releases. See <a
href="https://issues.apache.org/jira/browse/SLING-10321";>SLING-10321</a> for
details.</p>
+<pre><code><!-- TODO syntax marker (#!java) disabled -->@Deprecated
+String getServiceUserID(Bundle bundle, String subServiceName);
+</code></pre>
+<p>The implementation uses the following fallbacks in case no mapping can be
found for the given subServiceName:</p>
<ol>
<li>Use user/principal mapping for the serviceName only (not considering
subServiceName)</li>
<li>Use default user (if one is configured in the OSGi configuration for PID
<code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl</code>).</li>
<li>Use default mapping (if it is enabled in the OSGi configuration for PID
<code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl</code>)
which looks up a user with id
<code>serviceuser--<bundleId>[--<subservice-name>]</code> (since
Service User Mapper 1.3.0, <a
href="https://issues.apache.org/jira/browse/SLING-6772";>SLING-6227</a>).</li>
</ol>
<p>In addition a service named <code>ServiceUserMapped</code> is registered
for each bundle and subservice name for which a service user mapping is
explicitly configured (<a
href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>). By
explicitly defining a (static) reference towards <code>ServiceUserMapped</code>
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 Service [...]
+<h4><a href="#validators-serviceprincipalsvalidator-and-serviceuservalidator"
id="validators-serviceprincipalsvalidator-and-serviceuservalidator">Validators
<code>ServicePrincipalsValidator</code> and
<code>ServiceUserValidator</code></a></h4>
+<p>The API defines two interfaces to validate principal names and user IDs
defined in service user mappings each with a single method. The default
<code>ServiceUserMapper</code> implementation allows to configure the set of
required implementations that need to be consulted to verify the validity of a
given mapping.</p>
+<p><code>ServicePrincipalsValidator</code> validates mappings by principal
names</p>
+<pre><code> <!-- TODO syntax marker (#!java) disabled --> boolean
isValid(Iterable<String> servicePrincipalNames, String serviceName,
String subServiceName);
+</code></pre>
+<p><code>ServiceUserValidator</code> validates mappings by user ID</p>
+<pre><code> <!-- TODO syntax marker (#!java) disabled --> boolean
isValid(String serviceUserId, String serviceName, String subServiceName)
+</code></pre>
+<p>Module <em>sling-org-apache-sling-jcr-resource</em> defines
<code>JcrSystemUserValidator</code> implementing both interfaces, which makes
sure all mapped principal names or user IDs refer to an existing JCR system
user.</p>
<h3><a href="#resourceresolverfactory"
id="resourceresolverfactory"><code>ResourceResolverFactory</code></a></h3>
<p>The second part is support for service access to the Resource Tree. To this
avail, the <code>ResourceResolverFactory</code> service is enhanced with a new
factory method</p>
<pre><code><!-- TODO syntax marker (#!java) disabled -->ResourceResolver
getServiceResourceResolver(Map<String, Object> authenticationInfo)
@@ -170,7 +183,7 @@
</code></pre>
<p>This method allows for access to the resource tree for services where the
service bundle is the bundle actually using the
<code>ResourceResolverFactory</code> service. The optional Subservice Name may
be provided as an entry in the <code>authenticationInfo</code> map.</p>
<p>In addition to having new API on the <code>ResourceResolverFactory</code>
service to be used by services, the <code>ResourceProviderFactory</code>
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.</p>
-<p>The default implementation leverages
<code>ServiceUserMapper.getServiceUserID()</code> to resolve the right user id
and throws a <code>LoginException</code> in case no mapping has been setup (and
none of the fallbacks returned a user id != <code>null</code> either).</p>
+<p>The default implementation leverages
<code>ServiceUserMapper.getServicePrincipalNames()</code> (and as fallback the
deprecated <code>ServiceUserMapper.getServiceID()</code>) to resolve the
principal names (fallback userID) and throws a <code>LoginException</code> in
case no mapping has been setup (and none of the fallbacks described returned a
valid user id either).</p>
<h3><a href="#slingrepository"
id="slingrepository"><code>SlingRepository</code></a></h3>
<p>The third part is an extension to the <code>SlingRepository</code>service
interface to support JCR Repository access for services:</p>
<pre><code><!-- TODO syntax marker (#!java) disabled -->Session
loginService(String subServiceName, String workspace)
@@ -179,11 +192,14 @@
<p>This method allows for access to the JCR Repository for services where the
service bundle is the bundle actually using the <code>SlingRepository</code>
service. The additional Subservice Name may be provided with the
<code>subServiceName</code> parameter.</p>
<h2><a href="#configuration" id="configuration">Configuration</a></h2>
<h3><a href="#service-user-mappings" id="service-user-mappings">Service User
Mappings</a></h3>
-<p>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 <a
href="https://issues.apache.org/jira/browse/SLING-6963";>SLING-6939</a>). This
is configured through an OSGi configuration for the factory configuration with
PID
<code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended</code>
(added in <a href="https://issues.apache.o [...]
-<pre><code><service-name>[:<subservice-name>]=<authorizable id
of a JCR system user>|"["<principal
name>{","<principal name>}"]"
+<p>For each service/subservice name combination an according mapping needs to
be provided. The mapping binds a service name/subservice name to one or many
principal names (since version 1.3.4, see <a
href="https://issues.apache.org/jira/browse/SLING-6963";>SLING-6963</a>). This
is configured through an OSGi configuration for the factory configuration with
PID
<code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended</code>
(added in <a href="https://issues.apache.org/ji [...]
+<pre><code><service-name>[:<subservice-name>]="["<principal
name of a JCR system user>{","<principal name of a JCR system
user>}"]"
+</code></pre>
+<p>The alternative mapping by ID has been deprecated (see: <a
href="https://issues.apache.org/jira/browse/SLING-10321";>SLING-10321</a>) and
will be disabled in the future.</p>
+<pre><code><service-name>[:<subservice-name>]=<id of a JCR
system user>
</code></pre>
-<p>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.</p>
-<p>The according user/principal must exist at the point in time where
<code>ResourceResolverFactory.getServiceResourceResolver(...)</code> or
<code>SlingRepository.loginService(...)</code> is called. If you rely on one of
those methods in your <code>activate</code> 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 <code>ServiceUserMapped</code> (see [...]
+<p>The principal based mapping (enclosed in square brackets) is in general
faster than the id based variant. It allows to directly reference multiple
service user principals and avoids resolving group memberships. This provides
full control over effective permissions granted to the service and prevents
privilege escalations through changing group permissions.</p>
+<p>The JCR system user whose principal name or ID is mapped must exist at the
point in time where
<code>ResourceResolverFactory.getServiceResourceResolver(...)</code> or
<code>SlingRepository.loginService(...)</code> is called. If you rely on one of
those methods in your <code>activate</code> 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 <code>S [...]
<p>Example OSGi DS Component</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Component(
reference = {
@@ -249,7 +265,7 @@ whitelist.bundles.regexp="^PAXEXAM.*$"
</div><footer class="footer">
<div class="content has-text-centered is-small">
<div class="revisionInfo">
- Last modified by <span class="author">Konrad
Windszus</span> on <span class="comment">Wed Dec 12 10:07:41 2018 +0100</span>
+ Last modified by <span class="author">angela</span> on
<span class="comment">Wed Apr 21 13:05:03 2021 +0200</span>
</div> <p>
Apache Sling, Sling, Apache, the Apache feather logo,
and the Apache Sling project logo are trademarks of The Apache Software
Foundation. All other marks mentioned may be trademarks or registered
trademarks of their respective owners.
</p><p>
