Screenshot Tutorial
The following screenshots show an example app's usage of the module, which includes all the services and entities
(users, roles, permissions etc)
provided by the module itself. This example app's domain
also has its own very simple ExampleEntity entity and corresponding repository.
The screenshots are a bit of a nasty mix of 1.7.0 and 1.8.0-SNAPSHOT; haven't got around to updating them all...
The security module provides a number of menus: Users, Roles, Features, Permissions and User Tenancies.
When the security module starts up, it will automatically seed a number of roles, corresponding permissions and a default 'admin' user.
The isis-module-security-admin role grants all permissions to all classes in the security module itself:
The isis-module-security-regular-user role grants selected permissions to the ApplicationUser class:
Permissions created at the package level apply to all classes in all packages and subpackages (that is, recursively).
Permissions can either grant (allow) access or prevent (veto) access. If a user has permissions that contradict each other (for example, they are a member of "roleA" that allows the permission, but also of "roleB" that vetoes the permission) then by default the allow wins. However, this is strategy is pluggable, and the security module can be configured such that a veto would override an allow if required.
For a property, "changing" means being able to edit it. For a collection, "changing" means being able to add or remove from it. For an action, "changing" means being able to invoke it.
Note that Isis' Wicket viewer currently does not support the concept of "changing" collections; the work-around is instead create a pair of actions to add/remove instead. This level of control is usually needed anyway.
An allow/changing permission naturally enough implies allow/viewing, while conversely and symmetrically veto/viewing permission implies veto/changing.
The list of packages is derived from Isis' own metamodel.
Permissions defined at the class level take precedence to those defined at the package level. For example, a user might have allow/viewing at a parent level, but have this escalated to allow/changing for a particular class. Conversely, the class-level permission might veto access.
Select classes within package:
Permissions can also be defined at the member level: action, property or collection. These override permissions defined at either the class- or package-level.
For example, to add a permission for an individual action:
The package list is then filtered to those that contain classes that have actions:
And then select the action:
Similarly, to add a permission to a property; only those classes with properties are shown (so no domain services):
And similarly, adding a collection; again the package list is filtered to those classes that actually have collections.
A common approach to set up security is to define broad-brush allow/viewing or allow/changing permissions at the package level, then fine-tune using targetted veto/changing rule or even veto/viewing permissions at the class- or member-level.
As you would expect, permissions can be removed:
However, the system guards against the accidental removal of certain permissions from the isis-module-security-admin
that might cause the security system from becoming inaccessible.
To remove, specify the permission's rule, type and feature:
Once a roles' permissions are defined, users (discussed in more detail below) can be added to the role:
It's also possible to add roles to a user (from the page representing the ApplicationUser object).
The role's permissions can be navigated to...
... where each permission simply holds the role, rule, mode and feature. The role, rule and mode can be changed but the feature cannot.
It can, however, be navigated to...
Class members (action, property or collection) lists the permissions defined against that member:
It provides access in turn to the parent (class) feature...
The class feature lists associated permissions (if any), also the child properties, collections and actions:
It also provides access to its parent (package) feature ...
The package feature lists its associated permissions (if any), its contents (class or package features) and also provides access to its parent (package) feature.
The security module provides an implementation of the Shiro realm interface, IsisModuleSecurityRealm - intended for both authentication and authorization. Optionally a delegateAuthenticationRealm can be configured; if so then any ApplicationUsers with a delegated account type will be authenticated through the delegate authentication realm.
If configured without a delegate realm, then the users must be created by the administrator. If configured with a delegate realm, then the user will be created automatically if that user attempts to log on. However, for safety their ApplicationUser accounts are created in a disabled state and with no roles, so the administrator is still required to update them.
To create a new local user:
The minimum information held for users its just the username; this corresponds to the name used to log in to Isis via Shiro. Optionally the administrator can specify the user's initial password, role and whether the user is disabled (that is, their account is locked):
Once the user is created, then additional information about that user can be captured, including their name and contact details. This information is not otherwise used by the security module, but may be of use to other parts of the application. The users' roles and effective permissions are also shown (more discussion on effective permissions below).
To create a new delegated user:
The user details are very similar, only the password property and associated actions are suppressed:
For both local and delegate accounts a user can maintain their own details, but may not alter other users' details. An administrator can alter all details, as well as reset a users' password.
If a user is disabled, then they may not log in. This is useful for temporarily barring access to users without having to change all their roles, for example if they leave the company or go on maternity leave.
Each user can have an associated tenancy, so for example an Italian user sees only Italian data.
(This anticipates support for multi-tenancy within Isis itself, not yet implemented as of 1.6.0).
The effective permissions for each user are listed. This evaluates the roles that the user is in, the permissions of those roles, including all scoping and allow/veto rules.
In the screenshot below, the user shown - by virtue of their membership of the isis-module-security-regular-user
role - has access to selected features of ApplicationUser (plus also for the ExampleEntity domain, as per
screenshots above):
The user's roles can be maintained through the user entity as well as the role entity (above). For example, remove
the isis-module-security-admin role can be added to "sven":
Whenever role membership is changed, the effective permissions for a user are re-evaluated. In the screenshot below, note that "sven" now has access to additional features:
The user permission not only shows whether a user has a permission to a feature, but also indicates the role permission that is allowing/vetoing the ability to view or change the feature.
Cool huh?
The application features that permissions to relate (packages, classes, actions, properties, collections) are built up dynamically from the Isis metamodel.
For example, from the list of classes:
... can then drill down to a particular application class:
As a convenience (development aid) note that action semantics and max length/typical length of string properties are also available for inspection.
From the application class it is possible to navigate up to the parent package:
... or indeed down into any individual class member, eg action:
