You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/08 00:00:15 UTC

[17/44] isis-site git commit: ISIS-1594: provide an 'edit' button

http://git-wip-us.apache.org/repos/asf/isis-site/blob/83a3755a/content/guides/ugsec.html
----------------------------------------------------------------------
diff --git a/content/guides/ugsec.html b/content/guides/ugsec.html
index 564715f..5242b89 100644
--- a/content/guides/ugsec.html
+++ b/content/guides/ugsec.html
@@ -1,12 +1,10 @@
 <!doctype html>
 <html class="no-js" lang="en">
-<head>
-    <meta charset="utf-8"/>
-    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
-
-    <title>Security</title>
-
-    <!--
+ <head> 
+  <meta charset="utf-8"> 
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"> 
+  <title>Security</title> 
+  <!--
         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
@@ -23,31 +21,21 @@
         KIND, either express or implied.  See the License for the
         specific language governing permissions and limitations
         under the License.
-    -->
-
-    <!-- No caching headers -->
-    <meta http-equiv="cache-control" content="no-cache" />
-    <meta http-equiv="pragma" content="no-cache" />
-    <meta http-equiv="expires" content="-1" />
-
-
-    <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
-    <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet" />
-    <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
-    <link href="../css/asciidoctor/colony.css" rel="stylesheet">
-    <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
-
-
-
-
-    <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet" />
-    <!--[if lt IE 9]>
+    --> 
+  <!-- No caching headers --> 
+  <meta http-equiv="cache-control" content="no-cache"> 
+  <meta http-equiv="pragma" content="no-cache"> 
+  <meta http-equiv="expires" content="-1"> 
+  <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line --> 
+  <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet"> 
+  <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script> 
+  <link href="../css/asciidoctor/colony.css" rel="stylesheet"> 
+  <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet"> 
+  <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet"> 
+  <!--[if lt IE 9]>
       <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.ie.css" rel="stylesheet" />
-    <![endif]-->
-
-
-
-    <style type="text/css">
+    <![endif]--> 
+  <style type="text/css">
         pre code {
             background-color: inherit;
             border-style: none;
@@ -192,9 +180,8 @@ table.CodeRay td.code>pre{padding:0}
         color:#fff;
         font-size: 1.1em;
     }
-    </style>
-
-    <style>
+    </style> 
+  <style>
         @media only screen and (min-width: 40.063em) {
           .top-bar {
             .contain-to-grid .top-bar {
@@ -205,9 +192,8 @@ table.CodeRay td.code>pre{padding:0}
         .row {
             max-width: 80rem;
         }
-    </style>
-
-    <style>
+    </style> 
+  <style>
         .extended-quote,
         .extended-quote-first {
             margin-left: 40px;
@@ -231,9 +217,8 @@ table.CodeRay td.code>pre{padding:0}
             text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
         }
         
-    </style>
-
-    <style>
+    </style> 
+  <style>
         body {
           position: relative;
         }
@@ -255,6 +240,7 @@ table.CodeRay td.code>pre{padding:0}
 
         div#doc-content {
             margin-top: 30px;
+            padding-top: 30px;
         }
 
         div.documentation-page table.frame-all {
@@ -286,9 +272,8 @@ table.CodeRay td.code>pre{padding:0}
             min-height: 2000px;
         }
 
-    </style>
-
-    <style>
+    </style> 
+  <style>
 
         @media only screen and (min-width: 768px) {
           #toc.toc2 ul ul { margin-left: -10px; }
@@ -316,15 +301,13 @@ table.CodeRay td.code>pre{padding:0}
         body div#toc2 li.tocify-item.active a {
             color: red;
         }
-    </style>
-
-    <style>
+    </style> 
+  <style>
         footer {
             margin-top: 1000px;
         }
-    </style>
-
-    <style>
+    </style> 
+  <style>
         /* overriding colony.css stylesheet */
         .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] {
            /*padding: 1.25em 1.5625em 1.125em 1.5625em;*/
@@ -372,9 +355,8 @@ table.CodeRay td.code>pre{padding:0}
         .imageblock img {
             margin-bottom: 10px;
         }
-    </style>
-
-    <style>
+    </style> 
+  <style>
         /* from http://ben.balter.com/2014/03/13/pages-anchor-links/ */
         .header-link {
           position: absolute;
@@ -395,9 +377,8 @@ table.CodeRay td.code>pre{padding:0}
         h6:hover .header-link {
           opacity: 1;
         }
-    </style>
-
-    <style>
+    </style> 
+  <style>
         .top-bar
         {
             -webkit-transition-duration: .5s;
@@ -425,309 +406,239 @@ table.CodeRay td.code>pre{padding:0}
             -webkit-transition-property: -webkit-transform;
             transition-property: transform;
         }
-    </style>
-
-    <style>
+    </style> 
+  <style>
         #doc-content a.guide {
             color: white;
         }
-    </style>
-
-    <style>
+    </style> 
+  <style>
+        .tocify {
+            margin-top: 80px;
+        }
+    </style> 
+  <style>
         .tocify {
             margin-top: 80px;
         }
-    </style>
-
-
-</script>
-
-</head>
-<body>
-
-<<div class="github-fork-ribbon-wrapper right" style="position: fixed;">
-    <div class="github-fork-ribbon">
-        <a href="https://github.com/apache/isis#fork-destination-box">Fork me on GitHub</a>
-    </div>
-</div>
-
-
-<div class="row">
-
-    <div class="fixed contain-to-grid header">
-        <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
-            <ul class="title-area">
-                <li class="name">
-                    <h1>
-                        <a href="/index.html">Apache Isis&trade;</a>
-                    </h1>
-                </li>
-                <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
-                <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
-            </ul>
-
-            <section class="top-bar-section">
-                <ul class="right">
-
-                    <li class="has-form">
-                       <FORM class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
-                        <div class="row collapse">
-                            <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
-                            <INPUT type="hidden" name="cof" value="FORID:0">
-                            <INPUT class="form-control" name="q" type="text" placeholder="Search">
-                        </div>
-                    </FORM>
-                     </li>
-
-                </ul>
-
-                <!-- Left Nav Section -->
-                <ul class="left">
-
-                    <li><a href="/documentation.html">Documentation</a></li>
-                    <li><a href="/downloads.html">Downloads</a></li>
-                    <li><a href="/help.html">Help</a></li>
-                    <li><a href="/asf.html">@ASF</a></li>
-
-                </ul>
-
-            </section>
-        </nav>
-    </div>
-</div>
-
-<div class="row">
-
-    <div id="doc-content-left" class="large-9 medium-9 columns">
-
-
-        <div id="doc-content">
-          <div class="sect1">
-<h2 id="_ugsec">1. Security</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>This guide describes the authentication and authorization features available to secure your Apache Isis application.</p>
-</div>
-<div class="sect2">
-<h3 id="_other_guides">1.1. Other Guides</h3>
-<div class="paragraph">
-<p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
-</div>
-<div class="paragraph">
-<p>The user guides available are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="ugfun.html">Fundamentals</a></p>
-</li>
-<li>
-<p><a href="ugvw.html">Wicket viewer</a></p>
-</li>
-<li>
-<p><a href="ugvro.html">Restful Objects viewer</a></p>
-</li>
-<li>
-<p><a href="ugdno.html">DataNucleus object store</a></p>
-</li>
-<li>
-<p><a href="#">Security</a> (this guide)</p>
-</li>
-<li>
-<p><a href="ugtst.html">Testing</a></p>
-</li>
-<li>
-<p><a href="ugbtb.html">Beyond the Basics</a></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The reference guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="rgant.html">Annotations</a></p>
-</li>
-<li>
-<p><a href="rgsvc.html">Domain Services</a></p>
-</li>
-<li>
-<p><a href="rgcfg.html">Configuration Properties</a></p>
-</li>
-<li>
-<p><a href="rgcms.html">Classes, Methods and Schema</a></p>
-</li>
-<li>
-<p><a href="rgmvn.html">Apache Isis Maven plugin</a></p>
-</li>
-<li>
-<p><a href="rgfis.html">Framework Internal Services</a></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The remaining guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="dg.html">Developers' Guide</a> (how to set up a development environment
-for Apache Isis and contribute back to the project)</p>
-</li>
-<li>
-<p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_terminology">1.2. Terminology</h3>
-<div class="paragraph">
-<p>Apache Isis has built-in support for authentication and authorization:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>By "authentication" we mean logging into the application using some credentials, typically a username and password.  Authentication also means looking up the set of roles to which a user belongs.</p>
-</li>
-<li>
-<p>By "authorization" we mean permissions: granting roles to have access to features (object member) of the app.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Isis has two levels of permissions.  <em>Read</em> permission means that the user can view the object member; it will be rendered in the UI.  An action with only read permission will be shown disabled ("greyed out".  <em>Write</em> permission means that the object member can be changed.  For actions this means that they can be invoked.</p>
-</div>
-<div class="paragraph">
-<p>Isis provides an API for both authentication and authorization, and provides an implementation that integrates with <a href="http://shiro.apache.org">Apache Shiro</a>.  Shiro in turn uses the concept of a <em>realm</em> as a source for both authentication and optionally authorization.</p>
-</div>
-<div class="paragraph">
-<p>Shiro ships with a simple text-based realm&#8201;&#8212;&#8201;the <code>IniRealm</code>&#8201;&#8212;&#8201;which reads users (and password), user roles and role permissions from the <code>WEB-INF/shiro.ini</code> file.  The <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> is configured to use this realm.</p>
-</div>
-<div class="paragraph">
-<p>Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups.  Apache Isis in turn extends this with its <code>IsisLdapRealm</code>, which provides more flexibility for both group/role and role/permissions management.</p>
-</div>
-<div class="paragraph">
-<p>In addition, the (non-ASF) <a href="http://www.isisaddons.org">Isis Addons</a> provides the <a href="http://github.com/isisaddons/isis-module-security">Isis addons' security</a> module, which also provides an implementation of the Shiro <code>Realm</code> API.  However, the security module also represents users, roles and permissions as domain objects, allowing them to be administered through Apache Isis itself.  Moreover, the security module can optionally delegate password management to a subsidiary (delegate) realm (usually LDAP as discussed above).</p>
-</div>
-<div class="paragraph">
-<p>In addition to Apache Isis' Shiro-based implementation of its authentication and authorization APIs, Isis also provides a "bypass" implementation, useful for quick-n-dirty prototyping when you want to in effect disable (bypass) security completely.</p>
-</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-<div class="title">What about auditing?</div>
-<div class="paragraph">
-<p>A further aspect of security is auditing: recording what data was modified by which user.</p>
-</div>
-<div class="paragraph">
-<p>Apache Isis provides the <a href="rgsvc.html#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a>
-can be used to track the actions being invoked, and the <a href="rgsvc.html#_rgsvc_spi_AuditerService"><code>AuditerService</code></a>
-captures what data was modified as a result (auditing).  When <code>Interaction</code>s are persisted (eg by way of
-(non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module) this provides excellent
-traceability.  The (non-ASF) <a href="http://github.com/isisaddons/isis-module-audit">Isis addons' audit</a> module provides an
-implementation of the <code>AuditerService</code>.</p>
-</div>
-<div class="paragraph">
-<p>For earlier versions of the framework the
-<a href="rgsvc.html#_rgsvc_spi_CommandService"><code>CommandService</code></a> can be used to capture actions, while the (deprecated)
-<a href="rgsvc.html#_rgsvc_spi_AuditingService"><code>AuditingService</code></a> used to capture data modified.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugsec_configuring-isis-to-use-shiro">2. Configuring Apache Isis to use Shiro</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Apache Isis' security mechanism is configurable, specifying an <code>Authenticator</code> and an <code>Authorizor</code> (non-public) APIs.  The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.</p>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>The <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> is pre-configured to use Apache Shiro, so much of what follows is set up already.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="sect2">
-<h3 id="_telling_apache_isis_to_use_shiro">2.1. Telling Apache Isis to use Shiro</h3>
-<div class="paragraph">
-<p>To tell Apache Isis to use Shiro, update the <code>WEB-INF/isis.properties</code> file:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.authentication=shiro
-isis.authorization=shiro</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This installs the appropriate implementation (the <code>ShiroAuthenticatorOrAuthorizor</code> class) that use Shiro&#8217;s APIs to perform authentication and authorization:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/security/security-apis-impl/configure-isis-to-use-shiro.png" alt="configure isis to use shiro" width="600px">
-</div>
-</div>
-<div class="paragraph">
-<p>The figure above doesn&#8217;t tell the whole story; we haven&#8217;t yet seen how Shiro itself is configured to use realms.  The <code>ShiroAuthenticatorOrAuthorizor</code> is in essence the glue between the Apache Isis runtime and Shiro.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_configuring_isis_shiro_authenticator">2.2. Configuring Isis' Shiro Authenticator</h3>
-<div class="paragraph">
-<p>The <code>ShiroAuthenticatorOrAuthorizor</code> class itself supports a single optional property.  This can
-be configured in <code>authentication_shiro.properties</code> file:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.authentication.shiro.autoLogoutIfAlreadyAuthenticated=false</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This configuration property only comes into effect for the <a href="ugvro.html">Restful Objects viewer</a>; if set then
-the Shiro subject - if found to be still authenticated - will be logged out anyway and then re-authenticated.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>This auto-logout behaviour was the default prior to <code>1.13.0</code>, but is believed to be the root cause of some
-exceptions caused by a possible race condition.  There should generally be no need to change this property from its
-default (<code>false</code>).</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_bootstrapping_shiro">2.3. Bootstrapping Shiro</h3>
-<div class="paragraph">
-<p>The Shiro environment (in essence, thread-locals holding the security credentials) needs to be bootstrapped using the following settings in the <code>WEB-INF/web.xml</code> file:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;listener&gt;</span>
+    </style>  
+ </head> 
+ <body> 
+  <div class="row"> 
+   <div class="fixed contain-to-grid header"> 
+    <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem"> 
+     <ul class="title-area"> 
+      <li class="name"> <h1> <a href="/index.html">Apache Isis\u2122</a> </h1> </li> 
+      <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone --> 
+      <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li> 
+     </ul> 
+     <section class="top-bar-section"> 
+      <ul class="right"> 
+       <li class="has-form"> 
+        <form class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse"> 
+         <div class="row collapse"> 
+          <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya"> 
+          <input type="hidden" name="cof" value="FORID:0"> 
+          <input class="form-control" name="q" type="text" placeholder="Search"> 
+         </div> 
+        </form> </li> 
+      </ul> 
+      <!-- Left Nav Section --> 
+      <ul class="left"> 
+       <li><a href="/documentation.html">Documentation</a></li> 
+       <li><a href="/downloads.html">Downloads</a></li> 
+       <li><a href="/help.html">Help</a></li> 
+       <li><a href="/asf.html">@ASF</a></li> 
+      </ul> 
+     </section> 
+    </nav> 
+   </div> 
+  </div> 
+  <div class="row"> 
+   <div id="doc-content-left" class="large-9 medium-9 columns"> 
+    <div id="doc-content">
+     <button type="button" class="button secondary" onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc&quot;" style="float: right; font-size: small; padding: 6px;  "><i class="fa fa-pencil-square-o"></i>&nbsp;Edit</button> 
+     <div class="sect1"> 
+      <h2 id="_ugsec">1. Security</h2>
+      <button type="button" class="button secondary" onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugsec.adoc&quot;" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i>&nbsp;Edit</button> 
+      <div class="sectionbody"> 
+       <div class="paragraph"> 
+        <p>This guide describes the authentication and authorization features available to secure your Apache Isis application.</p> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_other_guides">1.1. Other Guides</h3> 
+        <div class="paragraph"> 
+         <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The user guides available are:</p> 
+        </div> 
+        <div class="ulist"> 
+         <ul> 
+          <li> <p><a href="ugfun.html">Fundamentals</a></p> </li> 
+          <li> <p><a href="ugvw.html">Wicket viewer</a></p> </li> 
+          <li> <p><a href="ugvro.html">Restful Objects viewer</a></p> </li> 
+          <li> <p><a href="ugdno.html">DataNucleus object store</a></p> </li> 
+          <li> <p><a href="#">Security</a> (this guide)</p> </li> 
+          <li> <p><a href="ugtst.html">Testing</a></p> </li> 
+          <li> <p><a href="ugbtb.html">Beyond the Basics</a></p> </li> 
+         </ul> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The reference guides are:</p> 
+        </div> 
+        <div class="ulist"> 
+         <ul> 
+          <li> <p><a href="rgant.html">Annotations</a></p> </li> 
+          <li> <p><a href="rgsvc.html">Domain Services</a></p> </li> 
+          <li> <p><a href="rgcfg.html">Configuration Properties</a></p> </li> 
+          <li> <p><a href="rgcms.html">Classes, Methods and Schema</a></p> </li> 
+          <li> <p><a href="rgmvn.html">Apache Isis Maven plugin</a></p> </li> 
+          <li> <p><a href="rgfis.html">Framework Internal Services</a></p> </li> 
+         </ul> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The remaining guides are:</p> 
+        </div> 
+        <div class="ulist"> 
+         <ul> 
+          <li> <p><a href="dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p> </li> 
+          <li> <p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li> 
+         </ul> 
+        </div> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_terminology">1.2. Terminology</h3> 
+        <div class="paragraph"> 
+         <p>Apache Isis has built-in support for authentication and authorization:</p> 
+        </div> 
+        <div class="ulist"> 
+         <ul> 
+          <li> <p>By "authentication" we mean logging into the application using some credentials, typically a username and password. Authentication also means looking up the set of roles to which a user belongs.</p> </li> 
+          <li> <p>By "authorization" we mean permissions: granting roles to have access to features (object member) of the app.</p> </li> 
+         </ul> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Isis has two levels of permissions. <em>Read</em> permission means that the user can view the object member; it will be rendered in the UI. An action with only read permission will be shown disabled ("greyed out". <em>Write</em> permission means that the object member can be changed. For actions this means that they can be invoked.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Isis provides an API for both authentication and authorization, and provides an implementation that integrates with <a href="http://shiro.apache.org">Apache Shiro</a>. Shiro in turn uses the concept of a <em>realm</em> as a source for both authentication and optionally authorization.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Shiro ships with a simple text-based realm\u2009\u2014\u2009the <code>IniRealm</code>\u2009\u2014\u2009which reads users (and password), user roles and role permissions from the <code>WEB-INF/shiro.ini</code> file. The <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> is configured to use this realm.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups. Apache Isis in turn extends this with its <code>IsisLdapRealm</code>, which provides more flexibility for both group/role and role/permissions management.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>In addition, the (non-ASF) <a href="http://www.isisaddons.org">Isis Addons</a> provides the <a href="http://github.com/isisaddons/isis-module-security">Isis addons' security</a> module, which also provides an implementation of the Shiro <code>Realm</code> API. However, the security module also represents users, roles and permissions as domain objects, allowing them to be administered through Apache Isis itself. Moreover, the security module can optionally delegate password management to a subsidiary (delegate) realm (usually LDAP as discussed above).</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>In addition to Apache Isis' Shiro-based implementation of its authentication and authorization APIs, Isis also provides a "bypass" implementation, useful for quick-n-dirty prototyping when you want to in effect disable (bypass) security completely.</p> 
+        </div> 
+        <div class="admonitionblock note"> 
+         <table> 
+          <tbody>
+           <tr> 
+            <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> 
+            <td class="content"> 
+             <div class="title">
+              What about auditing?
+             </div> 
+             <div class="paragraph"> 
+              <p>A further aspect of security is auditing: recording what data was modified by which user.</p> 
+             </div> 
+             <div class="paragraph"> 
+              <p>Apache Isis provides the <a href="rgsvc.html#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a> can be used to track the actions being invoked, and the <a href="rgsvc.html#_rgsvc_spi_AuditerService"><code>AuditerService</code></a> captures what data was modified as a result (auditing). When <code>Interaction</code>s are persisted (eg by way of (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module) this provides excellent traceability. The (non-ASF) <a href="http://github.com/isisaddons/isis-module-audit">Isis addons' audit</a> module provides an implementation of the <code>AuditerService</code>.</p> 
+             </div> 
+             <div class="paragraph"> 
+              <p>For earlier versions of the framework the <a href="rgsvc.html#_rgsvc_spi_CommandService"><code>CommandService</code></a> can be used to capture actions, while the (deprecated) <a href="rgsvc.html#_rgsvc_spi_AuditingService"><code>AuditingService</code></a> used to capture data modified.</p> 
+             </div> </td> 
+           </tr> 
+          </tbody>
+         </table> 
+        </div> 
+       </div> 
+      </div> 
+     </div> 
+     <div class="sect1"> 
+      <h2 id="_ugsec_configuring-isis-to-use-shiro">2. Configuring Apache Isis to use Shiro</h2>
+      <button type="button" class="button secondary" onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc&quot;" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i>&nbsp;Edit</button> 
+      <div class="sectionbody"> 
+       <div class="paragraph"> 
+        <p>Apache Isis' security mechanism is configurable, specifying an <code>Authenticator</code> and an <code>Authorizor</code> (non-public) APIs. The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.</p> 
+       </div> 
+       <div class="admonitionblock tip"> 
+        <table> 
+         <tbody>
+          <tr> 
+           <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> 
+           <td class="content"> 
+            <div class="paragraph"> 
+             <p>The <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> is pre-configured to use Apache Shiro, so much of what follows is set up already.</p> 
+            </div> </td> 
+          </tr> 
+         </tbody>
+        </table> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_telling_apache_isis_to_use_shiro">2.1. Telling Apache Isis to use Shiro</h3> 
+        <div class="paragraph"> 
+         <p>To tell Apache Isis to use Shiro, update the <code>WEB-INF/isis.properties</code> file:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">isis.authentication=shiro
+isis.authorization=shiro</code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>This installs the appropriate implementation (the <code>ShiroAuthenticatorOrAuthorizor</code> class) that use Shiro\u2019s APIs to perform authentication and authorization:</p> 
+        </div> 
+        <div class="imageblock"> 
+         <div class="content"> 
+          <img src="images/security/security-apis-impl/configure-isis-to-use-shiro.png" alt="configure isis to use shiro" width="600px"> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The figure above doesn\u2019t tell the whole story; we haven\u2019t yet seen how Shiro itself is configured to use realms. The <code>ShiroAuthenticatorOrAuthorizor</code> is in essence the glue between the Apache Isis runtime and Shiro.</p> 
+        </div> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_configuring_isis_shiro_authenticator">2.2. Configuring Isis' Shiro Authenticator</h3> 
+        <div class="paragraph"> 
+         <p>The <code>ShiroAuthenticatorOrAuthorizor</code> class itself supports a single optional property. This can be configured in <code>authentication_shiro.properties</code> file:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">isis.authentication.shiro.autoLogoutIfAlreadyAuthenticated=false</code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>This configuration property only comes into effect for the <a href="ugvro.html">Restful Objects viewer</a>; if set then the Shiro subject - if found to be still authenticated - will be logged out anyway and then re-authenticated.</p> 
+        </div> 
+        <div class="admonitionblock warning"> 
+         <table> 
+          <tbody>
+           <tr> 
+            <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> 
+            <td class="content"> 
+             <div class="paragraph"> 
+              <p>This auto-logout behaviour was the default prior to <code>1.13.0</code>, but is believed to be the root cause of some exceptions caused by a possible race condition. There should generally be no need to change this property from its default (<code>false</code>).</p> 
+             </div> </td> 
+           </tr> 
+          </tbody>
+         </table> 
+        </div> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_bootstrapping_shiro">2.3. Bootstrapping Shiro</h3> 
+        <div class="paragraph"> 
+         <p>The Shiro environment (in essence, thread-locals holding the security credentials) needs to be bootstrapped using the following settings in the <code>WEB-INF/web.xml</code> file:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;listener&gt;</span>
     <span class="tag">&lt;listener-class&gt;</span>org.apache.shiro.web.env.EnvironmentLoaderListener<span class="tag">&lt;/listener-class&gt;</span>
 <span class="tag">&lt;/listener&gt;</span>
 <span class="tag">&lt;filter&gt;</span>
@@ -737,164 +648,155 @@ default (<code>false</code>).</p>
 <span class="tag">&lt;filter-mapping&gt;</span>
     <span class="tag">&lt;filter-name&gt;</span>ShiroFilter<span class="tag">&lt;/filter-name&gt;</span>
     <span class="tag">&lt;url-pattern&gt;</span>/*<span class="tag">&lt;/url-pattern&gt;</span>
-<span class="tag">&lt;/filter-mapping&gt;</span></code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Based on this Shiro will then read <code>WEB-INF/shiro.ini</code> file to configure its Realm definitions for authentication and authorization.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="__code_web_inf_shiro_ini_code">2.4. <code>WEB-INF/shiro.ini</code></h3>
-<div class="paragraph">
-<p>The <code>shiro.ini</code> file is used to specify the realm(s) that Shiro will delegate to:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">securityManager.realms = $realmName</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Shiro&#8217;s ini file supports a "poor-man&#8217;s" dependency injection (<a href="https://shiro.apache.org/configuration.html">their words</a>), and so <code>$realmName</code> in the above example is a reference to a realm defined elsewhere in <code>shiro.ini</code>.  The subsequent sections describe the specifics for thevarious realm implementations available to you.</p>
-</div>
-<div class="paragraph">
-<p>It&#8217;s also possible to configure Shiro to support multiple realms.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">securityManager.realms = $realm1,$realm2</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>You can learn more about Shiro realms in the <a href="http://shiro.apache.org/realm.html">Shiro documentation</a>.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugsec_shiro-ini-realm">3. Shiro Ini Realm</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Probably the simplest realm to use is Shiro&#8217;s built-in <code>IniRealm</code>, which reads from the (same) <code>WEB-INF/shiro.ini</code> file.</p>
-</div>
-<div class="paragraph">
-<p>This is suitable for prototyping, but isn&#8217;t intended for production use, if only because user/password credentials are stored in plain text.  Nevertheless, it&#8217;s a good starting point.  The app generated by the <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> is configured to use this realm.</p>
-</div>
-<div class="paragraph">
-<p>The diagram below shows the Isis and components involved:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG" alt="configure shiro to use ini realm" width="600px">
-</div>
-</div>
-<div class="paragraph">
-<p>The realm is responsible for validating the user credentials, and then creates a Shiro <a href="http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html"><code>Subject</code></a> which represents the user (for the current request).  Apache Isis <code>Authenticator</code> component then interacts with the <code>Subject</code> in order to check permissions.</p>
-</div>
-<div class="sect2">
-<h3 id="_shiro_configuration">3.1. Shiro Configuration</h3>
-<div class="paragraph">
-<p>To use the built-in <code>IniRealm</code>, we add the following to <code>WEB-INF/shiro.ini</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">securityManager.realms = $iniRealm</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>(Unlike other realms) there is no need to "define" <code>$iniRealm</code>; it is automatically available to us.</p>
-</div>
-<div class="paragraph">
-<p>Specifying <code>$iniRealm</code> means that the usernames/passwords, roles and permissions are read from the <code>shiro.ini</code> file itself.  Specifically:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>the users/passwords and their roles from the <code>[users]</code> sections;</p>
-</li>
-<li>
-<p>the roles are mapped to permissions in the <code>[roles]</code> section.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The format of these is described below.</p>
-</div>
-<div class="sect3">
-<h4 id="__code_users_code_section">3.1.1. <code>[users]</code> section</h4>
-<div class="paragraph">
-<p>This section lists users, passwords and their roles.</p>
-</div>
-<div class="paragraph">
-<p>For example:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">sven = pass, admin_role
+<span class="tag">&lt;/filter-mapping&gt;</span></code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Based on this Shiro will then read <code>WEB-INF/shiro.ini</code> file to configure its Realm definitions for authentication and authorization.</p> 
+        </div> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="__code_web_inf_shiro_ini_code">2.4. <code>WEB-INF/shiro.ini</code></h3> 
+        <div class="paragraph"> 
+         <p>The <code>shiro.ini</code> file is used to specify the realm(s) that Shiro will delegate to:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">securityManager.realms = $realmName</code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Shiro\u2019s ini file supports a "poor-man\u2019s" dependency injection (<a href="https://shiro.apache.org/configuration.html">their words</a>), and so <code>$realmName</code> in the above example is a reference to a realm defined elsewhere in <code>shiro.ini</code>. The subsequent sections describe the specifics for thevarious realm implementations available to you.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>It\u2019s also possible to configure Shiro to support multiple realms.</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">securityManager.realms = $realm1,$realm2</code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>You can learn more about Shiro realms in the <a href="http://shiro.apache.org/realm.html">Shiro documentation</a>.</p> 
+        </div> 
+       </div> 
+      </div> 
+     </div> 
+     <div class="sect1"> 
+      <h2 id="_ugsec_shiro-ini-realm">3. Shiro Ini Realm</h2>
+      <button type="button" class="button secondary" onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc&quot;" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i>&nbsp;Edit</button> 
+      <div class="sectionbody"> 
+       <div class="paragraph"> 
+        <p>Probably the simplest realm to use is Shiro\u2019s built-in <code>IniRealm</code>, which reads from the (same) <code>WEB-INF/shiro.ini</code> file.</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>This is suitable for prototyping, but isn\u2019t intended for production use, if only because user/password credentials are stored in plain text. Nevertheless, it\u2019s a good starting point. The app generated by the <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> is configured to use this realm.</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>The diagram below shows the Isis and components involved:</p> 
+       </div> 
+       <div class="imageblock"> 
+        <div class="content"> 
+         <img src="images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG" alt="configure shiro to use ini realm" width="600px"> 
+        </div> 
+       </div> 
+       <div class="paragraph"> 
+        <p>The realm is responsible for validating the user credentials, and then creates a Shiro <a href="http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html"><code>Subject</code></a> which represents the user (for the current request). Apache Isis <code>Authenticator</code> component then interacts with the <code>Subject</code> in order to check permissions.</p> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_shiro_configuration">3.1. Shiro Configuration</h3> 
+        <div class="paragraph"> 
+         <p>To use the built-in <code>IniRealm</code>, we add the following to <code>WEB-INF/shiro.ini</code>:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">securityManager.realms = $iniRealm</code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>(Unlike other realms) there is no need to "define" <code>$iniRealm</code>; it is automatically available to us.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Specifying <code>$iniRealm</code> means that the usernames/passwords, roles and permissions are read from the <code>shiro.ini</code> file itself. Specifically:</p> 
+        </div> 
+        <div class="ulist"> 
+         <ul> 
+          <li> <p>the users/passwords and their roles from the <code>[users]</code> sections;</p> </li> 
+          <li> <p>the roles are mapped to permissions in the <code>[roles]</code> section.</p> </li> 
+         </ul> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The format of these is described below.</p> 
+        </div> 
+        <div class="sect3"> 
+         <h4 id="__code_users_code_section">3.1.1. <code>[users]</code> section</h4> 
+         <div class="paragraph"> 
+          <p>This section lists users, passwords and their roles.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>For example:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="ini">sven = pass, admin_role
 dick = pass, user_role, analysis_role, self-install_role
-bob  = pass, user_role, self-install_role</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The first value is the password (eg "pass", the remaining values are the role(s).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="__code_roles_code_section">3.1.2. <code>[roles]</code> section</h4>
-<div class="paragraph">
-<p>This section lists roles and their corresponding permissions.</p>
-</div>
-<div class="paragraph">
-<p>For example:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">user_role = *:ToDoItems:*:*,\
+bob  = pass, user_role, self-install_role</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The first value is the password (eg "pass", the remaining values are the role(s).</p> 
+         </div> 
+        </div> 
+        <div class="sect3"> 
+         <h4 id="__code_roles_code_section">3.1.2. <code>[roles]</code> section</h4> 
+         <div class="paragraph"> 
+          <p>This section lists roles and their corresponding permissions.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>For example:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="ini">user_role = *:ToDoItems:*:*,\
             *:ToDoItem:*:*,\
             *:ToDoAppDashboard:*:*
 analysis_role = *:ToDoItemAnalysis:*:*,\
             *:ToDoItemsByCategoryViewModel:*:*,\
             *:ToDoItemsByDateRangeViewModel:*:*
 self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The value is a comma-separated list of permissions for the role.  The format is:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">packageName:className:memberName:r,w</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>where:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>memberName</code> is the property, collection or action name.</p>
-</li>
-<li>
-<p><code>r</code> indicates that the member is visible</p>
-</li>
-<li>
-<p><code>w</code> indicates that the member is usable (editable or invokable)</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>and where each of the parts of the permission string can be wildcarded using <code>*</code>.</p>
-</div>
-<div class="paragraph">
-<p>Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards.</p>
-</div>
-<div class="paragraph">
-<p>Thus:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">com.mycompany.myapp:Customer:firstName:r,w   # view or edit customer's firstName
+admin_role = *</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The value is a comma-separated list of permissions for the role. The format is:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="ini">packageName:className:memberName:r,w</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>where:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><code>memberName</code> is the property, collection or action name.</p> </li> 
+           <li> <p><code>r</code> indicates that the member is visible</p> </li> 
+           <li> <p><code>w</code> indicates that the member is usable (editable or invokable)</p> </li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>and where each of the parts of the permission string can be wildcarded using <code>*</code>.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Thus:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="ini">com.mycompany.myapp:Customer:firstName:r,w   # view or edit customer's firstName
 com.mycompany.myapp:Customer:lastName:r      # view customer's lastName only
 com.mycompany.myapp:Customer:placeOrder:*    # view and invoke placeOrder action
 com.mycompany.myapp:Customer:placeOrder      # ditto
@@ -904,93 +806,94 @@ com.mycompany.myapp:*:*:*                    # view/edit for all classes in myap
 com.mycompany.myapp:*:*                      # ditto
 com.mycompany.myapp:*                        # ditto
 com.mycompany.myapp                          # ditto
-*                                            # view/edit access to everything</code></pre>
-</div>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>The format of the permissions string is configurable in Shiro, and Apache Isis uses this to provide an extended wildcard format, described <a href="#_ugsec_shiro-isis-enhanced-wildcard-permission">here</a>.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_externalized_inirealm">3.2. Externalized IniRealm</h3>
-<div class="paragraph">
-<p>There&#8217;s no requirement for all users/roles to be defined in the <code>shiro.ini</code> file.  Instead, a realm can be defined that loads its users/roles from some other resource.</p>
-</div>
-<div class="paragraph">
-<p>For example:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">$realm1=org.apache.shiro.realm.text.IniRealm <i class="conum" data-value="1"></i><b>(1)</b>
-realm1.resourcePath=classpath:webapp/realm1.ini <i class="conum" data-value="2"></i><b>(2)</b></code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>happens to (coincidentally) be the <a href="http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html">same implementation</a> as Shiro&#8217;s built-in $iniRealm</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>in this case load the users/roles from the <code>src/main/resources/webapp/realm1.ini</code> file.</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>Note that a URL could be provided as the <code>resourcePath</code>, so a centralized config file could be used.  Even so, the</p>
-</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>If configured this way then the <code>[users]</code> and <code>[roles]</code> sections of <code>shiro.ini</code> become unused. Instead, the corresponding sections from for <code>realm1.ini</code> are used instead.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugsec_shiro-isis-ldap-realm">4. Isis Ldap Realm</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Isis ships with an implementation of <a href="http://shiro.apache.org">Apache Shiro</a>'s <code>Realm</code> class that allows user authentication and authorization to be performed against an LDAP server.</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG" alt="configure shiro to use isis ldap realm" width="600px">
-</div>
-</div>
-<div class="paragraph">
-<p>The LDAP database stores the user/passwords and user groups, while the <code>shiro.ini</code> file is used to map the LDAP groups to roles, and to map the roles to permissions.</p>
-</div>
-<div class="sect2">
-<h3 id="_shiro_configuration_2">4.1. Shiro Configuration</h3>
-<div class="paragraph">
-<p>To use LDAP involves telling Shiro how to instantiate the realm.  This bootstrapping info lives in the <code>WEB-INF/shiro.ini</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
+*                                            # view/edit access to everything</code></pre> 
+          </div> 
+         </div> 
+         <div class="admonitionblock tip"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>The format of the permissions string is configurable in Shiro, and Apache Isis uses this to provide an extended wildcard format, described <a href="#_ugsec_shiro-isis-enhanced-wildcard-permission">here</a>.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+        </div> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_externalized_inirealm">3.2. Externalized IniRealm</h3> 
+        <div class="paragraph"> 
+         <p>There\u2019s no requirement for all users/roles to be defined in the <code>shiro.ini</code> file. Instead, a realm can be defined that loads its users/roles from some other resource.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>For example:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">$realm1=org.apache.shiro.realm.text.IniRealm <i class="conum" data-value="1"></i><b>(1)</b>
+realm1.resourcePath=classpath:webapp/realm1.ini <i class="conum" data-value="2"></i><b>(2)</b></code></pre> 
+         </div> 
+        </div> 
+        <div class="colist arabic"> 
+         <table> 
+          <tbody>
+           <tr> 
+            <td><i class="conum" data-value="1"></i><b>1</b></td> 
+            <td>happens to (coincidentally) be the <a href="http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html">same implementation</a> as Shiro\u2019s built-in $iniRealm</td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="2"></i><b>2</b></td> 
+            <td>in this case load the users/roles from the <code>src/main/resources/webapp/realm1.ini</code> file.</td> 
+           </tr> 
+          </tbody>
+         </table> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Note that a URL could be provided as the <code>resourcePath</code>, so a centralized config file could be used. Even so, the</p> 
+        </div> 
+        <div class="admonitionblock note"> 
+         <table> 
+          <tbody>
+           <tr> 
+            <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> 
+            <td class="content"> 
+             <div class="paragraph"> 
+              <p>If configured this way then the <code>[users]</code> and <code>[roles]</code> sections of <code>shiro.ini</code> become unused. Instead, the corresponding sections from for <code>realm1.ini</code> are used instead.</p> 
+             </div> </td> 
+           </tr> 
+          </tbody>
+         </table> 
+        </div> 
+       </div> 
+      </div> 
+     </div> 
+     <div class="sect1"> 
+      <h2 id="_ugsec_shiro-isis-ldap-realm">4. Isis Ldap Realm</h2>
+      <button type="button" class="button secondary" onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isis-ldap-realm.adoc&quot;" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i>&nbsp;Edit</button> 
+      <div class="sectionbody"> 
+       <div class="paragraph"> 
+        <p>Isis ships with an implementation of <a href="http://shiro.apache.org">Apache Shiro</a>'s <code>Realm</code> class that allows user authentication and authorization to be performed against an LDAP server.</p> 
+       </div> 
+       <div class="imageblock"> 
+        <div class="content"> 
+         <img src="images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG" alt="configure shiro to use isis ldap realm" width="600px"> 
+        </div> 
+       </div> 
+       <div class="paragraph"> 
+        <p>The LDAP database stores the user/passwords and user groups, while the <code>shiro.ini</code> file is used to map the LDAP groups to roles, and to map the roles to permissions.</p> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_shiro_configuration_2">4.1. Shiro Configuration</h3> 
+        <div class="paragraph"> 
+         <p>To use LDAP involves telling Shiro how to instantiate the realm. This bootstrapping info lives in the <code>WEB-INF/shiro.ini</code>:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
 contextFactory.url = ldap://localhost:10389
 contextFactory.systemUsername = uid=admin,ou=system        <i class="conum" data-value="1"></i><b>(1)</b>
 contextFactory.systemPassword = secret
@@ -1019,282 +922,283 @@ ldapRealm.permissionsByRole=\                              <i class="conum" data
    self-install_role = *:ToDoItemsFixturesService:install:* ; \
    admin_role = *
 
-securityManager.realms = $ldapRealm</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>user accounts are searched using a dedicated service account</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>SASL (CRAM-MD5) authentication is used for this authentication</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>Apache Isis' implementation of the LDAP realm.</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>groups are searched under <code>ou=groups,o=mojo</code> (where <code>mojo</code> is the company name)</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>each group has an LDAP objectClass of <code>groupOfUniqueNames</code></td>
-</tr>
-<tr>
-<td><i class="conum" data-value="6"></i><b>6</b></td>
-<td>each group has a vector attribute of <code>uniqueMember</code></td>
-</tr>
-<tr>
-<td><i class="conum" data-value="7"></i><b>7</b></td>
-<td>groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="8"></i><b>8</b></td>
-<td>roles are mapped in turn to permissions</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>The value of <code>uniqueMember</code> is in the form <code>uid=xxx</code>, with <code>xxx</code> being the uid of the user
-* users searched under <code>ou=system</code>
-* users have, at minimum, a <code>uid</code> attribute and a password
-* the users credentials are used to verify their user/password</p>
-</div>
-<div class="paragraph">
-<p>The above configuration has been tested against <a href="http://directory.apache.org/apacheds/">ApacheDS</a>, v1.5.7. This can be administered using <a href="http://directory.apache.org/studio/">Apache Directory Studio</a>, v1.5.3.</p>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-<div class="title">Shiro Realm Mappings</div>
-<div class="paragraph">
-<p>When configuring role based permission mapping, there can only be one of these entries per realm:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">realm.groupToRolesMappings = ...</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>and</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">realm.roleToPermissionsMappings = ...</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This forces you to put everything on one line for each of the above.  This is, unfortunately, a Shiro "feature".  And if you repeat the entries above then it&#8217;s "last one wins".)</p>
-</div>
-<div class="paragraph">
-<p>To make the configuration maintainable, use "\" to separate the mappings onto separate lines in the file.  Use this technique for both group to roles mapping and role to permission mapping. If you use the '&#39; after the "," that separates the key:value pairs it is more readable.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_externalizing_role_perms">4.2. Externalizing role perms</h3>
-<div class="paragraph">
-<p>As an alternative to injecting the <code>permissionsByRole</code> property, the role/permission mapping can alternatively be specified by injecting a resource path:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">ldapRealm.resourcePath=classpath:webapp/myroles.ini</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>where <code>myroles.ini</code> is in <code>src/main/resources/webapp</code>, and takes the form:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">[roles]
+securityManager.realms = $ldapRealm</code></pre> 
+         </div> 
+        </div> 
+        <div class="colist arabic"> 
+         <table> 
+          <tbody>
+           <tr> 
+            <td><i class="conum" data-value="1"></i><b>1</b></td> 
+            <td>user accounts are searched using a dedicated service account</td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="2"></i><b>2</b></td> 
+            <td>SASL (CRAM-MD5) authentication is used for this authentication</td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="3"></i><b>3</b></td> 
+            <td>Apache Isis' implementation of the LDAP realm.</td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="4"></i><b>4</b></td> 
+            <td>groups are searched under <code>ou=groups,o=mojo</code> (where <code>mojo</code> is the company name)</td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="5"></i><b>5</b></td> 
+            <td>each group has an LDAP objectClass of <code>groupOfUniqueNames</code></td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="6"></i><b>6</b></td> 
+            <td>each group has a vector attribute of <code>uniqueMember</code></td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="7"></i><b>7</b></td> 
+            <td>groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly</td> 
+           </tr> 
+           <tr> 
+            <td><i class="conum" data-value="8"></i><b>8</b></td> 
+            <td>roles are mapped in turn to permissions</td> 
+           </tr> 
+          </tbody>
+         </table> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The value of <code>uniqueMember</code> is in the form <code>uid=xxx</code>, with <code>xxx</code> being the uid of the user * users searched under <code>ou=system</code> * users have, at minimum, a <code>uid</code> attribute and a password * the users credentials are used to verify their user/password</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The above configuration has been tested against <a href="http://directory.apache.org/apacheds/">ApacheDS</a>, v1.5.7. This can be administered using <a href="http://directory.apache.org/studio/">Apache Directory Studio</a>, v1.5.3.</p> 
+        </div> 
+        <div class="admonitionblock tip"> 
+         <table> 
+          <tbody>
+           <tr> 
+            <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> 
+            <td class="content"> 
+             <div class="title">
+              Shiro Realm Mappings
+             </div> 
+             <div class="paragraph"> 
+              <p>When configuring role based permission mapping, there can only be one of these entries per realm:</p> 
+             </div> 
+             <div class="listingblock"> 
+              <div class="content"> 
+               <pre class="CodeRay highlight"><code data-lang="ini">realm.groupToRolesMappings = ...</code></pre> 
+              </div> 
+             </div> 
+             <div class="paragraph"> 
+              <p>and</p> 
+             </div> 
+             <div class="listingblock"> 
+              <div class="content"> 
+               <pre class="CodeRay highlight"><code data-lang="ini">realm.roleToPermissionsMappings = ...</code></pre> 
+              </div> 
+             </div> 
+             <div class="paragraph"> 
+              <p>This forces you to put everything on one line for each of the above. This is, unfortunately, a Shiro "feature". And if you repeat the entries above then it\u2019s "last one wins".)</p> 
+             </div> 
+             <div class="paragraph"> 
+              <p>To make the configuration maintainable, use "\" to separate the mappings onto separate lines in the file. Use this technique for both group to roles mapping and role to permission mapping. If you use the '' after the "," that separates the key:value pairs it is more readable.</p> 
+             </div> </td> 
+           </tr> 
+          </tbody>
+         </table> 
+        </div> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_externalizing_role_perms">4.2. Externalizing role perms</h3> 
+        <div class="paragraph"> 
+         <p>As an alternative to injecting the <code>permissionsByRole</code> property, the role/permission mapping can alternatively be specified by injecting a resource path:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">ldapRealm.resourcePath=classpath:webapp/myroles.ini</code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>where <code>myroles.ini</code> is in <code>src/main/resources/webapp</code>, and takes the form:</p> 
+        </div> 
+        <div class="listingblock"> 
+         <div class="content"> 
+          <pre class="CodeRay highlight"><code data-lang="ini">[roles]
 user_role = *:ToDoItemsJdo:*:*,\
             *:ToDoItem:*:*
 self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_active_ds_ldap_tutorial">4.3. Active DS LDAP tutorial</h3>
-<div class="paragraph">
-<p>The screenshots below show how to setup LDAP accounts in ApacheDS using the Apache Directory Studio.</p>
-</div>
-<div class="paragraph">
-<p>The setup here was initially based on <a href="http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html">this tutorial</a>, however we have moved the user accounts so that they are defined in a separate LDAP node.</p>
-</div>
-<div class="paragraph">
-<p>To start, create a partition in order to hold the mojo node (holding the groups):</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images//configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png" alt="ActiveDS LDAP Users">
-</div>
-</div>
-<div class="paragraph">
-<p>Create the <code>ou=groups,o=mojo</code> hierarchy:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images//configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png" alt="ActiveDS LDAP Users">
-</div>
-</div>
-<div class="paragraph">
-<p>Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Apache Isis connecting to LDAP using these credentials:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images//configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png" alt="ActiveDS LDAP Users">
-</div>
-</div>
-<div class="paragraph">
-<p>In order for SASL to work, it seems to be necessary to put users under <code>o=system</code>. (This is why the setup is slightly different than the tutorial mentioned above):</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images//configuration/configuring-shiro/ldap/activeds-ldap-users.png" alt="ActiveDS LDAP Users">
-</div>
-</div>
-<div class="paragraph">
-<p>Configure the users into the groups:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images//configuration/configuring-shiro/ldap/activeds-ldap-groups.png" alt="ActiveDS LDAP Users">
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugsec_shiro-isisaddons-security-module-realm">5. Security Module Realm</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The <a href="https://github.com/isisaddons/isis-module-security">Isis Addons' security module</a> (not ASF) provides a complete
-security subdomain for users, roles, permissions; all are persisted as domain entities.</p>
-</div>
-<div class="paragraph">
-<p>What that means, of course, that they can also be administered through your Isis application.  Moreover, the set of permissions (to features) is derived completely from your application&#8217;s metamodel; in essence the permissions are "type-safe".</p>
-</div>
-<div class="paragraph">
-<p>In order to play along, the module includes a Shiro realm, which fits in as follows:</p>
-</div>
-<div class="paragraph">
-<p>The general configuration is as follows:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG" alt="configure shiro to use isisaddons security module realm" width="600px">
-</div>
-</div>
-<div class="paragraph">
-<p>where the <code>IsisModuleSecurityRealm</code> realm is the implementation provided by the module.</p>
-</div>
-<div class="paragraph">
-<p>In the configuration above user passwords are stored in the database.  The module uses <a href="http://www.mindrot.org/projects/jBCrypt/">jBCrypt</a> so that passwords are only stored in a (one-way) encrypted form in the database.</p>
-</div>
-<div class="paragraph">
-<p>The security module also supports a slightly more sophisticated configuration.  Most organizations use LDAP for user credentials, and maintaining two separate user accounts would be less than ideal.  The <code>IsisModuleSecurityRealm</code> can therefore be configured with a subsidiary "delegate" realm that is responsible for performing the primary authentication of the user; if that passes then a user is created (as a domain entity) automatically.
-In most cases this delegate realm will be the LDAP realm, and so the architecture becomes:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG" alt="configure shiro to use isisaddons security module realm with delegate realm" width="600px">
-</div>
-</div>
-<div class="paragraph">
-<p>The security module has many more features than are described here, all of which are described in the module&#8217;s <a href="https://github.com/isisaddons/isis-module-security">README</a>.  The README also explains in detail how to configure an existing app to use this module.</p>
-</div>
-<div class="paragraph">
-<p>You can also look at the Isisaddons <a href="https://github.com/isisaddons/isis-app-todoapp">todoapp example</a> (not ASF), which is preconfigured to use the security module.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugsec_shiro-jdbc-realm">6. Shiro JDBC Realm</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>There is nothing to stop you from using some other <code>Realm</code> implementation (or indeed writing one yourself).  For example, you could use Shiro&#8217;s own JDBC realm that loads user/password details from a database.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>If you are happy to use a database then we strongly recommend you use the <a href="http://github.com/isisaddons/isis-module-security">Isis addons' security</a> module instead of a vanilla JDBC; it is far more sophisticated and moreover gives you the ability to administer the system from within your Isis application.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>If you go down this route, then the architecture is as follows:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png" alt="configure shiro to use custom jdbc realm" width="600px">
-</div>
-</div>
-<div class="paragraph">
-<p>There&#8217;s quite a lot of configuration required (in <code>WEB-INF/shiro.ini</code>) to set up a JDBC realm, so we&#8217;ll break it out into sections.</p>
-</div>
-<div class="paragraph">
-<p>First, we need to set up the connection to JDBC:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm        <i class="conum" data-value="1"></i><b>(1)</b>
+admin_role = *</code></pre> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)</p> 
+        </div> 
+       </div> 
+       <div class="sect2"> 
+        <h3 id="_active_ds_ldap_tutorial">4.3. Active DS LDAP tutorial</h3> 
+        <div class="paragraph"> 
+         <p>The screenshots below show how to setup LDAP accounts in ApacheDS using the Apache Directory Studio.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The setup here was initially based on <a href="http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html">this tutorial</a>, however we have moved the user accounts so that they are defined in a separate LDAP node.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>To start, create a partition in order to hold the mojo node (holding the groups):</p> 
+        </div> 
+        <div class="imageblock"> 
+         <div class="content"> 
+          <img src="images//configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png" alt="ActiveDS LDAP Users"> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Create the <code>ou=groups,o=mojo</code> hierarchy:</p> 
+        </div> 
+        <div class="imageblock"> 
+         <div class="content"> 
+          <img src="images//configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png" alt="ActiveDS LDAP Users"> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Apache Isis connecting to LDAP using these credentials:</p> 
+        </div> 
+        <div class="imageblock"> 
+         <div class="content"> 
+          <img src="images//configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png" alt="ActiveDS LDAP Users"> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>In order for SASL to work, it seems to be necessary to put users under <code>o=system</code>. (This is why the setup is slightly different than the tutorial mentioned above):</p> 
+        </div> 
+        <div class="imageblock"> 
+         <div class="content"> 
+          <img src="images//configuration/configuring-shiro/ldap/activeds-ldap-users.png" alt="ActiveDS LDAP Users"> 
+         </div> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Configure the users into the groups:</p> 
+        </div> 
+        <div class="imageblock"> 
+         <div class="content"> 
+          <img src="images//configuration/configuring-shiro/ldap/activeds-ldap-groups.png" alt="ActiveDS LDAP Users"> 
+         </div> 
+        </div> 
+       </div> 
+      </div> 
+     </div> 
+     <div class="sect1"> 
+      <h2 id="_ugsec_shiro-isisaddons-security-module-realm">5. Security Module Realm</h2>
+      <button type="button" class="button secondary" onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-isisaddons-security-module-realm.adoc&quot;" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i>&nbsp;Edit</button> 
+      <div class="sectionbody"> 
+       <div class="paragraph"> 
+        <p>The <a href="https://github.com/isisaddons/isis-module-security">Isis Addons' security module</a> (not ASF) provides a complete security subdomain for users, roles, permissions; all are persisted as domain entities.</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>What that means, of course, that they can also be administered through your Isis application. Moreover, the set of permissions (to features) is derived completely from your application\u2019s metamodel; in essence the permissions are "type-safe".</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>In order to play along, the module includes a Shiro realm, which fits in as follows:</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>The general configuration is as follows:</p> 
+       </div> 
+       <div class="imageblock"> 
+        <div class="content"> 
+         <img src="images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG" alt="configure shiro to use isisaddons security module realm" width="600px"> 
+        </div> 
+       </div> 
+       <div class="paragraph"> 
+        <p>where the <code>IsisModuleSecurityRealm</code> realm is the implementation provided by the module.</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>In the configuration above user passwords are stored in the database. The module uses <a href="http://www.mindrot.org/projects/jBCrypt/">jBCrypt</a> so that passwords are only stored in a (one-way) encrypted form in the database.</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>The security module also supports a slightly more sophisticated configuration. Most organizations use LDAP for user credentials, and maintaining two separate user accounts would be less than ideal. The <code>IsisModuleSecurityRealm</code> can therefore be configured with a subsidiary "delegate" realm that is responsible for performing the primary authentication of the user; if that passes then a user is created (as a domain entity) automatically. In most cases this delegate realm will be the LDAP realm, and so the architecture becomes:</p> 
+       </div> 
+       <div class="imageblock"> 
+        <div class="content"> 
+         <img src="images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG" alt="configure shiro to use isisaddons security module realm with delegate realm" width="600px"> 
+        </div> 
+       </div> 
+       <div class="paragraph"> 
+        <p>The security module has many more features than are described here, all of which are described in the module\u2019s <a href="https://github.com/isisaddons/isis-module-security">README</a>. The README also explains in detail how to configure an existing app to use this module.</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>You can also look at the Isisaddons <a href="https://github.com/isisaddons/isis-app-todoapp">todoapp example</a> (not ASF), which is preconfigured to use the security module.</p> 
+       </div> 
+      </div> 
+     </div> 
+     <div class="sect1"> 
+      <h2 id="_ugsec_shiro-jdbc-realm">6. Shiro JDBC Realm</h2>
+      <button type="button" class="button secondary" onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-jdbc-realm.adoc&quot;" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i>&nbsp;Edit</button> 
+      <div class="sectionbody"> 
+       <div class="paragraph"> 
+        <p>There is nothing to stop you from using some other <code>Realm</code> implementation (or indeed writing one yourself). For example, you could use Shiro\u2019s own JDBC realm that loads user/password details from a database.</p> 
+       </div> 
+       <div class="admonitionblock warning"> 
+        <table> 
+         <tbody>
+          <tr> 
+           <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> 
+           <td class="content"> 
+            <div class="paragraph"> 
+             <p>If you are happy to use a database then we strongly recommend you use the <a href="http://github.com/isisaddons/isis-module-security">Isis addons' security</a> module instead of a vanilla JDBC; it is far more sophisticated and moreover gives you the ability to administer the system from within your Isis application.</p> 
+            </div> </td> 
+          </tr> 
+         </tbody>
+        </table> 
+       </div> 
+       <div class="paragraph"> 
+        <p>If you go down this route, then the architecture is as follows:</p> 
+       </div> 
+       <div class="imageblock"> 
+        <div class="content"> 
+         <img src="images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png" alt="configure shiro to use custom jdbc realm" width="600px"> 
+        </div> 
+       </div> 
+       <div class="paragraph"> 
+        <p>There\u2019s quite a lot of configuration required (in <code>WEB-INF/shiro.ini</code>) to set up a JDBC realm, so we\u2019ll break it out into sections.</p> 
+       </div> 
+       <div class="paragraph"> 
+        <p>First, we need to set up the connection to JDBC:</p> 
+       </div> 
+       <div class="listingblock"> 
+        <div class="content"> 
+         <pre class="CodeRay highlight"><code data-lang="ini">jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm        <i class="conum" data-value="1"></i><b>(1)</b>
 
 jof = org.apache.shiro.jndi.JndiObjectFactory          <i class="conum" data-value="2"></i><b>(2)</b>
 jof.resourceName = jdbc/postgres                       <i class="conum" data-value="3"></i><b>(3)</b>
 jof.requiredType = javax.sql.DataSource
 jof.resourceRef = true
 
-jdbcRealm.dataSource = $jof                            <i class="conum" data-value="4"></i><b>(4)</b></code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>instantiate the JDBC realm</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>instantiate factory object to lookup DataSource from servlet container</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>name of the datasource (as configured in <code>web.xml</code>)</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>instruct JDBC realm to obtain datasource from the JNDI</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>We next need to tell the realm how to query the database.  Shiro supports any schema; what matters is the input search argument and the output results.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">jdbcRealm.authenticationQuery =         \              <i class="conum" data-value="1"></i><b>(1)</b>
+jdbcRealm.dataSource = $jof                            <i class="conum" data-value="4"></i><b>(4)</b></code></pre> 
+        </div> 
+       </div> 
+       <div class="colist arabic"> 
+        <table> 
+         <tbody>
+          <tr> 
+           <td><i class="conum" data-value="1"></i><b>1</b></td> 
+           <td>instantiate the JDBC realm</td> 
+          </tr> 
+          <tr> 
+           <td><i class="conum" data-value="2"></i><b>2</b></td> 
+           <td>instantiate factory object to lookup DataSource from servlet container</td> 
+          </tr> 
+          <tr> 
+           <td><i class="conum" data-value="3"></i><b>3</b></td> 
+           <td>name of the datasource (as configured in <code>web.xml</code>)</td> 
+          </tr> 
+          <tr> 
+           <td><i class="conum" data-value="4"></i><b>4</b></td> 
+           <td>instruct JDBC realm to obtain datasource from the JNDI</td> 
+          </tr> 
+         </tbody>
+        </table> 
+       </div> 
+       <div class="paragraph"> 
+        <p>We next need to tell the realm how to query the database. Shiro supports any schema; what matters is the input search argument and the output results.</p> 
+       </div> 
+       <div class="listingblock"> 
+        <div class="content"> 
+         <pre class="CodeRay highlight"><code data-lang="ini">jdbcRealm.authenticationQuery =         \              <i class="conum" data-value="1"></i><b>(1)</b>
         select password                 \
           from users                    \
          where username = ?
@@ -1319,408 +1223,385 @@ jdbcRealm.permissionsQuery=             \               <i class="conum" data-va
              from roles                 \
             where label = ?);
 
-jdbcRealm.permissionsLookupEnabled=true                 <i class="conum" data-value="4"></i><b>(4)</b></code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>query to find password for user</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>query to find roles for user</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>query to find permissions for role</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>enable permissions lookup</td>
-</tr>
-</table>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>The <code>permissionsLookupEnabled</code> is very important, otherwise Shiro just returns an empty list of permissions and your users will have no access to any features(!).</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>We also should ensure that the passwords are not stored as plain-text:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">dps = org.apache.shiro.authc.credential.DefaultPasswordService   <i class="conum" data-value="1"></i><b>(1)</b>
+jdbcRealm.permissionsLookupEnabled=true                 <i class="conum" data-value="4"></i><b>(4)</b></code></pre> 
+        </div> 
+       </div> 
+       <div class="colist arabic"> 
+        <table> 
+         <tbody>
+          <tr> 
+           <td><i class="conum" data-value="1"></i><b>1</b></td> 
+           <td>query to find password for user</td> 
+          </tr> 
+          <tr> 
+           <td><i class="conum" data-value="2"></i><b>2</b></td> 
+           <td>query to find roles for user</td> 
+          </tr> 
+          <tr> 
+           <td><i class="conum" data-value="3"></i><b>3</b></td> 
+           <td>query to find permissions for role</td> 
+          </tr> 
+          <tr> 
+           <td><i class="conum" data-value="4"></i><b>4</b></td> 
+           <td>enable permissions lookup</td> 
+          </tr> 
+         </tbody>
+        </table> 
+       </div> 
+       <div class="admonitionblock warning"> 
+        <table> 
+         <tbody>
+          <tr> 
+           <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> 
+           <td class="content"> 
+            <div class="paragraph"> 
+             <p>The <code>permissionsLookupEnabled</code> is very important, otherwise Shiro just returns an empty list of permissions and your users will have no access to any features(!).</p> 
+            </div> </td> 
+          </tr> 
+         </tbody>
+        </table> 
+       </div> 
+       <div class="paragraph"> 
+        <p>We also should ensure that the passwords are not stored as plain-text:</p> 
+       </div> 
+       <div class="listingblock"> 
+        <div class="content"> 
+         <pre class="CodeRay highlight"><code data-lang="ini">dps = org.apache.shiro.authc.credential.DefaultPasswordService   <i class="conum" data-value="1"></i><b>(1)</b>
 pm = org.apache.shiro.authc.credential.PasswordMatcher           <i class="conum" data-value="2"></i><b>(2)</b>
 pm.passwordService = $dps
-jdbcRealm.credentialsMatcher = $pm                               <i class="conum" data-value="3"></i><b>(3)</b></code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>mechanism to encrypts password</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>service to match passwords</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>instruct JDBC realm to use password matching service when authenticating</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>And finally we need to tell Shiro to use the realm, in the usual fashion:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">securityManager.realms = $jdbcRealm</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Using the above configuration you will also need to setup a <code>DataSource</code>.  The details vary by servlet container, for example this is <a href="https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html">how to do the setup on Tomcat 8.0</a>.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>The name of the <code>DataSource</code> can also vary by servlet container; see for example <a href="http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702">this StackOverflow answer</a>.</p>
-</div>
-</td>
-</tr>
-</tab

<TRUNCATED>