Added: websites/staging/sling/trunk/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html ============================================================================== --- websites/staging/sling/trunk/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html (added) +++ websites/staging/sling/trunk/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html Tue May 22 09:41:22 2012 @@ -0,0 +1,298 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<html> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE- 2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + <head> + <title>Apache Sling - Managing users and groups (jackrabbit.usermanager)</title> + <link rel="stylesheet" href="/css/site.css" type="text/css" media="all"> + <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico";> + <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> + </head> + <body> + <div class="title"> + <div class="logo"> + <a href="http://sling.apache.org/site/index.html";> + <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png";> + </a> + </div> + <div class="header"> + <a href="http://www.apache.org/";> + <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png";> + </a> + </div> + </div> + + <div class="menu"> + <p><strong>Documentation</strong> <br /> +<a href="/getting-started.html">Getting Started</a> <br /> +<a href="/the-sling-engine.html">The Sling Engine</a> <br /> +<a href="/development.html">Development</a> <br /> +<a href="/bundles.html">Bundles</a> <br /> +<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br /> +<a href="/configuration.html">Configuration</a> <br /> +<a href="http://s.apache.org/sling.wiki";>Wiki</a> <br /> +<a href="http://s.apache.org/sling.faq";>FAQ</a> <br /> +<a href="/sitemap.html">Site Map</a></p> +<p><strong>API Docs</strong> <br /> +<a href="http://sling.apache.org/apidocs/sling6/index.html";>Sling 6</a> <br /> +<a href="http://sling.apache.org/apidocs/sling5/index.html";>Sling 5</a> <br /> +</p> +<p><strong>Project info</strong> <br /> +<a href="http://sling.apache.org/site/downloads.cgi";>Downloads</a> <br /> +<a href="http://www.apache.org/licenses/";>License</a> <br /> +<a href="/contributing.html">Contributing</a> <br /> +<a href="/news.html">News</a> <br /> +<a href="/links.html">Links</a> <br /> +<a href="/project-information.html">Project Information</a> <br /> +<a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a> <br /> +<a href="http://svn.apache.org/viewvc/sling/trunk";>Browse Source Repository</a> <br /> +<a href="/security.html">Security</a> <br /> +</p> +<p><strong>Sponsorship</strong> <br /> +<a href="http://www.apache.org/foundation/thanks.html";>Thanks</a> <br /> +<a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a> <br /> +<a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a> <br /> +</p> +<iframe + src="http://www.apache.org/ads/button.html"; + style="border-width:0; float: left" frameborder="0" + scrolling="no" + width="135" + height="135"> +</iframe> + </div> + + <div class="main"> + <div class="breadcrump" style="font-size: 80%;"> + <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/bundles.html">Bundles</a> + </div> + <h1>Managing users and groups (jackrabbit.usermanager)</h1> + <p>The <code>jackrabbit-usermanager</code> bundle delivers a REST interface to create, update and delete users and groups in the JCR. After installing the <code>jackrabbit-usermanager</code> bundle all REST services are exposed under the path /system/userManager.</p> +<div class="toc"> +<ul> +<li><a href="#list-users">List users</a></li> +<li><a href="#get-user">Get user</a></li> +<li><a href="#create-user">Create user</a></li> +<li><a href="#update-user">Update user</a></li> +<li><a href="#change-password">Change password</a></li> +<li><a href="#delete-user">Delete user</a></li> +<li><a href="#list-groups">List groups</a></li> +<li><a href="#get-group">Get group</a></li> +<li><a href="#create-group">Create group</a></li> +<li><a href="#update-group">Update group</a></li> +<li><a href="#delete-group">Delete group</a></li> +<li><a href="#automated-tests">Automated Tests</a></li> +<li><a href="#permissions-checking-from-scripts">Permissions checking from scripts</a></li> +<li><a href="#sample-user-interface-implementation">Sample User Interface Implementation</a></li> +</ul> +</div> +<h2 id="list-users">List users</h2> +<p>To list existing users a GET request to the <code>/system/userManager/user</code> resource can be posted. Depending on the configuration of the Default GET Servlet and/or the availability of a Servlet or Script handling the <code>sling/users</code> resource type, a result may be delivered.</p> +<p>Example with curl and the default JSON rendering:</p> +<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="o">/</span><span class="n">user</span><span class="o">.</span><span class="n">tidy</span><span class="mf">.1</span><span class="o">.</span><span class="n">json</span> +<span class="p">{</span> + <span class="s">"admin"</span><span class="p">:</span> <span class="p">{</span> + <span class="s">"memberOf"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMemberOf"</span><span class="p">:</span> <span class="o">[]</span> + <span class="p">},</span> + <span class="s">"anonymous"</span><span class="p">:</span> <span class="p">{</span> + <span class="s">"memberOf"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMemberOf"</span><span class="p">:</span> <span class="o">[]</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> + + +<h2 id="get-user">Get user</h2> +<p><em>since version 2.0.8</em> +The properties of a single user can be retrieved by sending a GET request to the user's resource at <code>/system/userManager/user/username</code> where <em>username</em> would be replaced with the name of the user. Depending on the configuration of the Default GET Servlet and/or the availability of a Servlet or Script handling the <code>sling/user</code> resource type, a result may be delivered.</p> +<p>Example with curl and the default JSON rendering:</p> +<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="sr">/user/</span><span class="n">admin</span><span class="o">.</span><span class="n">tidy</span><span class="mf">.1</span><span class="o">.</span><span class="n">json</span> +<span class="p">{</span> + <span class="s">"memberOf"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMemberOf"</span><span class="p">:</span> <span class="o">[]</span> +<span class="p">}</span> +</pre></div> + + +<p>If a non-existing user is requested a 404/NOT FOUND status is sent back.</p> +<h2 id="create-user">Create user</h2> +<p>To create a new user POST a request to <code>/system/userManager/user.create.<html or json></code>. The following parameters are available:</p> +<p>Responses: +| 200 | Success, a redirect is sent to the users resource locator with HTML (or JSON) describing status. |</p> +<p>Example with curl:</p> +<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">F:name</span><span class="o">=</span><span class="n">myuser</span> <span class="o">-</span><span class="n">Fpwd</span><span class="o">=</span><span class="n">password</span> <span class="o">-</span><span class="n">FpwdConfirm</span><span class="o">=</span><span class="n">password</span> <span class="o">-</span><span class="n">Fanyproperty1</span><span class="o">=</span><span class="n">value1</span> <span class="o">\</span> + <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="o">/</span><span class="n">user</span><span class="o">.</span><span class="n">create</span><span class="o">.</span><span class="n">html</span> +</pre></div> + + +<h2 id="update-user">Update user</h2> +<p>To update an existing user POST a request to <code>/system/userManager/user/username.update.<html or json></code>. You can NOT update the username or the password (see Change Password below) only the additional properties are updateable through this URL. The following parameters are available:</p> +<p>Responses: +| 200 | Success, a redirect is sent to the users resource locator with HTML (or JSON) describing status. |</p> +<p>Example</p> +<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">Fanyproperty1</span><span class="nv">@Delete</span> <span class="o">-</span><span class="n">Fproperty2</span><span class="o">=</span><span class="n">value2</span> <span class="o">\</span> + <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="sr">/user/m</span><span class="n">yuser</span><span class="o">.</span><span class="n">update</span><span class="o">.</span><span class="n">html</span> +</pre></div> + + +<h2 id="change-password">Change password</h2> +<p>To change a password of an existing user POST a request to <code>/system/userManager/user/username.changePassword.<html or json></code>. NOTE: since version 2.1.1, the oldPwd is optional if the current user is a user administrator. The following parameters are available:</p> +<p>Responses: +| 200 | Success, sent with no body. |</p> +<p>Example</p> +<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">FoldPwd</span><span class="o">=</span><span class="n">oldpassword</span> <span class="o">-</span><span class="n">FnewPwd</span><span class="o">=</span><span class="n">newpassword</span> <span class="o">=</span><span class="n">FnewPwdConfirm</span><span class="o">=</span><span class="n">newpassword</span> <span class="o">\</span> + <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="sr">/user/m</span><span class="n">yuser</span><span class="o">.</span><span class="n">changePassword</span><span class="o">.</span><span class="n">html</span> +</pre></div> + + +<h2 id="delete-user">Delete user</h2> +<p>To delete an existing user POST a request to <code>/system/userManager/user/username.delete.<html or json></code>. The following parameters are available:</p> +<p>Responses: +| 200 | Success, sent with no body. |</p> +<p>Example</p> +<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">Fgo</span><span class="o">=</span><span class="mi">1</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="sr">/user/m</span><span class="n">yuser</span><span class="o">.</span><span class="nb">delete</span><span class="o">.</span><span class="n">html</span> +</pre></div> + + +<h2 id="list-groups">List groups</h2> +<p>To list existing groups a GET request to the <code>/system/userManager/group</code> resource can be sent. Depending on the configuration of the Default GET Servlet and/or the availability of a Servlet or Script handling the <code>sling/groups</code> resource type, a result may be delivered.</p> +<p>Example with curl and the default JSON rendering:</p> +<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="o">/</span><span class="n">group</span><span class="o">.</span><span class="n">tidy</span><span class="mf">.1</span><span class="o">.</span><span class="n">json</span> +<span class="p">{</span> + <span class="s">"UserAdmin"</span><span class="p">:</span> <span class="p">{</span> + <span class="s">"members"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMembers"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"memberOf"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMemberOf"</span><span class="p">:</span> <span class="o">[]</span> + <span class="p">},</span> + <span class="s">"GroupAdmin"</span><span class="p">:</span> <span class="p">{</span> + <span class="s">"members"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMembers"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"memberOf"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMemberOf"</span><span class="p">:</span> <span class="o">[]</span> + <span class="p">},</span> + <span class="s">"administrators"</span><span class="p">:</span> <span class="p">{</span> + <span class="s">"members"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMembers"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"memberOf"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMemberOf"</span><span class="p">:</span> <span class="o">[]</span> +<span class="p">}</span> +<span class="p">}</span> +</pre></div> + + +<h2 id="get-group">Get group</h2> +<p>The properties of a single group can be retrieved by sending a GET request to the group's resource at <code>/system/userManager/group/groupname</code> where <em>groupname</em> would be replaced with the name of the group. Depending on the configuration of the Default GET Servlet and/or the availability of a Servlet or Script handling the <code>sling/group</code> resource type, a result may be delivered.</p> +<p>Example with curl and the default JSON rendering:</p> +<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="sr">/group/</span><span class="n">administrators</span><span class="o">.</span><span class="n">tidy</span><span class="mf">.1</span><span class="o">.</span><span class="n">json</span> +<span class="p">{</span> + <span class="s">"members"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMembers"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"memberOf"</span><span class="p">:</span> <span class="o">[]</span><span class="p">,</span> + <span class="s">"declaredMemberOf"</span><span class="p">:</span> <span class="o">[]</span> +<span class="p">}</span> +</pre></div> + + +<p>If a non-existing group is requested a 404/NOT FOUND status is sent back.</p> +<h2 id="create-group">Create group</h2> +<p>To create a new group POST a request to <code>/system/userManager/group.create.<html or json></code>. The following parameters are available:</p> +<p>Responses: +| 200 | Success, a redirect is sent to the group resource locator with HTML (or JSON) describing status. |</p> +<p>Example with curl:</p> +<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">F:name</span><span class="o">=</span><span class="n">mygroup</span> <span class="o">-</span><span class="n">Fanyproperty1</span><span class="o">=</span><span class="n">value1</span> <span class="o">\</span> + <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="o">/</span><span class="n">group</span><span class="o">.</span><span class="n">create</span><span class="o">.</span><span class="n">html</span> +</pre></div> + + +<h2 id="update-group">Update group</h2> +<p>To update an existing group POST a request to <code>/system/userManager/group/groupname.update.<html or json></code>. You can NOT update the name of the group only the additional properties are updateable. The following parameters are available:</p> +<p>Responses: +| 200 | Success, a redirect is sent to the groups resource locator with HTML (or JSON) describing status. |</p> +<p>Example</p> +<div class="codehilite"><pre><span class="n">curl</span> <span class="o">\-</span><span class="n">Fanyproperty1</span><span class="nv">@Delete</span> <span class="o">\-</span><span class="n">Fproperty2</span><span class="o">=</span><span class="n">value2</span> <span class="o">-</span><span class="n">F</span> <span class="s">":member=/system/userManager/user/myuser"</span> <span class="o">\</span> + <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="sr">/group/m</span><span class="n">ygroup</span><span class="o">.</span><span class="n">update</span><span class="o">.</span><span class="n">html</span> +</pre></div> + + +<h2 id="delete-group">Delete group</h2> +<p>To delete an existing group POST a request to <code>/system/userManager/group/groupname.delete.<html or json></code>. The following parameters are available:</p> +<p>Responses: +| 200 | Success, sent with no body. |</p> +<p>Example</p> +<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">Fgo</span><span class="o">=</span><span class="mi">1</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/system/</span><span class="n">userManager</span><span class="sr">/group/m</span><span class="n">ygroup</span><span class="o">.</span><span class="nb">delete</span><span class="o">.</span><span class="n">html</span> +</pre></div> + + +<h2 id="automated-tests">Automated Tests</h2> +<p>The <a href="">launchpad/testing</a> module contains test classes for various operations of the <code>jackrabbit-usermanager</code>. Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various operations, in a way that's guaranteed to be in sync with the actual Sling core code. If you have an idea for additional tests, make sure to let us know!</p> +<h2 id="permissions-checking-from-scripts">Permissions checking from scripts</h2> +<p><em>Since Version 2.0.6</em></p> +<p>When developing scripts that will perform user or group updates, you may want to know what actions the current user is provisioned to do. This information can be used to conditionally render parts of your page differently based on the user rights.</p> +<p>The jackrabbit.usermanager bundle provides a service (AuthorizablePrivilegesInfo) you can utilize to do help with this permission checking.</p> +<p>The AuthorizablePrivilegesInfo provides methods for checking the following actions +| Method | Description | +|--|--| +| canAddUser(jcrSession) | Checks if the current user may add new users | +| canAddGroup(jcrSession) | Checks if the current user may add new groups | +| canUpdateProperties(jcrSession, principalId) | Checks if the current user may update the properties of the specified principal | +| canRemove(jcrSession, principalId) | Checks if the current user may remove the specified user or group | +| canUpdateGroupMembers(jcrSession, groupId) | Checks if the current user may modify the membership of the specified group |</p> +<p>Example:</p> +<div class="codehilite"><pre><span class="cp"><%</span> + <span class="sr">//</span> <span class="n">lookup</span> <span class="n">the</span> <span class="n">service</span> + <span class="n">var</span> <span class="n">privilegesInfo</span> <span class="o">=</span> <span class="n">sling</span><span class="o">.</span><span class="n">getService</span><span class="p">(</span><span class="no">Packages</span><span class="o">.</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">jackrabbit</span><span class="o">.</span><span class="n">usermanager</span><span class="o">.</span><span class="n">AuthorizablePrivilegesInfo</span><span class="p">);</span> + + <span class="k">if</span> <span class="p">(</span><span class="n">privilegesInfo</span><span class="o">.</span><span class="n">canAddUser</span><span class="p">(</span><span class="n">currentSession</span><span class="p">))</span> <span class="p">{</span><span class="sr"></span> +<span class="sr"> //TODO: render the UI that allows the user to add a user here</span> +<span class="sr"> }</span> + +<span class="sr"> if (privilegesInfo.canAddGroup(currentSession)) {</span> +<span class="sr"> /</span><span class="o">/</span><span class="no">TODO</span><span class="p">:</span> <span class="n">render</span> <span class="n">the</span> <span class="no">UI</span> <span class="n">that</span> <span class="n">allows</span> <span class="n">the</span> <span class="n">user</span> <span class="n">to</span> <span class="n">add</span> <span class="n">a</span> <span class="n">group</span> <span class="n">here</span> + <span class="p">}</span> + + <span class="k">if</span> <span class="p">(</span><span class="n">privilegesInfo</span><span class="o">.</span><span class="n">canUpdateProperties</span><span class="p">(</span><span class="n">currentSession</span><span class="p">,</span> <span class="s2">"someUserId"</span><span class="p">))</span> <span class="p">{</span><span class="sr"></span> +<span class="sr"> //TODO: render the UI that allows the user to update the properties of the user here</span> +<span class="sr"> }</span> + +<span class="sr"> if (privilegesInfo.canRemove(currentSession, "someUserId")) {</span> +<span class="sr"> /</span><span class="o">/</span><span class="no">TODO</span><span class="p">:</span> <span class="n">render</span> <span class="n">the</span> <span class="no">UI</span> <span class="n">that</span> <span class="n">allows</span> <span class="n">the</span> <span class="n">user</span> <span class="n">to</span> <span class="n">remove</span> <span class="n">the</span> <span class="n">user</span> <span class="n">here</span> + <span class="p">}</span> + + <span class="k">if</span> <span class="p">(</span><span class="n">privilegesInfo</span><span class="o">.</span><span class="n">canUpdateGroupMembers</span><span class="p">(</span><span class="n">currentSession</span><span class="p">,</span> <span class="s2">"GroupName"</span><span class="p">))</span> <span class="p">{</span><span class="sr"></span> +<span class="sr"> //TODO: draw your UI that allows the user to update the group memebership here</span> +<span class="sr"> }</span> +<span class="cp">%></span><span class="x"></span> +</pre></div> + + +<h2 id="sample-user-interface-implementation">Sample User Interface Implementation</h2> +<p><em>Since Version 2.1.1</em></p> +<p>A sample implementation of ui pages for user/group management is provided @ http://svn.apache.org/viewvc/sling/trunk/samples/usermanager-ui/</p> + <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> + Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000 + </div> + <div class="trademarkFooter"> + 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. + </div> + </div> + </body> +</html>
![http://sling.apache.org/site/media.data/logo.png"](http://sling.apache.org/site/media.data/logo.png"){kind=link}
![http://sling.apache.org/site/media.data/apache.png"](http://sling.apache.org/site/media.data/apache.png"){kind=link}
