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 2018/01/08 22:29:10 UTC
[11/51] [abbrv] [partial] isis-site git commit: ISIS-1465: publishes
1.16.0
http://git-wip-us.apache.org/repos/asf/isis-site/blob/2b88051d/content/guides/ugsec/ugsec.html
----------------------------------------------------------------------
diff --git a/content/guides/ugsec/ugsec.html b/content/guides/ugsec/ugsec.html
deleted file mode 100644
index bb063e2..0000000
--- a/content/guides/ugsec/ugsec.html
+++ /dev/null
@@ -1,1947 +0,0 @@
-<!doctype html>
-<html>
- <head>
- <!--
- 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.
- -->
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <!-- No caching headers -->
- <meta http-equiv="cache-control" content="no-cache">
- <meta http-equiv="pragma" content="no-cache">
- <meta http-equiv="expires" content="-1">
- <title>Security</title>
- <link rel="icon" type="image/png" href="../../images/isis-favicon.png">
- <!--
- Based on DataNucleus' template,
- that was in turn based on an earlier version of Apache Isis' template,
- that was in turn based on Apache Deltaspike's template.
-
- This template uses
- * Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar.
- * Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/)
- for the table of contents.
- * jQuery (necessary for Bootstrap's JavaScript plugins)
- * Font-Awesome for some icons used by Asciidoctor
-
- Also:
- * Bootswatch "flatly" theme for Bootstrap (https://bootswatch.com/flatly).
- * slick.js (carousel)
- * add a link to all headers (home-grown, adapted from blog posts)
- * integration of elasticlunr.js (home-grown, adapted from blog posts)
- -->
- <link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/flatly/bootstrap.min.css" rel="stylesheet">
- <link href="../../css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" rel="stylesheet">
- <link href="../../css/asciidoctor/foundation.css" rel="stylesheet">
- <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
- <link href="../../css/slick/1.5.0/slick.css" rel="stylesheet">
- <link href="../../css/slick/1.5.0/slick-theme.css" rel="stylesheet">
- <link href="../../css/search-panel/search-panel.css" rel="stylesheet">
- <link href="../../css/header-links/header-links.css" rel="stylesheet">
- <link href="../../css/sticky-header/sticky-header.css" rel="stylesheet">
- <link href="../../css/customisations.css" rel="stylesheet">
- <!-- Coderay syntax formatter -->
- <style type="text/css">
- /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
-/*pre.CodeRay {background-color:#f7f7f8;}*/
-.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
-.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
-.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
-table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
-table.CodeRay td{vertical-align: top;line-height:1.45}
-table.CodeRay td.line-numbers{text-align:right}
-table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
-table.CodeRay td.code{padding:0 0 0 .5em}
-table.CodeRay td.code>pre{padding:0}
-.CodeRay .debug{color:#fff !important;background:#000080 !important}
-.CodeRay .annotation{color:#007}
-.CodeRay .attribute-name{color:#000080}
-.CodeRay .attribute-value{color:#700}
-.CodeRay .binary{color:#509}
-.CodeRay .comment{color:#998;font-style:italic}
-.CodeRay .char{color:#04d}
-.CodeRay .char .content{color:#04d}
-.CodeRay .char .delimiter{color:#039}
-.CodeRay .class{color:#458;font-weight:bold}
-.CodeRay .complex{color:#a08}
-.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
-.CodeRay .color{color:#099}
-.CodeRay .class-variable{color:#369}
-.CodeRay .decorator{color:#b0b}
-.CodeRay .definition{color:#099}
-.CodeRay .delimiter{color:#000}
-.CodeRay .doc{color:#970}
-.CodeRay .doctype{color:#34b}
-.CodeRay .doc-string{color:#d42}
-.CodeRay .escape{color:#666}
-.CodeRay .entity{color:#800}
-.CodeRay .error{color:#808}
-.CodeRay .exception{color:inherit}
-.CodeRay .filename{color:#099}
-.CodeRay .function{color:#900;font-weight:bold}
-.CodeRay .global-variable{color:#008080}
-.CodeRay .hex{color:#058}
-.CodeRay .integer,.CodeRay .float{color:#099}
-.CodeRay .include{color:#555}
-.CodeRay .inline{color:#000}
-.CodeRay .inline .inline{background:#ccc}
-.CodeRay .inline .inline .inline{background:#bbb}
-.CodeRay .inline .inline-delimiter{color:#d14}
-.CodeRay .inline-delimiter{color:#d14}
-.CodeRay .important{color:#555;font-weight:bold}
-.CodeRay .interpreted{color:#b2b}
-.CodeRay .instance-variable{color:#008080}
-.CodeRay .label{color:#970}
-.CodeRay .local-variable{color:#963}
-.CodeRay .octal{color:#40e}
-.CodeRay .predefined{color:#369}
-.CodeRay .preprocessor{color:#579}
-.CodeRay .pseudo-class{color:#555}
-.CodeRay .directive{font-weight:bold}
-.CodeRay .type{font-weight:bold}
-.CodeRay .predefined-type{color:inherit}
-.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
-.CodeRay .key{color:#808}
-.CodeRay .key .delimiter{color:#606}
-.CodeRay .key .char{color:#80f}
-.CodeRay .value{color:#088}
-.CodeRay .regexp .delimiter{color:#808}
-.CodeRay .regexp .content{color:#808}
-.CodeRay .regexp .modifier{color:#808}
-.CodeRay .regexp .char{color:#d14}
-.CodeRay .regexp .function{color:#404;font-weight:bold}
-.CodeRay .string{color:#d20}
-.CodeRay .string .string .string{background:#ffd0d0}
-.CodeRay .string .content{color:#d14}
-.CodeRay .string .char{color:#d14}
-.CodeRay .string .delimiter{color:#d14}
-.CodeRay .shell{color:#d14}
-.CodeRay .shell .delimiter{color:#d14}
-.CodeRay .symbol{color:#990073}
-.CodeRay .symbol .content{color:#a60}
-.CodeRay .symbol .delimiter{color:#630}
-.CodeRay .tag{color:#008080}
-.CodeRay .tag-special{color:#d70}
-.CodeRay .variable{color:#036}
-.CodeRay .insert{background:#afa}
-.CodeRay .delete{background:#faa}
-.CodeRay .change{color:#aaf;background:#007}
-.CodeRay .head{color:#f8f;background:#505}
-.CodeRay .insert .insert{color:#080}
-.CodeRay .delete .delete{color:#800}
-.CodeRay .change .change{color:#66f}
-.CodeRay .head .head{color:#f4f}
- </style>
- </head>
- <body data-spy="scroll" data-target="#toc">
- <div id="basedir" style="display:none;">
- ../../
- </div>
- <div id="docname" style="display:none;">
- ugsec
- </div>
- <div id="filetype" style="display:none;">
- html
- </div>
- <!-- Navbar -->
- <nav class="navbar navbar-default navbar-static-top header">
- <div class="container">
- <div class="navbar-header">
- <!-- Three line menu button for use on mobile screens -->
- <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button>
- <a class="navbar-brand" href="../../index.html"> <img alt="Brand" src="../../images/isis-logo-48x48.png"> </a>
- <a class="navbar-brand" href="../../index.html">Apache Isis</a>
- </div>
- <!-- Navbar that will collapse on mobile screens -->
- <div id="navbar" class="navbar-collapse collapse">
- <ul class="nav navbar-nav">
- <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Documentation<span class="caret"></span></a>
- <ul class="dropdown-menu">
- <li><a href="../../documentation.html">Table of Contents</a></li>
- <li role="separator" class="divider"></li>
- <li class="dropdown-header">User Guides</li>
- <li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li>
- <li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li>
- <li><a href="../../guides/ugvro/ugvro.html">Restful Objects Viewer</a></li>
- <li><a href="../../guides/ugsec/ugsec.html">Security</a></li>
- <li><a href="../../guides/ugtst/ugtst.html">Testing</a></li>
- <li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li>
- <li role="separator" class="divider"></li>
- <li class="dropdown-header">Reference Guides</li>
- <li><a href="../../guides/rgant/rgant.html">Annotations</a></li>
- <li><a href="../../guides/rgsvc/rgsvc.html">Domain Services</a></li>
- <li><a href="../../guides/rgcfg/rgcfg.html">Core Config' Properties</a></li>
- <li><a href="../../guides/rgcms/rgcms.html">Classes, Methods and Schema</a></li>
- <li><a href="../../guides/rgmvn/rgmvn.html">Maven plugin</a></li>
- <li><a href="../../guides/rgfis/rgfis.html">Framework Internal Services</a></li>
- <li role="separator" class="divider"></li>
- <li class="dropdown-header">Javadoc</li>
- <li><a href="http://javadoc.io/doc/org.apache.isis.core/isis-core-applib">Applib</a></li>
- </ul> </li>
- <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Downloads<span class="caret"></span></a>
- <ul class="dropdown-menu">
- <li><a href="../../downloads.html">Downloads</a></li>
- <li><a href="../../release-notes/release-notes.html">Release Notes</a></li>
- <li><a href="../../migration-notes/migration-notes.html">Migration Notes</a></li>
- <li role="separator" class="divider"></li>
- <li class="dropdown-header">Maven archetypes</li>
- <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li>
- <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li>
- <li role="separator" class="divider"></li>
- <li><a href="https://issues.apache.org/jira/browse/ISIS">ASF JIRA</a></li>
- <li><a href="https://github.com/apache/isis">Github mirror</a></li>
- </ul> </li>
- <li class="dropdown hidden-sm"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Support<span class="caret"></span></a>
- <ul class="dropdown-menu">
- <li><a href="../../support.html">Mailing lists</a></li>
- <li><a href="https://lists.apache.org/list.html?users@isis.apache.org">Archives (ASF Pony mail)</a></li>
- <li><a href="http://isis.markmail.org/search/?q=">Archives (Markmail)</a></li>
- <li><a href="http://stackoverflow.com/questions/tagged/isis">Stack Overflow</a></li>
- <li><a href="../../guides/dg/dg.html">How to contribute</a></li>
- <li><a href="../../help.html">Other resources</a></li>
- </ul> </li>
- <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a>
- <ul class="dropdown-menu">
- <li><a href="http://www.apache.org/">Apache Homepage</a></li>
- <li><a href="http://www.apache.org/licenses/">Licenses</a></li>
- <li><a href="http://www.apache.org/security/">Security</a></li>
- <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
- <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
- <li role="separator" class="divider"></li>
- <li><a href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a></li>
- </ul> </li>
- </ul>
- <div class="nav navbar-nav navbar-right">
- <!-- 'style' added to fix height of input box. FIX THIS -->
- <form class="navbar-form" role="search" id="search-form" style="padding: 1px 15px;">
- <div class="form-group">
- <input class="form-control" id="search-field" type="text" size="30" placeholder="Search">
- </div>
- </form>
- </div>
- </div>
- </div>
- </nav>
- <div class="container">
- <div class="row-fluid">
- <div class="col-xs-12 col-sm-12 col-md-12 col-lg-9">
- <div id="search-panel">
- <div id="search-results"></div>
- <div>
- <br>
- <a href="#" id="search-results-clear">clear</a>
- </div>
- </div>
- <span class="pdf-link"><a href="ugsec.pdf"><img src="../../images/PDF-50.png"></a></span>
- <div class="page-title">
- <h1>Security</h1>
- </div>
- <div id="doc-content">
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <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/ugfun.html">Fundamentals</a></p> </li>
- <li> <p><a href="../ugvw/ugvw.html">Wicket viewer</a></p> </li>
- <li> <p><a href="../ugvro/ugvro.html">Restful Objects viewer</a></p> </li>
- <li> <p><a href="../ugodn/ugodn.html">DataNucleus object store</a></p> </li>
- <li> <p><a href="../ugsec/ugsec.html">Security</a> (this guide)</p> </li>
- <li> <p><a href="../ugtst/ugtst.html">Testing</a></p> </li>
- <li> <p><a href="../ugbtb/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/rgant.html">Annotations</a></p> </li>
- <li> <p><a href="../rgsvc/rgsvc.html">Domain Services</a></p> </li>
- <li> <p><a href="../rgcfg/rgcfg.html">Configuration Properties</a></p> </li>
- <li> <p><a href="../rgcms/rgcms.html">Classes, Methods and Schema</a></p> </li>
- <li> <p><a href="../rgmvn/rgmvn.html">Apache Isis Maven plugin</a></p> </li>
- <li> <p><a href="../rgfis/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/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/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 — the <code>IniRealm</code> — which reads users (and password), user roles and role permissions from the <code>WEB-INF/shiro.ini</code> file. The <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a> and <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp</a> archetypes are both 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://platform.incode.org" target="_blank">Incode Platform</a> modules provides the security 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/rgsvc.html#_rgsvc_application-layer-api_InteractionContext"><code>InteractionContext</code></a> can be used to track the actions being invoked, and the <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-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://platform.incode.org" target="_blank">Incode Platform</a>'s publishmq module) this provides excellent traceability. The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s audit 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/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> can be used to capture actions, while the (deprecated) <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-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 to use Shiro</h2>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <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>Both the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a> and <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp</a> archetypes are pre-configured to use Apache Shiro, so much of what follows may well have been 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, set the "isis.authentication" and "isis.authorisation" properties.</p>
- </div>
- <div class="paragraph">
- <p>One way to do this is by updating 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>Alternatively (as of <code>1.15.0</code>) you can set them both programmatically from the <code>AppManifestAbstract.BUILDER</code> (see <a href="../rgcms/rgcms.html#__rgcms_classes_AppManifest-bootstrapping_bootstrapping_AppManifestAbstract">here</a>). For example, the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld archetype</a> bootstraps using:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">HelloWorldAppManifest</span> <span class="directive">extends</span> AppManifestAbstract {
-
- <span class="directive">public</span> <span class="directive">static</span> <span class="directive">final</span> Builder BUILDER = Builder
- .forModules(HelloWorldModule.class)
- .withConfigurationPropertiesFile(
- HelloWorldAppManifest.class, <span class="string"><span class="delimiter">"</span><span class="content">isis.properties</span><span class="delimiter">"</span></span>)
- .withAuthMechanism(<span class="string"><span class="delimiter">"</span><span class="content">shiro</span><span class="delimiter">"</span></span>);
-
- <span class="directive">public</span> HelloWorldAppManifest() {
- <span class="local-variable">super</span>(BUILDER);
- }
-}</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>Either way, this installs the appropriate implementation (the <code>ShiroAuthenticatorOrAuthorizor</code> class) that use Shiro’s APIs to perform authentication and authorization:</p>
- </div>
- <div class="imageblock">
- <div class="content">
- <a class="image" href="images/security/security-apis-impl/configure-isis-to-use-shiro.png"><img src="images/security/security-apis-impl/configure-isis-to-use-shiro.png" alt="configure isis to use shiro" width="600px"></a>
- </div>
- </div>
- <div class="paragraph">
- <p>The figure above doesn’t tell the whole story; we haven’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_shiro_authenticator">2.2. Configuring 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/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"><listener></span>
- <span class="tag"><listener-class></span>org.apache.shiro.web.env.EnvironmentLoaderListener<span class="tag"></listener-class></span>
-<span class="tag"></listener></span>
-<span class="tag"><filter></span>
- <span class="tag"><filter-name></span>ShiroFilter<span class="tag"></filter-name></span>
- <span class="tag"><filter-class></span>org.apache.shiro.web.servlet.ShiroFilter<span class="tag"></filter-class></span>
-<span class="tag"></filter></span>
-<span class="tag"><filter-mapping></span>
- <span class="tag"><filter-name></span>ShiroFilter<span class="tag"></filter-name></span>
- <span class="tag"><url-pattern></span>/*<span class="tag"></url-pattern></span>
-<span class="tag"></filter-mapping></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’s ini file supports a "poor-man’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’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-realm-implementations">3. Shiro Realm Implementations</h2>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <div class="sectionbody">
- <div class="sect2">
- <h3 id="_ugsec_shiro-realm-implementations_ini-realm">3.1. Shiro Ini Realm</h3>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <div class="paragraph">
- <p>Probably the simplest realm to use is Shiro’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’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 both the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a> and <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp</a> archetypes are 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">
- <a class="image" href="images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG"><img src="images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG" alt="configure shiro to use ini realm" width="600px"></a>
- </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="sect3">
- <h4 id="_shiro_configuration">3.1.1. Shiro Configuration</h4>
- <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="sect4">
- <h5 id="__code_users_code_section"><code>[users]</code> section</h5>
- <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="sect4">
- <h5 id="__code_roles_code_section"><code>[roles]</code> section</h5>
- <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
-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</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/ugsec.html#_ugsec_shiro-isis-enhanced-wildcard-permission">here</a>.</p>
- </div> </td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- </div>
- <div class="sect3">
- <h4 id="_externalized_inirealm">3.1.2. Externalized IniRealm</h4>
- <div class="paragraph">
- <p>There’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>
- <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’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>
- </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 class="sect2">
- <h3 id="_ugsec_shiro-realm-implementations_isis-ldap-realm">3.2. Isis Ldap Realm</h3>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <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">
- <a class="image" href="images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG"><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"></a>
- </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="sect3">
- <h4 id="_shiro_configuration_2">3.2.1. Shiro Configuration</h4>
- <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
-contextFactory.authenticationMechanism = CRAM-MD5 <i class="conum" data-value="2"></i><b>(2)</b>
-contextFactory.systemAuthenticationMechanism = simple
-
-ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm <i class="conum" data-value="3"></i><b>(3)</b>
-ldapRealm.contextFactory = $contextFactory
-
-ldapRealm.searchBase = ou=groups,o=mojo <i class="conum" data-value="4"></i><b>(4)</b>
-ldapRealm.groupObjectClass = groupOfUniqueNames <i class="conum" data-value="5"></i><b>(5)</b>
-ldapRealm.uniqueMemberAttribute = uniqueMember <i class="conum" data-value="6"></i><b>(6)</b>
-ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
-
-# optional mapping from physical groups to logical application roles
-ldapRealm.rolesByGroup = \ <i class="conum" data-value="7"></i><b>(7)</b>
- LDN_USERS: user_role,\
- NYK_USERS: user_role,\
- HKG_USERS: user_role,\
- GLOBAL_ADMIN: admin_role,\
- DEMOS: self-install_role
-
-ldapRealm.permissionsByRole=\ <i class="conum" data-value="8"></i><b>(8)</b>
- user_role = *:ToDoItemsJdo:*:*,\
- *:ToDoItem:*:*; \
- self-install_role = *:ToDoItemsFixturesService:install:* ; \
- admin_role = *
-
-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’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 '' after the "," that separates the key:value pairs it is more readable.</p>
- </div> </td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- <div class="sect3">
- <h4 id="_externalizing_role_perms">3.2.2. Externalizing role perms</h4>
- <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="sect3">
- <h4 id="_active_ds_ldap_tutorial">3.2.3. Active DS LDAP tutorial</h4>
- <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">
- <a class="image" href="images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png"><img src="images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png" alt="activeds ldap mojo partition"></a>
- </div>
- </div>
- <div class="paragraph">
- <p>Create the <code>ou=groups,o=mojo</code> hierarchy:</p>
- </div>
- <div class="imageblock">
- <div class="content">
- <a class="image" href="images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png"><img src="images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png" alt="activeds ldap mojo root dse"></a>
- </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">
- <a class="image" href="images/configuration/configuring-shiro/ldap/activeds-ldap-sas"><img src="images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png" alt="activeds ldap sasl authentication"></a>
- </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">
- <a class="image" href="images/configuration/configuring-shiro/ldap/activeds-ldap-users.png"><img src="images/configuration/configuring-shiro/ldap/activeds-ldap-users.png" alt="activeds ldap users"></a>
- </div>
- </div>
- <div class="paragraph">
- <p>Configure the users into the groups:</p>
- </div>
- <div class="imageblock">
- <div class="content">
- <a class="image" href="images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png"><img src="images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png" alt="activeds ldap groups"></a>
- </div>
- </div>
- </div>
- </div>
- <div class="sect2">
- <h3 id="_ugsec_shiro-realm-implementations_isisaddons-security-module-realm">3.3. Security Module Realm</h3>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s security module 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’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">
- <a class="image" href="images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG"><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"></a>
- </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">
- <a class="image" href="images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG"><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"></a>
- </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’s README. 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 class="sect2">
- <h3 id="_ugsec_shiro-realm-implementations_jdbc-realm">3.4. Shiro JDBC Realm</h3>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <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’s 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 (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s 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.</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">
- <a class="image" href="images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png"><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"></a>
- </div>
- </div>
- <div class="paragraph">
- <p>There’s quite a lot of configuration required (in <code>WEB-INF/shiro.ini</code>) to set up a JDBC realm, so we’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>
-
-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>
- <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 = ?
-
-jdbcRealm.userRolesQuery = \ <i class="conum" data-value="2"></i><b>(2)</b>
- 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= \ <i class="conum" data-value="3"></i><b>(3)</b>
- 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 <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>
- <tbody>
- <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>
- </tbody>
- </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>
- <tbody>
- <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>
- </tbody>
- </table>
- </div>
- </div>
- </div>
- </div>
- <div class="sect1">
- <h2 id="_ugsec_shiro-isis-enhanced-wildcard-permission">4. Enhanced Wildcard Permission</h2>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <div class="sectionbody">
- <div class="paragraph">
- <p>If using the text-based <a href="../ugsec/ugsec.html#_ugsec_shiro-realm-implementations_ini-realm"><code>IniRealm</code></a> or <a href="../ugsec/ugsec.html#_ugsec_shiro-realm-implementations_isis-ldap-realm">Isis' LDAP realm</a>, then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative <code>Permission</code> instances. Apache Isis provides its own <code>IsisPermission</code> which introduces the concept of a "veto".</p>
- </div>
- <div class="paragraph">
- <p>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.</p>
- </div>
- <div class="paragraph">
- <p>The string representation of the <code>IsisPermission</code> uses the following format:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="CodeRay highlight"><code data-lang="ini">([!]?)([^/]+)[/](.+)</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>where:</p>
- </div>
- <div class="ulist">
- <ul>
- <li> <p>the optional <code>!</code> prefix indicates this permission is a vetoing permission</p> </li>
- <li> <p>the optional <code>xxx/</code> prefix is a permission group that scopes any vetoing permissions</p> </li>
- <li> <p>the remainder of the string is the permission (possibly wildcarded, with :rw as optional suffix)</p> </li>
- </ul>
- </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 = !reg/org.estatio.api,\
- !reg/org.estatio.webapp.services.admin,\
- reg/* ; \
-api_role = org.estatio.api ;\
-admin_role = adm/*</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>sets up:</p>
- </div>
- <div class="ulist">
- <ul>
- <li> <p>the <code>user_role</code> with access to all permissions except those in <code>org.estatio.api</code> and <code>org.estatio.webapp.services.admin</code></p> </li>
- <li> <p>the <code>api_role</code> with access to all permissions in <code>org.estatio.api</code></p> </li>
- <li> <p>the <code>admin_role</code> with access to everything.</p> </li>
- </ul>
- </div>
- <div class="paragraph">
- <p>The permission group concept is required to scope the applicability of any veto permission. This is probably best explained by an example. Suppose that a user has both <code>admin_role</code> and <code>user_role</code>; we would want the <code>admin_role</code> to trump the vetos of the <code>user_role</code>, in other words to give the user access to everything.</p>
- </div>
- <div class="paragraph">
- <p>Because of the permission groups, the two "!reg/...+""" vetos in user_role only veto out selected permissions granted by the "reg/<strong>" permissions, but they do not veto the permissions granted by a different scope, namely "adm/</strong>+".</p>
- </div>
- <div class="paragraph">
- <p>The net effect is therefore what we would want: that a user with both <code>admin_role</code> and <code>user_role</code> would have access to everything, irrespective of those two veto permissions of the <code>user_role</code>.</p>
- </div>
- <div class="paragraph">
- <p>Finally, the Apache Isis permission resolver is specified in <code>WEB-INF/shiro.ini</code> file:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="CodeRay highlight"><code data-lang="ini">permissionResolver = org.apache.isis.security.shiro.authorization.IsisPermissionResolver
-myRealm.permissionResolver = $permissionResolver <i class="conum" data-value="1"></i><b>(1)</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><code>myRealm</code> is the handle to the configured realm, eg <code>$iniRealm</code> or <code>$isisLdapRealm</code> etc.</td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- </div>
- <div class="sect1">
- <h2 id="_ugsec_hints-and-tips">5. Hints and Tips</h2>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <div class="sectionbody">
- <div class="paragraph">
- <p>This chapter provides some solutions for problems we’ve encountered ourselves or have been raised on the Apache Isis mailing lists.</p>
- </div>
- <div class="paragraph">
- <p>See also hints-n-tips chapters in the:</p>
- </div>
- <div class="ulist">
- <ul>
- <li> <p>the <a href="../dg/dg.html#_dg_hints-and-tips">Developers'</a> guide</p> </li>
- <li> <p>the <a href="../ugvw/ugvw.html#_ugvw_hints-and-tips">Wicket viewer</a> guide</p> </li>
- <li> <p>the <a href="../ugvro/ugvro.html#_ugvro_hints-and-tips">Restful Objects viewer</a> guide</p> </li>
- <li> <p>the <a href="../ugodn/ugodn.html#_ugodn_hints-and-tips">Datanucleus ObjectStore</a> guide</p> </li>
- <li> <p>the <a href="../ugsec/ugsec.html#_ugsec_hints-and-tips">Security</a> guide (this chapter)</p> </li>
- <li> <p>the <a href="../ugbtb/ugbtb.html#_ugbtb_hints-and-tips">Beyond the Basics</a> guide.</p> </li>
- </ul>
- </div>
- <div class="sect2">
- <h3 id="_ugsec_hints-and-tips_configuring-isis-to-use-bypass">5.1. Bypassing security</h3>
- <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
- <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
- <ul class="dropdown-menu">
- <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
- <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
- <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
- <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
- </ul>
- </div>
- <div class="paragraph">
-
<TRUNCATED>