Usage by Apache Isis' Viewers

TODO: this content has not yet been reviewed/updated for v2.0

By and large the security mechanisms within Isis are transparent to the rest of the framework. That said, it is the responsibility of the viewers to ensure that for each request there is a valid user session present. The sections below explain how this works.

the content below also appears in the respective user guides for the Web UI (Wicket viewer) and the REST API (Restful Objects viewer).

Wicket Viewer

The Web UI (Wicket viewer) defines a relatively small number of pages (subclasses of org.apache.wicket.markup.html.WebPage). There are two main groups:

  • subclasses of PageAbstract, and

  • subclasses of AccountManagementPageAbstract

The subclasses of PageAbstract are annotated with the Wicket annotation:

@AuthorizeInstantiation("org.apache.isis.viewer.wicket.roles.USER")

which means that they can only be accessed by a user with an authenticated session that has this special, reserved role. If not, Wicket will automatically redirect the user to the sign-in page.

In the sign-in page the viewer calls to the Authenticator API, and obtains back a user/role. It also adds in its special reserved role (per the annotation above) and then continues on to whichever page the user was attempting to access (usually the home page).

And that’s really all there is to it. When the viewer renders a domain object it queries the Apache Isis metamodel, and suppresses from the view any object members (properties, actions etc) that are invisible. These may be invisible because the user has no (read ) permission, or they may be invisible because of domain object logic (eg a hideXxx() method). The viewer neither knows nor cares.

Similarly, for those object members that are visible, the viewer also checks if they are enabled or disabled. Again, an object member will be disabled if the user does not have (write) permission, or it could be disabled because of domain object logic (eg a disableXxx() method).

User-registration

As well as providing a sign-in screen, the Wicket viewer also provides the ability for users to self-register. By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered without there being any current user session. These pages all "reach inside" Apache Isis framework in order to actually do their stuff.

User registration is only available if the UserRegistrationService is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.

Because Shiro realms are pluggable, the Apache Isis framework does not provide default implementations of this service. However, if you are using the SecMan extension, then this module does provide an implementation (that, as you might expect, creates new "user" domain entities).

Restful Objects Viewer

The REST API (Restful Objects viewer) does not provide a login page. Instead it defines the authentication strategy SPI, delegated to by a filter. (For more detail on how this is wired together, see the implementation of the WebModuleJaxrsResteasy4 web module service).

The SPI is:

where Authentication represents a signed-on user.

The strategy is defined using this configuration property:

The framework currently provides only HTTP Basic Auth support as a simple implementation, this is also the default strategy if none is explicitly configured.