| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <title>Security :: Apache Isis</title> |
| <link rel="canonical" href="https://isis.apache.org/vro/2.0.0-M4/security.html"> |
| <meta name="generator" content="Antora 2.3.4"> |
| <link rel="stylesheet" href="../../_/css/site.css"> |
| <link rel="stylesheet" href="../../_/css/site-custom.css"> |
| <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,700,700i|Raleway:300,400,500,700,800|Montserrat:300,400,700" rel="stylesheet"> |
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"/> |
| <link rel="home" href="https://isis.apache.org" title="Apache Isis"> |
| <link rel="next" href="hints-and-tips.html" title="Hints-n-Tips"> |
| <link rel="prev" href="configuration-properties.html" title="Configuration Properties"> |
| </head> |
| <body class="article"> |
| <header class="header"> |
| <nav class="navbar"> |
| <div class="navbar-brand"> |
| <a class="navbar-item" href="https://isis.apache.org"> |
| <span class="icon"> |
| <img src="../../_/img/isis-logo-48x48.png"></img> |
| </span> |
| <span>Apache Isis</span> |
| </a> |
| <button class="navbar-burger" data-target="topbar-nav"> |
| <span></span> |
| <span></span> |
| <span></span> |
| </button> |
| </div> |
| <div id="topbar-nav" class="navbar-menu"> |
| <a class="navbar-end"> |
| <div class="navbar-item hide-for-print"> |
| <span> |
| <input id="algolia-search-input" placeholder="Search"></span> |
| </span> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Quick Start</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Starter Apps</span> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/starters/helloworld.html">Hello World</a> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/starters/simpleapp.html">Simple App</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Demos & Tutorials</span> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/demo/about.html">Demo App</a> |
| <a class="navbar-item" href="https://danhaywood.gitlab.io/isis-petclinic-tutorial-docs/petclinic/1.16.2/intro.html">Petclinic (tutorial)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Resources</span> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/resources/cheatsheet.html">Cheatsheet</a> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/resources/icons.html">Icons</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Guides</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Development</span> |
| <a class="navbar-item" href="../../setupguide/2.0.0-M4/about.html">Setup Guide</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Core</span> |
| <a class="navbar-item" href="../../userguide/2.0.0-M4/about.html">User Guide</a> |
| <a class="navbar-item" href="../../refguide/2.0.0-M4/about.html">Reference Guide</a> |
| <a class="navbar-item" href="../../testing/2.0.0-M4/about.html">Testing Guide</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Libraries</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">For Use in Apps</span> |
| <a class="navbar-item" href="../../subdomains/2.0.0-M4/about.html">Subdomain Libraries</a> |
| <a class="navbar-item" href="../../valuetypes/2.0.0-M4/about.html">Value Types</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Integrate between Apps</span> |
| <a class="navbar-item" href="../../mappings/2.0.0-M4/about.html">Bounded Context Mapping Libraries</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Other</span> |
| <a class="navbar-item" href="../../incubator/2.0.0-M4/about.html">Incubator</a> |
| <a class="navbar-item" href="../../legacy/2.0.0-M4/about.html">Legacy</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Components</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Viewers</span> |
| <a class="navbar-item" href="../../vw/2.0.0-M4/about.html">Wicket UI</a> |
| <a class="navbar-item" href="../../vro/2.0.0-M4/about.html">Restful Objects (REST)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Security</span> |
| <a class="navbar-item" href="../../security/2.0.0-M4/about.html">Security Guide</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Persistence</span> |
| <a class="navbar-item" href="../../pjdo/2.0.0-M4/about.html">DataNucleus (JDO)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Extensions</span> |
| <a class="navbar-item" href="../../extensions/2.0.0-M4/about.html">Extensions Catalog</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Support</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Contact</span> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/support/slack-channel.html">Slack</a> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/support/mailing-list.html">Mailing Lists</a> |
| <a class="navbar-item" href="https://issues.apache.org/jira/browse/ISIS">JIRA</a> |
| <a class="navbar-item" href="https://stackoverflow.com/questions/tagged/isis">Stack Overflow</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Releases</span> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/downloads/how-to.html">Downloads</a> |
| <a class="navbar-item" href="../../relnotes/2.0.0-M4/about.html">Release Notes</a> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/archive/1-x.html">Archive (1.x)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Framework</span> |
| <a class="navbar-item" href="../../conguide/2.0.0-M4/about.html">Contributors' Guide</a> |
| <a class="navbar-item" href="../../comguide/2.0.0-M4/about.html">Committers' Guide</a> |
| <a class="navbar-item" href="../../core/2.0.0-M4/about.html">Core Design</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">ASF</a> |
| <div class="navbar-dropdown"> |
| <a class="navbar-item" href="http://www.apache.org/">Apache Homepage</a> |
| <a class="navbar-item" href="https://www.apache.org/events/current-event">Events</a> |
| <a class="navbar-item" href="https://www.apache.org/licenses/">Licenses</a> |
| <a class="navbar-item" href="https://www.apache.org/security/">Security</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <hr class="navbar-divider"/> |
| <a class="navbar-item" href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a> |
| </div> |
| </div> |
| <a class="navbar-item" href="../../docs/2.0.0-M4/about.html"> |
| <span class="icon"> |
| <img src="../../_/img/home.png"></img> |
| </span> |
| </a> |
| </div> |
| </div> |
| </nav> |
| </header> |
| <div class="body "> |
| <div class="nav-container" data-component="vro" data-version="2.0.0-M4"> |
| <aside class="nav"> |
| <div class="panels"> |
| <div class="nav-panel-pagination"> |
| <a class="page-previous" rel="prev" href="configuration-properties.html" title="Configuration Properties"><span></span></a> |
| <a class="page-next" rel="next" |
| href="hints-and-tips.html" title="Hints-n-Tips"><span></span></a> |
| <!-- |
| page.parent doesn't seem to be set... |
| <a class="page-parent disabled" rel="prev" href="" title="Configuration Properties"><span></span></a> |
| --> |
| </div> |
| <div class="nav-panel-menu is-active" data-panel="menu"> |
| <nav class="nav-menu"> |
| <h3 class="title"><a href="about.html">Restful Objects Viewer</a></h3> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="ro-spec.html">RO Spec</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="architecture.html">Architecture</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="layout-resources.html">Layout Resources</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="health-check.html">Health Check</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="simplified-representations.html">Simplified Representations</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="configuration-properties.html">Configuration Properties</a> |
| </li> |
| <li class="nav-item is-current-page" data-depth="1"> |
| <a class="nav-link" href="security.html">Security</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="hints-and-tips.html">Hints-n-Tips</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <span class="nav-text">Extensions</span> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="cors/about.html">CORS</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| <div class="nav-panel-explore" data-panel="explore"> |
| <div class="context"> |
| <span class="title">Restful Objects Viewer</span> |
| <span class="version">2.0.0-M4</span> |
| </div> |
| <ul class="components"> |
| <li class="component"> |
| <span class="title"> </span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../docs/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">BC Mappings Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../mappings/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Committers' Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../comguide/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Contributors' Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../conguide/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Design Docs</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../core/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Extensions Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../extensions/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Incubator Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../incubator/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">JDO/DataNucleus</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../pjdo/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Legacy Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../legacy/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Reference Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../refguide/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Release Notes</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../relnotes/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component is-current"> |
| <span class="title">Restful Objects Viewer</span> |
| <ul class="versions"> |
| <li class="version is-current is-latest"> |
| <a href="about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Security Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../security/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Setup Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../setupguide/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Subdomains Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../subdomains/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">System Overview</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../system/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Testing Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../testing/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">User Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../userguide/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Value Types Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../valuetypes/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Wicket Viewer</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../vw/2.0.0-M4/about.html">2.0.0-M4</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </aside> |
| </div> |
| <main role="main"> |
| <div class="toolbar" role="navigation"> |
| <button class="nav-toggle"></button> |
| <a href="../../docs/2.0.0-M4/about.html" class="home-link"></a> |
| <nav class="breadcrumbs" aria-label="breadcrumbs"> |
| <ul> |
| <li><a href="about.html">Restful Objects Viewer</a></li> |
| <li><a href="security.html">Security</a></li> |
| </ul> |
| </nav> |
| <div class="edit-this-page"><a href="https://github.com/apache/isis/edit/2.0.0-M4/viewers/restfulobjects/adoc/modules/ROOT/pages/security.adoc">Edit</a></div> |
| </div> |
| <article class="doc"> |
| <a name="section-top"></a> |
| <h1 class="page">Security</h1> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| TODO: this content has not yet been reviewed/updated for v2.0 |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Unlike the Wicket viewer, the <a href="about.html" class="page">Restful Objects viewer</a> does <strong>not</strong> provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the <code>IsisSessionFilter</code> filter (set up by the framework’s web bootstrapping). |
| The authentication strategy is responsible for ensuring that a session is available for the REST resource.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The API of <code>AuthenticationSessionStrategy</code> is simply:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package org.apache.isis.core.webapp.auth; |
| ... |
| public interface AuthenticationSessionStrategy { |
| AuthenticationSession lookupValid( <i class="conum" data-value="1"></i><b>(1)</b> |
| ServletRequest servletRequest, |
| ServletResponse servletResponse); |
| void bind( <i class="conum" data-value="2"></i><b>(2)</b> |
| ServletRequest servletRequest, |
| ServletResponse servletResponse, |
| AuthenticationSession authSession); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>returns a valid <code>AuthenticationSession</code> for the specified request, response</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>binds (associates the provided <code>AuthenticationSession</code>) to the request and response</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Here <code>AuthenticationSession</code> is Apache Isis' internal API that represents a signed-on user.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The framework provides a number of simple strategies:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>AuthenticationSessionStrategyBasicAuth</code> implements the HTTP basic auth protocol (the pop-up dialog box shown by the web browser)</p> |
| </li> |
| <li> |
| <p><code>AuthenticationSessionStrategyHeader</code> that simply reads the user identity from an HTTP header</p> |
| </li> |
| <li> |
| <p><code>AuthenticationSessionStrategyTrusted</code> that always logs in with a special "exploration" user</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see, none of these should be considered production-quality.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The strategy is configured in <code>web.xml</code>; for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><filter> |
| <filter-name>IsisSessionFilterForRestfulObjects</filter-name> |
| <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class> |
| <init-param> |
| <param-name>authenticationSessionStrategy</param-name> |
| <param-value> <i class="conum" data-value="1"></i><b>(1)</b> |
| org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth |
| </param-value> |
| </init-param> |
| <init-param> |
| <param-name>whenNoSession</param-name> |
| <param-value>auto</param-value> <i class="conum" data-value="2"></i><b>(2)</b> |
| </init-param> |
| <init-param> |
| <param-name>passThru</param-name> |
| <param-value>/restful/swagger</param-value> <i class="conum" data-value="3"></i><b>(3)</b> |
| </init-param> |
| </filter></code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>configure basic auth strategy</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>what to do if no session was found; we use <code>auto</code> so as to issue a 401 status code with basic authentication challenge if the request originated from a web browser. (Prior to <code>1.11.0</code> this parameter was set either to <code>basicAuthChallenge</code> (which works when requested from web browser) or to <code>unauthorized</code> (which works when requested from a suitably coded custom Javascript app).</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="3"></i><b>3</b></td> |
| <td>which paths are allowed to be accessed directly, without a session. The <code>/restful/swagger</code> path provides access to the SwaggerResource that dynamically generates swagger schema definition files from the Apache Isis metamodel.</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The above filter must then be chained before the servlet that actually handles the REST requests:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><filter-mapping> |
| <filter-name>IsisSessionFilterForRestfulObjects</filter-name> |
| <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name> |
| </filter-mapping> |
| ... |
| <servlet> |
| <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name> |
| <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class> |
| </servlet></code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The above <code>web.xml</code> fragments do <em>not</em> constitute the full configuration for the Restful Objects viewer, just those parts that pertain to security.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="user-registration"><a class="anchor" href="#user-registration"></a>User-registration</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Unlike the Wicket viewer, the <a href="about.html" class="page">Restful Objects viewer</a> does <strong>not</strong> provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the <code>IsisSessionFilter</code> filter (set up by the framework’s web bootstrapping). |
| The authentication strategy is responsible for ensuring that a session is available for the REST resource.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The API of <code>AuthenticationSessionStrategy</code> is simply:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package org.apache.isis.core.webapp.auth; |
| ... |
| public interface AuthenticationSessionStrategy { |
| AuthenticationSession lookupValid( <i class="conum" data-value="1"></i><b>(1)</b> |
| ServletRequest servletRequest, |
| ServletResponse servletResponse); |
| void bind( <i class="conum" data-value="2"></i><b>(2)</b> |
| ServletRequest servletRequest, |
| ServletResponse servletResponse, |
| AuthenticationSession authSession); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>returns a valid <code>AuthenticationSession</code> for the specified request, response</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>binds (associates the provided <code>AuthenticationSession</code>) to the request and response</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Here <code>AuthenticationSession</code> is Apache Isis' internal API that represents a signed-on user.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The framework provides a number of simple strategies:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>AuthenticationSessionStrategyBasicAuth</code> implements the HTTP basic auth protocol (the pop-up dialog box shown by the web browser)</p> |
| </li> |
| <li> |
| <p><code>AuthenticationSessionStrategyHeader</code> that simply reads the user identity from an HTTP header</p> |
| </li> |
| <li> |
| <p><code>AuthenticationSessionStrategyTrusted</code> that always logs in with a special "exploration" user</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see, none of these should be considered production-quality.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The strategy is configured in <code>web.xml</code>; for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><filter> |
| <filter-name>IsisSessionFilterForRestfulObjects</filter-name> |
| <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class> |
| <init-param> |
| <param-name>authenticationSessionStrategy</param-name> |
| <param-value> <i class="conum" data-value="1"></i><b>(1)</b> |
| org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth |
| </param-value> |
| </init-param> |
| <init-param> |
| <param-name>whenNoSession</param-name> |
| <param-value>auto</param-value> <i class="conum" data-value="2"></i><b>(2)</b> |
| </init-param> |
| <init-param> |
| <param-name>passThru</param-name> |
| <param-value>/restful/swagger</param-value> <i class="conum" data-value="3"></i><b>(3)</b> |
| </init-param> |
| </filter></code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>configure basic auth strategy</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>what to do if no session was found; we use <code>auto</code> so as to issue a 401 status code with basic authentication challenge if the request originated from a web browser. (Prior to <code>1.11.0</code> this parameter was set either to <code>basicAuthChallenge</code> (which works when requested from web browser) or to <code>unauthorized</code> (which works when requested from a suitably coded custom Javascript app).</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="3"></i><b>3</b></td> |
| <td>which paths are allowed to be accessed directly, without a session. The <code>/restful/swagger</code> path provides access to the SwaggerResource that dynamically generates swagger schema definition files from the Apache Isis metamodel.</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The above filter must then be chained before the servlet that actually handles the REST requests:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><filter-mapping> |
| <filter-name>IsisSessionFilterForRestfulObjects</filter-name> |
| <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name> |
| </filter-mapping> |
| ... |
| <servlet> |
| <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name> |
| <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class> |
| </servlet></code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The above <code>web.xml</code> fragments do <em>not</em> constitute the full configuration for the Restful Objects viewer, just those parts that pertain to security.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Isis currently does not have any out-of-the-box support for user-registration for applications using only the Restful viewer. However, in principal the pieces do exist to put together a solution.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The general idea is similar to the design of the Wicket viewer; define some subsidiary resources that can operate <em>without</em> a user session in place, and which "reach into" the framework using headless access in order to setup the user.</p> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>An alternative approach, possibly less work and overall of more value, would be to implement <code>AuthenticationSessionStrategy</code> for oAuth, in other words allow users to use their existing Google or Facebook account.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The following steps sketch out the solution in a little more detail:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Define some new Restful resources (cf <a href="https://github.com/apache/isis/blob/master/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/DomainObjectResourceServerside.java"><code>DomainServiceResourceServerside</code></a> that correspond to sign-up/register page, eg <code>SignupResource</code><br></p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Path("/signup") |
| public class SignupResource { |
| ... |
| }</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Create a new subclass of <code>RestfulObjectsApplication</code>, eg "CustomRestfulObjectsApplication" and register your resources<br></p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class CustomRestfulObjectsApplication extends RestfulObjectsApplication { |
| public CustomRestfulObjectsApplication() { |
| addClass(SignupResource.class); |
| } |
| }</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Register your application class in <code>web.xml</code> instead of the default:<br></p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><context-param> |
| <param-name>javax.ws.rs.Application</param-name> |
| <param-value>com.mycompany.myapp.CustomRestfulObjectsApplication</param-value> |
| </context-param></code></pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>So far this is just standard javax.rs stuff.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Next, we need to ensure that a client can hit your new resource <strong>with</strong> the Apache Isis runtime in place, but without there being an Apache Isis session. For that…​.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>create a subclass of the <code>AuthenticationSessionStrategy</code> that automatically returns a dummy session if the resource being accessed is "/restful/signup", say. <br></p> |
| <div class="paragraph"> |
| <p>You could do this by subclassing <code>AuthenticationSessionStrategyBasicAuth</code>, but then using code from <code>AuthenticationSessionStrategyBasicAuth</code> to return an "exploration" (or better, "signup") session if accessing the "/restful/signup" resource.</p> |
| </div> |
| </li> |
| <li> |
| <p>in the <code>SignUpResource</code> resource, you can then do a lookup of the <code>UserRegistrationService</code> in order to allow the user to be created:<br></p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">final UserRegistrationService userRegistrationService = |
| IsisContext.getPersistenceSession().getServicesInjector().lookupService(UserRegistrationService.class); |
| userRegistrationService.registerUser(userDetails);</code></pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Obviously the methods exposed by the <code>SignupResource</code> are up to you; ultimately they need to be able to gather information to populate the <code>UserDetails</code> object as passed to the <code>UserRegistrationService</code>.</p> |
| </div> |
| </div> |
| </div> |
| </article> |
| <aside class="article-aside toc hide-for-print" role="navigation"> |
| <p class="toc-title">On this page</p> |
| <div id="article-toc"></div> |
| </aside> |
| </main> |
| </div> |
| <footer class="footer"> |
| <div class="content"> |
| <div class="copyright"> |
| <p> |
| Copyright © 2010~2020 The Apache Software Foundation, licensed under the Apache License, v2.0. |
| <br/> |
| Apache, the Apache feather logo, Apache Isis, and the Apache Isis project logo are all trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| <div class="revision"> |
| <p>Revision: SNAPSHOT</p> |
| </div> |
| </div> |
| </footer> |
| <script src="../../_/js/site.js"></script> |
| <script async src="../../_/js/vendor/highlight.js"></script> |
| <script src="../../_/js/vendor/jquery-3.4.1.min.js"></script> |
| <script src="../../_/js/vendor/jquery-ui-1.12.1.custom.widget-only.min.js"></script> |
| <script src="../../_/js/vendor/jquery.tocify.min.js"></script> |
| |
| <script> |
| $(function() { |
| $("#article-toc").tocify( { |
| showEffect: "slideDown", |
| hashGenerator: "pretty", |
| hideEffect: "slideUp", |
| selectors: "h2, h3", |
| scrollTo: 120, |
| smoothScroll: true, |
| theme: "jqueryui", |
| highlightOnScroll: true |
| } ); |
| }); |
| </script> |
| |
| <script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script> |
| <script> |
| function focusSearchInput () { document.querySelector('#algolia-search-input').focus() } |
| var search = docsearch({ |
| appId: '5ISP5TFAEN', |
| apiKey: '0fc51c28b4ad46e7318e96d4e97fab7c', |
| indexName: 'isis-apache-org', |
| inputSelector: '#algolia-search-input', |
| autocompleteOptions: { hint: false, keyboardShortcuts: ['s'] }, |
| debug: false, |
| }).autocomplete |
| search.on('autocomplete:closed', function () { search.autocomplete.setVal() }) |
| focusSearchInput() |
| window.addEventListener('load', focusSearchInput); |
| </script> |
| |
| <!-- |
| docsearch options: |
| https://docsearch.algolia.com/docs/behavior/ |
| --> |
| <!-- |
| https://www.algolia.com/doc/api-reference/api-parameters/ |
| algoliaOptions: { hitsPerPage: 6 }, |
| --> |
| </body> |
| </html> |
