ISIS-1521: reorganizes security chapters/sections

Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/45db638e
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/45db638e
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/45db638e

Branch: refs/heads/wip
Commit: 45db638ed1073af73ee49082a5c268d3f058b86f
Parents: bef8814
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Fri Apr 14 16:31:59 2017 +0100
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/dg/_dg_asciidoc-templates.adoc       |   4 +-
 .../asciidoc/guides/dg/_dg_hints-and-tips.adoc  |   2 +-
 .../guides/ugbtb/_ugbtb_hints-and-tips.adoc     |   2 +-
 .../guides/ugodn/_ugodn_hints-and-tips.adoc     |   2 +-
 .../guides/ugsec/_ugsec_hints-and-tips.adoc     |   3 +-
 .../_ugsec_hints-and-tips_shiro-caching.adoc    |  41 ++++++
 .../guides/ugsec/_ugsec_shiro-caching.adoc      |  41 ------
 .../guides/ugsec/_ugsec_shiro-ini-realm.adoc    | 133 -----------------
 ...shiro-isis-enhanced-wildcard-permission.adoc |   2 +-
 .../ugsec/_ugsec_shiro-isis-ldap-realm.adoc     | 146 -------------------
 ..._shiro-isisaddons-security-module-realm.adoc |  36 -----
 .../guides/ugsec/_ugsec_shiro-jdbc-realm.adoc   | 113 --------------
 .../_ugsec_shiro-realm-implementations.adoc     |  15 ++
 ...c_shiro-realm-implementations_ini-realm.adoc | 133 +++++++++++++++++
 ...o-realm-implementations_isis-ldap-realm.adoc | 146 +++++++++++++++++++
 ...ations_isisaddons-security-module-realm.adoc |  36 +++++
 ..._shiro-realm-implementations_jdbc-realm.adoc | 113 ++++++++++++++
 .../src/main/asciidoc/guides/ugsec/ugsec.adoc   |   6 +-
 .../guides/ugvro/_ugvro_hints-and-tips.adoc     |   2 +-
 .../guides/ugvw/_ugvw_hints-and-tips.adoc       |   2 +-
 20 files changed, 495 insertions(+), 483 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
index 8ccd418..44b6549 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
@@ -349,9 +349,9 @@ A hyperlink to a bookmark within the Secrurity guide, where:
 
 for example:
 
-`\xref:../ugsec/ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro 
Features]`
+`\xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips_shiro-caching[Caching and 
other Shiro Features]`
 
-|xref:../ugsec/ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro 
Features]
+|xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips_shiro-caching[Caching and 
other Shiro Features]
 
 
 |`adugtst`

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
index 094550e..f0ed4c6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -10,7 +10,7 @@ This chapter provides some solutions for problems we've 
encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide (this chapter)
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide (this chapter)
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
index 2c78959..51c76f0 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -10,7 +10,7 @@ This chapter provides some solutions for problems we've 
encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index 39ca25c..61806ac 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -9,7 +9,7 @@ This chapter provides some solutions for problems we've 
encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
index 97ccf36..71cef6b 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
@@ -11,7 +11,7 @@ This chapter provides some solutions for problems we've 
encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 
@@ -26,3 +26,4 @@ See also hints-n-tips chapters in the:
 
 
 
include::_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
+include::_ugsec_hints-and-tips_shiro-caching.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc
new file mode 100644
index 0000000..190a26c
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc
@@ -0,0 +1,41 @@
+[[_ugsec_hints-and-tips_shiro-caching]]
+= Caching and other Shiro Features
+:Notice: 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+We don't want to repeat the entire 
link:http://shiro.apache.org/documentation.html[Shiro documentation set] here, 
but we should flag a number of otherof other features that are worth checking 
out.
+
+
+
+
+== Caching
+
+To ensure that security operations does not impede performance, Shiro supports 
caching.  For example, this sets up a simple memory-based cache manager:
+
+[source,ini]
+----
+memoryCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
+securityManager.cacheManager = $memoryCacheManager
+----
+
+Other implementations can be plugged in; see the Shiro 
link:http://shiro.apache.org/caching.html[documentation] for further details.
+
+
+
+
+== Further Reading
+
+
+* Shiro's documentation page can be found 
link:http://shiro.apache.org/documentation.html[here].
+
+* community-contributed articles can be found 
link:http://shiro.apache.org/articles.html[here]. +
++
+These include for instance 
link:http://meri-stuff.blogspot.co.uk/2011/04/apache-shiro-part-2-realms-database-and.html[this
 interesting article] describing how to perform certificate-based 
authentication (ie login using Google or Facebook credentials).
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc
deleted file mode 100644
index c97fa72..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugsec_shiro-caching]]
-= Caching and other Shiro Features
-:Notice: 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.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-We don't want to repeat the entire 
link:http://shiro.apache.org/documentation.html[Shiro documentation set] here, 
but we should flag a number of otherof other features that are worth checking 
out.
-
-
-
-
-== Caching
-
-To ensure that security operations does not impede performance, Shiro supports 
caching.  For example, this sets up a simple memory-based cache manager:
-
-[source,ini]
-----
-memoryCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
-securityManager.cacheManager = $memoryCacheManager
-----
-
-Other implementations can be plugged in; see the Shiro 
link:http://shiro.apache.org/caching.html[documentation] for further details.
-
-
-
-
-== Further Reading
-
-
-* Shiro's documentation page can be found 
link:http://shiro.apache.org/documentation.html[here].
-
-* community-contributed articles can be found 
link:http://shiro.apache.org/articles.html[here]. +
-+
-These include for instance 
link:http://meri-stuff.blogspot.co.uk/2011/04/apache-shiro-part-2-realms-database-and.html[this
 interesting article] describing how to perform certificate-based 
authentication (ie login using Google or Facebook credentials).
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
deleted file mode 100644
index 3e3ce94..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
+++ /dev/null
@@ -1,133 +0,0 @@
-[[_ugsec_shiro-ini-realm]]
-= Shiro Ini Realm
-:Notice: 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.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads 
from the (same) `WEB-INF/shiro.ini` file.
-
-This is suitable for prototyping, but isn't intended for production use, if 
only because user/password credentials are stored in plain text.  Nevertheless, 
it's a good starting point.  The app generated by the 
xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp 
archetype] is configured to use this realm.
-
-The diagram below shows the Isis and components involved:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG[width="600px"]
-
-The realm is responsible for validating the user credentials, and then creates 
a Shiro 
link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`]
 which represents the user (for the current request).  Apache Isis 
`Authenticator` component then interacts with the `Subject` in order to check 
permissions.
-
-
-
-
-== Shiro Configuration
-
-To use the built-in `IniRealm`, we add the following to `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-securityManager.realms = $iniRealm
-----
-
-(Unlike other realms) there is no need to "define" `$iniRealm`; it is 
automatically available to us.
-
-Specifying `$iniRealm` means that the usernames/passwords, roles and 
permissions are read from the `shiro.ini` file itself.  Specifically:
-
-* the users/passwords and their roles from the `[users]` sections;
-* the roles are mapped to permissions in the `[roles]` section.
-
-The format of these is described below.
-
-=== `[users]` section
-
-This section lists users, passwords and their roles.
-
-For example:
-
-[source,ini]
-----
-sven = pass, admin_role
-dick = pass, user_role, analysis_role, self-install_role
-bob  = pass, user_role, self-install_role
-----
-The first value is the password (eg "pass", the remaining values are the 
role(s).
-
-
-=== `[roles]` section
-
-This section lists roles and their corresponding permissions.
-
-For example:
-
-[source,ini]
-----
-user_role = *:ToDoItems:*:*,\
-            *:ToDoItem:*:*,\
-            *:ToDoAppDashboard:*:*
-analysis_role = *:ToDoItemAnalysis:*:*,\
-            *:ToDoItemsByCategoryViewModel:*:*,\
-            *:ToDoItemsByDateRangeViewModel:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-The value is a comma-separated list of permissions for the role.  The format 
is:
-
-[source,ini]
-----
-packageName:className:memberName:r,w
-----
-
-where:
-
-* `memberName` is the property, collection or action name.
-* `r` indicates that the member is visible
-* `w` indicates that the member is usable (editable or invokable)
-
-and where each of the parts of the permission string can be wildcarded using 
`*`.
-
-Because these are wildcards, a '*' can be used at any level. Additionally, 
missing levels assume wildcards.
-
-Thus:
-
-[source,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
-com.mycompany.myapp:Customer:*:r             # view all customer class members
-com.mycompany.myapp:*:*:r                    # view-only access for all 
classes in myapp package
-com.mycompany.myapp:*:*:*                    # view/edit for all classes in 
myapp package
-com.mycompany.myapp:*:*                      # ditto
-com.mycompany.myapp:*                        # ditto
-com.mycompany.myapp                          # ditto
-*                                            # view/edit access to everything
-----
-
-[TIP]
-====
-The format of the permissions string is configurable in Shiro, and Apache Isis 
uses this to provide an extended wildcard format, described 
xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-enhanced-wildcard-permission[here].
-====
-
-
-
-
-== Externalized IniRealm
-
-There's no requirement for all users/roles to be defined in the `shiro.ini` 
file.  Instead, a realm can be defined that loads its users/roles from some 
other resource.
-
-For example:
-
-[source,ini]
-----
-$realm1=org.apache.shiro.realm.text.IniRealm # <1>
-realm1.resourcePath=classpath:webapp/realm1.ini # <2>
-----
-<1> happens to (coincidentally) be the 
link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same
 implementation] as Shiro's built-in $iniRealm
-<2> in this case load the users/roles from the 
`src/main/resources/webapp/realm1.ini` file.
-
-Note that a URL could be provided as the `resourcePath`, so a centralized 
config file could be used.  Even so, the
-
-[NOTE]
-====
-If configured this way then the `[users]` and `[roles]` sections of 
`shiro.ini` become unused. Instead, the corresponding sections from for 
`realm1.ini` are used instead.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
index 241a297..82b1b5d 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-If using the text-based 
xref:../ugsec/ugsec.adoc#_ugsec_shiro-ini-realm[`IniRealm`] or 
xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-ldap-realm[Isis' LDAP realm], then 
note that Shiro also allows the string representation of the permissions to be 
mapped (resolved) to alternative `Permission` instances.  Apache Isis provides 
its own `IsisPermission` which introduces the concept of a "veto".
+If using the text-based 
xref:../ugsec/ugsec.adoc#_ugsec_shiro-realm-implementations_ini-realm[`IniRealm`]
 or 
xref:../ugsec/ugsec.adoc#_ugsec_shiro-realm-implementations_isis-ldap-realm[Isis'
 LDAP realm], then note that Shiro also allows the string representation of the 
permissions to be mapped (resolved) to alternative `Permission` instances.  
Apache Isis provides its own `IsisPermission` which introduces the concept of a 
"veto".
 
 A vetoing permission is one that prevents access to a feature, rather than 
grants it.  This is useful in some situations where most users have access to 
most features, and only a small number of features are particularly sensitive.  
The configuration can therefore be set up to grant fairly broad-brush 
permissions and then veto permission for the sensitive features for those users 
that do not have access.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc
deleted file mode 100644
index c2a2ec6..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc
+++ /dev/null
@@ -1,146 +0,0 @@
-[[_ugsec_shiro-isis-ldap-realm]]
-= Isis Ldap Realm
-:Notice: 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.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-Isis ships with an implementation of http://shiro.apache.org[Apache Shiro]'s 
`Realm` class that allows user authentication and authorization to be performed 
against an LDAP server.
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG[width="600px"]
-
-The LDAP database stores the user/passwords and user groups, while the 
`shiro.ini` file is used to map the LDAP groups to roles, and to map the roles 
to permissions.
-
-== Shiro Configuration
-
-To use LDAP involves telling Shiro how to instantiate the realm.  This 
bootstrapping info lives in the `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
-contextFactory.url = ldap://localhost:10389
-contextFactory.systemUsername = uid=admin,ou=system        # <1>
-contextFactory.systemPassword = secret
-contextFactory.authenticationMechanism = CRAM-MD5          # <2>
-contextFactory.systemAuthenticationMechanism = simple
-
-ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm   # <3>
-ldapRealm.contextFactory = $contextFactory
-
-ldapRealm.searchBase = ou=groups,o=mojo                    # <4>
-ldapRealm.groupObjectClass = groupOfUniqueNames            # <5>
-ldapRealm.uniqueMemberAttribute = uniqueMember             # <6>
-ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
-
-# optional mapping from physical groups to logical application roles
-ldapRealm.rolesByGroup = \                                 # <7>
-    LDN_USERS: user_role,\
-    NYK_USERS: user_role,\
-    HKG_USERS: user_role,\
-    GLOBAL_ADMIN: admin_role,\
-    DEMOS: self-install_role
-
-ldapRealm.permissionsByRole=\                              # <8>
-   user_role = *:ToDoItemsJdo:*:*,\
-               *:ToDoItem:*:*; \
-   self-install_role = *:ToDoItemsFixturesService:install:* ; \
-   admin_role = *
-
-securityManager.realms = $ldapRealm
-----
-<1> user accounts are searched using a dedicated service account
-<2> SASL (CRAM-MD5) authentication is used for this authentication
-<3> Apache Isis' implementation of the LDAP realm.
-<4> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company 
name)
-<5> each group has an LDAP objectClass of `groupOfUniqueNames`
-<6> each group has a vector attribute of `uniqueMember`
-<7> groups looked up from LDAP can optionally be mapped to logical roles; 
otherwise groups are used as role names directly
-<8> roles are mapped in turn to permissions
-
-The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid 
of the user
-* users searched under `ou=system`
-* users have, at minimum, a `uid` attribute and a password
-* the users credentials are used to verify their user/password
-
-The above configuration has been tested against 
http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be 
administered using http://directory.apache.org/studio/[Apache Directory 
Studio], v1.5.3.
-
-
-[TIP]
-.Shiro Realm Mappings
-====
-When configuring role based permission mapping, there can only be one of these 
entries per realm:
-
-[source,ini]
-----
-realm.groupToRolesMappings = ...
-----
-
-and
-
-[source,ini]
-----
-realm.roleToPermissionsMappings = ...
-----
-
-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's "last one wins".)
-
-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.
-====
-
-
-
-
-
-
-== Externalizing role perms
-
-As an alternative to injecting the `permissionsByRole` property, the 
role/permission mapping can alternatively be specified by injecting a resource 
path:
-
-[source,ini]
-----
-ldapRealm.resourcePath=classpath:webapp/myroles.ini
-----
-
-where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
-
-[source,ini]
-----
-[roles]
-user_role = *:ToDoItemsJdo:*:*,\
-            *:ToDoItem:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-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)
-
-
-
-
-== Active DS LDAP tutorial
-
-The screenshots below show how to setup LDAP accounts in ApacheDS using the 
Apache Directory Studio.
-
-The setup here was initially based on 
http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this
 tutorial], however we have moved the user accounts so that they are defined in 
a separate LDAP node.
-
-To start, create a partition in order to hold the mojo node (holding the 
groups):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS
 LDAP Users]
-
-Create the `ou=groups,o=mojo` hierarchy:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS
 LDAP Users]
-
-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:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS
 LDAP Users]
-
-In order for SASL to work, it seems to be necessary to put users under 
`o=system`. (This is why the setup is slightly different than the tutorial 
mentioned above):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS
 LDAP Users]
-
-Configure the users into the groups:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS
 LDAP Users]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc
deleted file mode 100644
index e81a06a..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ugsec_shiro-isisaddons-security-module-realm]]
-= Security Module Realm
-:Notice: 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.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-The https://github.com/isisaddons/isis-module-security[Isis Addons' security 
module] (not ASF) provides a complete
-security subdomain for users, roles, permissions; all are persisted as domain 
entities.
-
-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's metamodel; in essence the permissions are 
"type-safe".  
-
-
-In order to play along, the module includes a Shiro realm, which fits in as 
follows:
-
-The general configuration is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG[width="600px"]
-
-where the `IsisModuleSecurityRealm` realm is the implementation provided by 
the module.
-
-In the configuration above user passwords are stored in the database.  The 
module uses link:http://www.mindrot.org/projects/jBCrypt/[jBCrypt] so that 
passwords are only stored in a (one-way) encrypted form in the database.
-
-
-
-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 `IsisModuleSecurityRealm` 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:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG[width="600px"]
-
-
-The security module has many more features than are described here, all of 
which are described in the module's 
link:https://github.com/isisaddons/isis-module-security[README].  The README 
also explains in detail how to configure an existing app to use this module.
-
-You can also look at the Isisaddons 
https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), 
which is preconfigured to use the security module.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc
deleted file mode 100644
index b16edf2..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ugsec_shiro-jdbc-realm]]
-= Shiro JDBC Realm
-:Notice: 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.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-There is nothing to stop you from using some other `Realm` implementation (or 
indeed writing one yourself).  For example, you could use Shiro's own JDBC 
realm that loads user/password details from a database.
-
-[WARNING]
-====
-If you are happy to use a database then we strongly recommend you use the 
http://github.com/isisaddons/isis-module-security[Isis addons' security] 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.
-====
-
-If you go down this route, then the architecture is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png[width="600px"]
-
-
-
-
-There's quite a lot of configuration required (in `WEB-INF/shiro.ini`) to set 
up a JDBC realm, so we'll break it out into sections.
-
-First, we need to set up the connection to JDBC:
-
-[source,ini]
-----
-jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm        # <1>
-
-jof = org.apache.shiro.jndi.JndiObjectFactory          # <2>
-jof.resourceName = jdbc/postgres                       # <3>
-jof.requiredType = javax.sql.DataSource
-jof.resourceRef = true
-
-jdbcRealm.dataSource = $jof                            # <4>
-----
-<1> instantiate the JDBC realm
-<2> instantiate factory object to lookup DataSource from servlet container
-<3> name of the datasource (as configured in `web.xml`)
-<4> instruct JDBC realm to obtain datasource from the JNDI
-
-
-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.
-
-[source,ini]
-----
-
-jdbcRealm.authenticationQuery =         \              # <1>
-        select password                 \
-          from users                    \
-         where username = ?
-
-jdbcRealm.userRolesQuery =              \              # <2>
-        select r.label                  \
-          from users_roles ur           \
-    inner join roles r                  \
-            on ur.role_id = r.id        \
-         where user_id = (              \
-            select id                   \
-             from users                 \
-            where username = ?);        \
-
-jdbcRealm.permissionsQuery=             \               # <3>
-        select p.permission             \
-          from roles_permissions rp     \
-    inner join permissions p            \
-            on rp.permission_id = p.id  \
-         where rp.role_id = (           \
-            select id                   \
-             from roles                 \
-            where label = ?);
-
-jdbcRealm.permissionsLookupEnabled=true                 # <4>
-----
-<1> query to find password for user
-<2> query to find roles for user
-<3> query to find permissions for role
-<4> enable permissions lookup
-
-[WARNING]
-====
-The `permissionsLookupEnabled` is very important, otherwise Shiro just returns 
an empty list of permissions and your users will have no access to any 
features(!).
-====
-
-We also should ensure that the passwords are not stored as plain-text:
-
-[source,ini]
-----
-dps = org.apache.shiro.authc.credential.DefaultPasswordService   # <1>
-pm = org.apache.shiro.authc.credential.PasswordMatcher           # <2>
-pm.passwordService = $dps
-jdbcRealm.credentialsMatcher = $pm                               # <3>
-----
-<1> mechanism to encrypts password
-<2> service to match passwords
-<3> instruct JDBC realm to use password matching service when authenticating
-
-
-And finally we need to tell Shiro to use the realm, in the usual fashion:
-
-[source,ini]
-----
-securityManager.realms = $jdbcRealm
-----
-
-Using the above configuration you will also need to setup a `DataSource`.  The 
details vary by servlet container, for example this is 
link:https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html[how
 to do the setup on Tomcat 8.0].
-
-[WARNING]
-====
-The name of the `DataSource` can also vary by servlet container; see for 
example 
link:http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702[this
 StackOverflow answer].
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc
new file mode 100644
index 0000000..df8b0a6
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc
@@ -0,0 +1,15 @@
+[[_ugsec_shiro-realm-implementations]]
+= Shiro Realm Implementations
+:Notice: 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+include::_ugsec_shiro-realm-implementations_ini-realm.adoc[leveloffset=+1]
+
+include::_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc[leveloffset=+1]
+
+include::_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc[leveloffset=+1]
+
+include::_ugsec_shiro-realm-implementations_jdbc-realm.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
new file mode 100644
index 0000000..d72defc
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
@@ -0,0 +1,133 @@
+[[_ugsec_shiro-realm-implementations_ini-realm]]
+= Shiro Ini Realm
+:Notice: 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads 
from the (same) `WEB-INF/shiro.ini` file.
+
+This is suitable for prototyping, but isn't intended for production use, if 
only because user/password credentials are stored in plain text.  Nevertheless, 
it's a good starting point.  The app generated by the 
xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp 
archetype] is configured to use this realm.
+
+The diagram below shows the Isis and components involved:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG[width="600px"]
+
+The realm is responsible for validating the user credentials, and then creates 
a Shiro 
link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`]
 which represents the user (for the current request).  Apache Isis 
`Authenticator` component then interacts with the `Subject` in order to check 
permissions.
+
+
+
+
+== Shiro Configuration
+
+To use the built-in `IniRealm`, we add the following to `WEB-INF/shiro.ini`:
+
+[source,ini]
+----
+securityManager.realms = $iniRealm
+----
+
+(Unlike other realms) there is no need to "define" `$iniRealm`; it is 
automatically available to us.
+
+Specifying `$iniRealm` means that the usernames/passwords, roles and 
permissions are read from the `shiro.ini` file itself.  Specifically:
+
+* the users/passwords and their roles from the `[users]` sections;
+* the roles are mapped to permissions in the `[roles]` section.
+
+The format of these is described below.
+
+=== `[users]` section
+
+This section lists users, passwords and their roles.
+
+For example:
+
+[source,ini]
+----
+sven = pass, admin_role
+dick = pass, user_role, analysis_role, self-install_role
+bob  = pass, user_role, self-install_role
+----
+The first value is the password (eg "pass", the remaining values are the 
role(s).
+
+
+=== `[roles]` section
+
+This section lists roles and their corresponding permissions.
+
+For example:
+
+[source,ini]
+----
+user_role = *:ToDoItems:*:*,\
+            *:ToDoItem:*:*,\
+            *:ToDoAppDashboard:*:*
+analysis_role = *:ToDoItemAnalysis:*:*,\
+            *:ToDoItemsByCategoryViewModel:*:*,\
+            *:ToDoItemsByDateRangeViewModel:*:*
+self-install_role = *:ToDoItemsFixturesService:install:*
+admin_role = *
+----
+
+The value is a comma-separated list of permissions for the role.  The format 
is:
+
+[source,ini]
+----
+packageName:className:memberName:r,w
+----
+
+where:
+
+* `memberName` is the property, collection or action name.
+* `r` indicates that the member is visible
+* `w` indicates that the member is usable (editable or invokable)
+
+and where each of the parts of the permission string can be wildcarded using 
`*`.
+
+Because these are wildcards, a '*' can be used at any level. Additionally, 
missing levels assume wildcards.
+
+Thus:
+
+[source,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
+com.mycompany.myapp:Customer:*:r             # view all customer class members
+com.mycompany.myapp:*:*:r                    # view-only access for all 
classes in myapp package
+com.mycompany.myapp:*:*:*                    # view/edit for all classes in 
myapp package
+com.mycompany.myapp:*:*                      # ditto
+com.mycompany.myapp:*                        # ditto
+com.mycompany.myapp                          # ditto
+*                                            # view/edit access to everything
+----
+
+[TIP]
+====
+The format of the permissions string is configurable in Shiro, and Apache Isis 
uses this to provide an extended wildcard format, described 
xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-enhanced-wildcard-permission[here].
+====
+
+
+
+
+== Externalized IniRealm
+
+There's no requirement for all users/roles to be defined in the `shiro.ini` 
file.  Instead, a realm can be defined that loads its users/roles from some 
other resource.
+
+For example:
+
+[source,ini]
+----
+$realm1=org.apache.shiro.realm.text.IniRealm # <1>
+realm1.resourcePath=classpath:webapp/realm1.ini # <2>
+----
+<1> happens to (coincidentally) be the 
link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same
 implementation] as Shiro's built-in $iniRealm
+<2> in this case load the users/roles from the 
`src/main/resources/webapp/realm1.ini` file.
+
+Note that a URL could be provided as the `resourcePath`, so a centralized 
config file could be used.  Even so, the
+
+[NOTE]
+====
+If configured this way then the `[users]` and `[roles]` sections of 
`shiro.ini` become unused. Instead, the corresponding sections from for 
`realm1.ini` are used instead.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc
new file mode 100644
index 0000000..5e5a805
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc
@@ -0,0 +1,146 @@
+[[_ugsec_shiro-realm-implementations_isis-ldap-realm]]
+= Isis Ldap Realm
+:Notice: 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Isis ships with an implementation of http://shiro.apache.org[Apache Shiro]'s 
`Realm` class that allows user authentication and authorization to be performed 
against an LDAP server.
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG[width="600px"]
+
+The LDAP database stores the user/passwords and user groups, while the 
`shiro.ini` file is used to map the LDAP groups to roles, and to map the roles 
to permissions.
+
+== Shiro Configuration
+
+To use LDAP involves telling Shiro how to instantiate the realm.  This 
bootstrapping info lives in the `WEB-INF/shiro.ini`:
+
+[source,ini]
+----
+contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
+contextFactory.url = ldap://localhost:10389
+contextFactory.systemUsername = uid=admin,ou=system        # <1>
+contextFactory.systemPassword = secret
+contextFactory.authenticationMechanism = CRAM-MD5          # <2>
+contextFactory.systemAuthenticationMechanism = simple
+
+ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm   # <3>
+ldapRealm.contextFactory = $contextFactory
+
+ldapRealm.searchBase = ou=groups,o=mojo                    # <4>
+ldapRealm.groupObjectClass = groupOfUniqueNames            # <5>
+ldapRealm.uniqueMemberAttribute = uniqueMember             # <6>
+ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
+
+# optional mapping from physical groups to logical application roles
+ldapRealm.rolesByGroup = \                                 # <7>
+    LDN_USERS: user_role,\
+    NYK_USERS: user_role,\
+    HKG_USERS: user_role,\
+    GLOBAL_ADMIN: admin_role,\
+    DEMOS: self-install_role
+
+ldapRealm.permissionsByRole=\                              # <8>
+   user_role = *:ToDoItemsJdo:*:*,\
+               *:ToDoItem:*:*; \
+   self-install_role = *:ToDoItemsFixturesService:install:* ; \
+   admin_role = *
+
+securityManager.realms = $ldapRealm
+----
+<1> user accounts are searched using a dedicated service account
+<2> SASL (CRAM-MD5) authentication is used for this authentication
+<3> Apache Isis' implementation of the LDAP realm.
+<4> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company 
name)
+<5> each group has an LDAP objectClass of `groupOfUniqueNames`
+<6> each group has a vector attribute of `uniqueMember`
+<7> groups looked up from LDAP can optionally be mapped to logical roles; 
otherwise groups are used as role names directly
+<8> roles are mapped in turn to permissions
+
+The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid 
of the user
+* users searched under `ou=system`
+* users have, at minimum, a `uid` attribute and a password
+* the users credentials are used to verify their user/password
+
+The above configuration has been tested against 
http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be 
administered using http://directory.apache.org/studio/[Apache Directory 
Studio], v1.5.3.
+
+
+[TIP]
+.Shiro Realm Mappings
+====
+When configuring role based permission mapping, there can only be one of these 
entries per realm:
+
+[source,ini]
+----
+realm.groupToRolesMappings = ...
+----
+
+and
+
+[source,ini]
+----
+realm.roleToPermissionsMappings = ...
+----
+
+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's "last one wins".)
+
+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.
+====
+
+
+
+
+
+
+== Externalizing role perms
+
+As an alternative to injecting the `permissionsByRole` property, the 
role/permission mapping can alternatively be specified by injecting a resource 
path:
+
+[source,ini]
+----
+ldapRealm.resourcePath=classpath:webapp/myroles.ini
+----
+
+where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
+
+[source,ini]
+----
+[roles]
+user_role = *:ToDoItemsJdo:*:*,\
+            *:ToDoItem:*:*
+self-install_role = *:ToDoItemsFixturesService:install:*
+admin_role = *
+----
+
+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)
+
+
+
+
+== Active DS LDAP tutorial
+
+The screenshots below show how to setup LDAP accounts in ApacheDS using the 
Apache Directory Studio.
+
+The setup here was initially based on 
http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this
 tutorial], however we have moved the user accounts so that they are defined in 
a separate LDAP node.
+
+To start, create a partition in order to hold the mojo node (holding the 
groups):
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS
 LDAP Users]
+
+Create the `ou=groups,o=mojo` hierarchy:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS
 LDAP Users]
+
+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:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS
 LDAP Users]
+
+In order for SASL to work, it seems to be necessary to put users under 
`o=system`. (This is why the setup is slightly different than the tutorial 
mentioned above):
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS
 LDAP Users]
+
+Configure the users into the groups:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS
 LDAP Users]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc
new file mode 100644
index 0000000..5ece3b3
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc
@@ -0,0 +1,36 @@
+[[_ugsec_shiro-realm-implementations_isisaddons-security-module-realm]]
+= Security Module Realm
+:Notice: 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The https://github.com/isisaddons/isis-module-security[Isis Addons' security 
module] (not ASF) provides a complete
+security subdomain for users, roles, permissions; all are persisted as domain 
entities.
+
+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's metamodel; in essence the permissions are 
"type-safe".  
+
+
+In order to play along, the module includes a Shiro realm, which fits in as 
follows:
+
+The general configuration is as follows:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG[width="600px"]
+
+where the `IsisModuleSecurityRealm` realm is the implementation provided by 
the module.
+
+In the configuration above user passwords are stored in the database.  The 
module uses link:http://www.mindrot.org/projects/jBCrypt/[jBCrypt] so that 
passwords are only stored in a (one-way) encrypted form in the database.
+
+
+
+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 `IsisModuleSecurityRealm` 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:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG[width="600px"]
+
+
+The security module has many more features than are described here, all of 
which are described in the module's 
link:https://github.com/isisaddons/isis-module-security[README].  The README 
also explains in detail how to configure an existing app to use this module.
+
+You can also look at the Isisaddons 
https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), 
which is preconfigured to use the security module.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc
new file mode 100644
index 0000000..fde09d1
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc
@@ -0,0 +1,113 @@
+[[_ugsec_shiro-realm-implementations_jdbc-realm]]
+= Shiro JDBC Realm
+:Notice: 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.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+There is nothing to stop you from using some other `Realm` implementation (or 
indeed writing one yourself).  For example, you could use Shiro's own JDBC 
realm that loads user/password details from a database.
+
+[WARNING]
+====
+If you are happy to use a database then we strongly recommend you use the 
http://github.com/isisaddons/isis-module-security[Isis addons' security] 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.
+====
+
+If you go down this route, then the architecture is as follows:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png[width="600px"]
+
+
+
+
+There's quite a lot of configuration required (in `WEB-INF/shiro.ini`) to set 
up a JDBC realm, so we'll break it out into sections.
+
+First, we need to set up the connection to JDBC:
+
+[source,ini]
+----
+jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm        # <1>
+
+jof = org.apache.shiro.jndi.JndiObjectFactory          # <2>
+jof.resourceName = jdbc/postgres                       # <3>
+jof.requiredType = javax.sql.DataSource
+jof.resourceRef = true
+
+jdbcRealm.dataSource = $jof                            # <4>
+----
+<1> instantiate the JDBC realm
+<2> instantiate factory object to lookup DataSource from servlet container
+<3> name of the datasource (as configured in `web.xml`)
+<4> instruct JDBC realm to obtain datasource from the JNDI
+
+
+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.
+
+[source,ini]
+----
+
+jdbcRealm.authenticationQuery =         \              # <1>
+        select password                 \
+          from users                    \
+         where username = ?
+
+jdbcRealm.userRolesQuery =              \              # <2>
+        select r.label                  \
+          from users_roles ur           \
+    inner join roles r                  \
+            on ur.role_id = r.id        \
+         where user_id = (              \
+            select id                   \
+             from users                 \
+            where username = ?);        \
+
+jdbcRealm.permissionsQuery=             \               # <3>
+        select p.permission             \
+          from roles_permissions rp     \
+    inner join permissions p            \
+            on rp.permission_id = p.id  \
+         where rp.role_id = (           \
+            select id                   \
+             from roles                 \
+            where label = ?);
+
+jdbcRealm.permissionsLookupEnabled=true                 # <4>
+----
+<1> query to find password for user
+<2> query to find roles for user
+<3> query to find permissions for role
+<4> enable permissions lookup
+
+[WARNING]
+====
+The `permissionsLookupEnabled` is very important, otherwise Shiro just returns 
an empty list of permissions and your users will have no access to any 
features(!).
+====
+
+We also should ensure that the passwords are not stored as plain-text:
+
+[source,ini]
+----
+dps = org.apache.shiro.authc.credential.DefaultPasswordService   # <1>
+pm = org.apache.shiro.authc.credential.PasswordMatcher           # <2>
+pm.passwordService = $dps
+jdbcRealm.credentialsMatcher = $pm                               # <3>
+----
+<1> mechanism to encrypts password
+<2> service to match passwords
+<3> instruct JDBC realm to use password matching service when authenticating
+
+
+And finally we need to tell Shiro to use the realm, in the usual fashion:
+
+[source,ini]
+----
+securityManager.realms = $jdbcRealm
+----
+
+Using the above configuration you will also need to setup a `DataSource`.  The 
details vary by servlet container, for example this is 
link:https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html[how
 to do the setup on Tomcat 8.0].
+
+[WARNING]
+====
+The name of the `DataSource` can also vary by servlet container; see for 
example 
link:http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702[this
 StackOverflow answer].
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
index 449abb5..8b5ca61 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
@@ -82,13 +82,9 @@ 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] used to c
 
 include::_ugsec_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
 
-include::_ugsec_shiro-ini-realm.adoc[leveloffset=+1]
+include::_ugsec_shiro-realm-implementations.adoc[leveloffset=+1]
 
-include::_ugsec_shiro-isis-ldap-realm.adoc[leveloffset=+1]
 
-include::_ugsec_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
-
-include::_ugsec_shiro-jdbc-realm.adoc[leveloffset=+1]
 
 include::_ugsec_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
index fa9b85f..d83beb4 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
@@ -9,7 +9,7 @@ This chapter provides some solutions for problems we've 
encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
index 8b7282b..0730daa 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
@@ -10,7 +10,7 @@ This chapter provides some solutions for problems we've 
encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide (this 
chapter)
 

Reply via email to