<?xml version="1.0" encoding="ISO-8859-1"?>

<document>

    <properties>
        <author email="pnever@apache.org">Peter Nevermann</author>
        <title>Security Howto</title>
    </properties>

    <body>
        <section name="Introduction">
            <p>
            Slide supports ACL (access control) according to draft 12 of the <a href="http://webdav.org/acl">WebDAV ACL specification</a>.
            </p>
            <p>
            By default, when running inside Tomcat, authentication for the WebDAV servlet is controlled by the realm
            <code>wrappers.catalina.SlideRealm</code>
            which accesses user names and passwords directly from the Slide namespace at <code>/slide/users</code>.
            </p>
            <p>
            In Slide, authentication and authorization (access control) can be en- or disabled independently from each other.
            </p>
        </section>
      
        <section name="Enabling or disabling authentication ">
            <p>
            By default, authentication is enabled in Slide.
            </p>
            <p>
            To disable authentication, open the webapp deployment descriptor, i.e. <code>WEB-INF/web.xml</code> in the webapp directory,
            and uncomment the two elements given by the xpath expressions
            <font color="blue"><code>/web-app/security-constraint</code></font> and <font color="blue"><code>/web-app/login-config</code></font>:
            <pre><font color="gray"><b>&lt;!--</b>
&lt;security-constraint&gt;
    &lt;web-resource-collection&gt;
        &lt;web-resource-name&gt;DAV resource&lt;/web-resource-name&gt;
        &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
        &lt;http-method&gt;COPY&lt;/http-method&gt;
        [...]
        &lt;http-method&gt;REBIND&lt;/http-method&gt;
    &lt;/web-resource-collection&gt;
    &lt;auth-constraint&gt;
        &lt;role-name&gt;root&lt;/role-name&gt;
        &lt;role-name&gt;guest&lt;/role-name&gt;
        &lt;role-name&gt;user&lt;/role-name&gt;
    &lt;/auth-constraint&gt;
&lt;/security-constraint&gt;
&lt;login-config&gt;
    &lt;auth-method&gt;BASIC&lt;/auth-method&gt;
    &lt;realm-name&gt;Slide DAV Server&lt;/realm-name&gt;
&lt;/login-config&gt;
<b>--&gt;</b></font>
            </pre>
            </p>
        </section>
      
        <section name="Enabling or disabling authorization (access control)">
            <p>
            By default, access control is enabled in Slide. If authentication is disabled (see above), the current user is "unauthenticated"
            and he/she has all permissions granted to DAV:unauthenticated.
            </p>
            <p>
            To disable access control, search for a configuration file named <i>slide.properties</i> in the classpath
            (if not there, you can create a new one at e.g. $CATALINA_HOME/common/classes)
            and set or add:
            <pre>org.apache.slide.security=false</pre>
            </p>
        </section>
        
        <section name="Other parameters (Domain.xml)">
            <p>
            There are some other namespace-specific parameters in the Slide configuration file <i>Domain.xml</i>, which
            influence the access control behavior of the server.
            </p>
            <ul>
            <li>
            <i>acl_semantics</i><br/> (xpath: <font color="blue"><code>/slide/namespace/configuration/parameter[@name="acl_semantics"]</code></font>):<br/>
            Class name of the access control implementation. Default value is <i>org.apache.slide.security.ACLSecurityImpl</i>.
            Allows to plug-in a customized security implementation.
            </li>
            <li>
            <i>acl_inheritance_type</i><br/> (xpath: <font color="blue"><code>/slide/namespace/configuration/parameter[@name="acl_inheritance_type"]</code></font>):<br/>
            Controls inheritance of ACEs over the namespace hierarchy.
            Can be one of <i>none</i> (no inheritance takes place), <i>root</i> (ACEs are inherited only from the root node),
            <i>path</i> (ACEs are inherited over the URI path) or <i>full</i> (ACEs are inherited over all available parent
            bindings). Default value is <i>path</i>, <i>full</i> is not yet implemented.
            </li>
            <li>
            <i>nested_roles_maxdepth</i><br/> (xpath: <font color="blue"><code>/slide/namespace/configuration/parameter[@name="nested_roles_maxdepth"]</code></font>):<br/>
            Defines the max. depth of nested roles/groups hierarchies. Default value is 0 (meaning no nesting). Value 1 means one sublevel, and so forth.
            </li>
            </ul>
        </section>
        
        <section name="More parameters (web.xml)">
            <p>
            There exist some servlet init parameters in the webapp deployment descriptor, i.e. <code>WEB-INF/web.xml</code>
            in the webapp directory, which influence the access control behavior of the server at the WebDAV level.
            </p>
            <ul>
            <li>
            <i>extendedAllprop</i><br/> (xpath: <font color="blue"><code>/web-app/servlet/init-param[param-name="extendedAllprop"]</code></font>):<br/>
            According to WebDAV DeltaV, ACL and Binding specifications,
            a DAV:allprop PROPFIND should <b>not</b> return any of the properties defined
            in any of those documents.
            For testing purposes, the specified behaviour can be disabled by 
            setting this parameter "true".
            </li>
            <li>
            <i>lockdiscoveryIncludesPrincipalURL</i><br/> (xpath: <font color="blue"><code>/web-app/servlet/init-param[param-name="lockdiscoveryIncludesPrincipalURL"]</code></font>):<br/>
            As proposed on February 08, 2003 by Lisa Dusseault in 
            w3c-dist-auth-request@w3.org, the DAV:lockdiscovery property should 
            include an element DAV:principal-URL with the semantics of the 
            WebDAV/ACL specification. This feature can be switched-off in case 
            of interoperability problems.
            </li>
            </ul>
            <p>
            </p>
        </section>
        
        <section name="Creation and maintenance principal resources (users, roles/groups) through WebDAV">
            <p>
            Although the creation and  maintenance of principal resources (users, roles/groups) is out of scope of the WebDAV/ACL
            specification, in Slide it is currently possible through a proprietary extension to the MKCOL method, provided the
            <i>SlideRealm</i> (<code>wrappers.catalina.SlideRealm</code>) is active.
            </p>
            <p>
            Resources created by MKCOL at the locations specified by the parameters:
            <li><i>userspath</i> (xpath: <font color="blue"><code>/slide/namespace/configuration/userspath</code></font>,</li>
            <li><i>groupspath</i> (xpath: <font color="blue"><code>/slide/namespace/configuration/groupspath</code></font>), or</li>
            <li><i>rolespath</i> (xpath: <font color="blue"><code>/slide/namespace/configuration/rolespath</code></font>)</li>
            <br/>
            automatically become principals,
            i.e. the property <i>DAV:resourcetype</i> automatically will contain the <i>DAV:principal</i> element.
            </p>
            <p>
            To set the password of a user, issue a PROPPATCH request setting the <i>password</i> property (namespace of the property:
            <i>http://jakarta.apache.org/slide/</i>).
            </p>
            <p>
            To associate users to a role/group, issue a PROPPATCH request setting the <i>DAV:group-member-set</i> property.<br/>
            <b><font color="red">NOTE:</font></b> to add a user(s) to a role/group, the value of the <i>DAV:group-member-set</i> property must
            list <b>all</b> members of the role/group, not just the user(s) being added.
            </p>
        </section>
    </body>
  
</document>

