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 2021/06/10 05:19:46 UTC
[isis] branch master updated: ISIS-2483: improves docs for secman
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new 49947a2 ISIS-2483: improves docs for secman
49947a2 is described below
commit 49947a238fb03e5c7db58f07d394da7fbbde3309
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Jun 10 06:18:20 2021 +0100
ISIS-2483: improves docs for secman
---
.../adoc/modules/secman/pages/setting-up.adoc | 100 +++++++++++++--------
.../AbstractRoleAndPermissionsFixtureScript.java | 6 ++
.../applib/seed/SeedSecurityModuleService.java | 10 +++
.../scripts/SeedUsersAndRolesFixtureScript.java | 13 +--
.../AbstractUserAndRolesFixtureScript.java | 8 +-
5 files changed, 94 insertions(+), 43 deletions(-)
diff --git a/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc b/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc
index 9fa1c23..5cc54dd 100644
--- a/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc
+++ b/extensions/security/secman/adoc/modules/secman/pages/setting-up.adoc
@@ -137,7 +137,9 @@ This is discussed in more detail <<user-registration-aka-sign-up,below>>.
With SecMan enabled, it will automatically seed a security super-user and a regular role.
It also creates a number of other roles to provide access to specific features of the framework (or its extensions).
-These are summarised here:
+This seeding is performed by the xref:refguide:extensions:index/secman/applib/seed/SeedSecurityModuleService.adoc[SeedSecurityModuleService], which calls xref:refguide:extensions:index/secman/applib/seed/scripts/SeedUsersAndRolesFixtureScript.adoc[SeedUsersAndRolesFixtureScript].
+
+The full list of roles set up is summarised here:
* Available in both production and prototype mode
@@ -178,7 +180,7 @@ Access the swagger UI (from the "Prototyping" menu)
+
Impersonate other users (from the "Prototyping" menu, and mixins)
-The full list can be found by searching for subclasses of `AbstractRoleAndPermissionsFixtureScript`.
+The full list can be found by searching for subclasses of xref:refguide:extensions:index/secman/applib/role/fixtures/ AbstractRoleAndPermissionsFixtureScript.adoc[AbstractRoleAndPermissionsFixtureScript].
== Creating Users
@@ -191,11 +193,62 @@ This will return an xref:refguide:extensions:index/secman/applib/user/dom/Applic
If prototyping with an in-memory database then you will most likely want to set up some fixture scripts to automatically set up application users.
-SecMan automatically seeds the built-in roles and users, so it is only necessary to setup roles and users specific to the application.
+As noted <<default-roles, above>>, SecMan automatically seeds the built-in roles and users, so it is only necessary to set up roles and users specific to the application.
+
+To save some boilerplate, you can subclass:
+
+* xref:refguide:extensions:index/secman/applib/role/fixtures/AbstractRoleAndPermissionsFixtureScript.adoc[AbstractRoleAndPermissionsFixtureScript]
++
+to create a role and associated permissions
+
+* xref:refguide:extensions:index/secman/applib/user/fixtures/AbstractUserAndRolesFixtureScript.adoc[AbstractUserAndRolesFixtureScript]
++
+to create a user and associated roles.
+
+You then will need a way to automatically ensure these users/roles are set up on bootstrapping; this is discussed next.
+
+[#custom-seed-service]
+=== Custom Seed Service
+
+When developing the app you will probably be using the H2 in-memory database, and so you'll want to ensure that the roles and (perhaps) users are automatically seeded into the database.
+Even when running in production with a persistent database, running a default set of fixture scripts may be worthwihle.
+
+One option to setup these users/roles would be to use the xref:refguide:config:sections/isis.testing.adoc#isis.testing.fixtures.initial-script[isis.testing.fixtures.initial-script] configuration property.
+However the purpose of that config property is meant to be to specify a demo scenario for demoing/prototyping, so that's probably not the smartest approach.
+
+Better is to write a little domain service to do the seeding of security data for you.
+The service below will set up the default roles and permissions for the framework's own modules:
+
+[source,java]
+.SeedUsersAndRoles.java
+----
+@Service
+@Order(OrderPrecedence.MIDPOINT + 10)
+@RequiredArgsConstructor(onConstructor_ = {@Inject})
+public class SeedSecurityService {
+
+ private final FixtureScripts fixtureScripts;
+ private final TransactionService transactionService;
+
+ @EventListener(MetamodelEvent.class)
+ public void onMetamodelEvent(final MetamodelEvent event) {
+ if (event.isPostMetamodel()) {
+ runScripts();
+ transactionService.flushTransaction();
+ }
+ }
+
+ private void runScripts() {
+ fixtureScripts.run(new CustomRolesAndUsers());
+ }
+}
+----
+
+where `CustomRolesAndUsers` is a top-level fixture script to set up the application-specific users and roles.
-In addition to the <<default-roles, default roles and users>>, you will of course need to define custom roles/perms for your own application.
+=== Examples
-For example, these scripts can be used to set up access to the domain objects in the xref:docs:starters:helloworld.adoc[HelloWorld] starter app:
+For example, the following scripts could be used to set up access to the domain objects in the xref:docs:starters:helloworld.adoc[HelloWorld] starter app:
* to set up a "user-rw" role with access to everything under the "hello" namespace:
+
@@ -278,38 +331,8 @@ public class UserToRole__joe_UserRw_but_NoDelete
<.> specific access to framework features, see <<default-roles,above>>
-You will probably want to ensure that the roles and (perhaps) users are automatically seeded into the database.
-One option is to use the xref:refguide:config:sections/isis.testing.adoc#isis.testing.fixtures.initial-script[isis.testing.fixtures.initial-script] configuration property, but the purpose of that config property is meant to be to specify a demo scenario for demoing/prototyping.
-
-Better is to write a little domain service to do the seeding of security data for you.
-The service below will set up the default roles and permissions for the framework's own modules:
-
-[source,java]
-.SeedUsersAndRoles.java
-----
-@Service
-@Order(OrderPrecedence.MIDPOINT + 10)
-@RequiredArgsConstructor(onConstructor_ = {@Inject})
-public class SeedSecurityService {
-
- private final FixtureScripts fixtureScripts;
- private final TransactionService transactionService;
-
- @EventListener(MetamodelEvent.class)
- public void onMetamodelEvent(final MetamodelEvent event) {
- if (event.isPostMetamodel()) {
- runScripts();
- transactionService.flushTransaction();
- }
- }
-
- private void runScripts() {
- fixtureScripts.run(new CustomRolesAndUsers());
- }
-}
-----
-
-where `CustomRolesAndUsers` is application-specific, for example:
+To seed in fixture scripts we could create a top-level `CustomRolesAndUsers` script (as mentioned in <<custom-seed-service,above>>).
+This would then look something like:
[source,java]
.CustomRolesAndUsers.java
@@ -327,6 +350,9 @@ public class CustomRolesAndUsers extends FixtureScript {
}
----
+The custom seed service would then ensure that these users/roles existed on startup.
+
+
[#user-registration-aka-sign-up]
== User registration (aka Sign-up)
diff --git a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/role/fixtures/AbstractRoleAndPermissionsFixtureScript.java b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/role/fixtures/AbstractRoleAndPermissionsFixtureScript.java
index de2a33c..5a184eb 100644
--- a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/role/fixtures/AbstractRoleAndPermissionsFixtureScript.java
+++ b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/role/fixtures/AbstractRoleAndPermissionsFixtureScript.java
@@ -30,6 +30,12 @@ import org.apache.isis.testing.fixtures.applib.fixturescripts.FixtureScript;
import lombok.val;
+/**
+ * Convenience fixture script intended to be easily subclassed in order to set up an
+ * {@link org.apache.isis.extensions.secman.applib.role.dom.ApplicationRole} with associated permissions.
+ *
+ * @since 2.x {@index}
+ */
public abstract class AbstractRoleAndPermissionsFixtureScript extends FixtureScript {
@Inject private ApplicationRoleRepository applicationRoleRepository;
diff --git a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/SeedSecurityModuleService.java b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/SeedSecurityModuleService.java
index bdf6947..09ffe08 100644
--- a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/SeedSecurityModuleService.java
+++ b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/SeedSecurityModuleService.java
@@ -34,6 +34,16 @@ import org.apache.isis.testing.fixtures.applib.fixturescripts.FixtureScripts;
import lombok.extern.log4j.Log4j2;
/**
+ * Automatically seeds the built-in roles (and permissions) for both Secman
+ * and any other UI features made available by the other modules.
+ *
+ * <p>
+ * The service just runs the {@link SeedUsersAndRolesFixtureScript} on a callback of {@link MetamodelEvent}.
+ * </p>
+ *
+ * @see SeedUsersAndRolesFixtureScript
+ * @see MetamodelEvent
+ *
* @since 2.0 {@index}
*/
@Service
diff --git a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/scripts/SeedUsersAndRolesFixtureScript.java b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/scripts/SeedUsersAndRolesFixtureScript.java
index 095594b..acc19b1 100644
--- a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/scripts/SeedUsersAndRolesFixtureScript.java
+++ b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/seed/scripts/SeedUsersAndRolesFixtureScript.java
@@ -34,11 +34,14 @@ import org.apache.isis.extensions.secman.applib.role.seed.IsisExtSecmanRegularUs
import org.apache.isis.testing.fixtures.applib.fixturescripts.FixtureScript;
/**
- * This fixture script will be run automatically on start-up by virtue of the fact that the
- * {@link SeedSecurityModuleService} is a
- * {@link org.apache.isis.applib.annotation.DomainService} and calls the setup during its
- * {@link SeedSecurityModuleService#onMetamodelEvent(org.apache.isis.core.metamodel.events.MetamodelEvent) init}
- * ({@link javax.annotation.PostConstruct}) method.
+ * Sets up roles and permissions for both Secman itself and also for all other modules that expose UI features
+ * for use by end-users.
+ *
+ * <p>
+ * This fixture script is run automatically on start-up by the {@link SeedSecurityModuleService}.
+ * </p>
+ *
+ * @see SeedSecurityModuleService
*
* @since 2.0 {@index}
*/
diff --git a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/user/fixtures/AbstractUserAndRolesFixtureScript.java b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/user/fixtures/AbstractUserAndRolesFixtureScript.java
index 9af574b..fb39cf2 100644
--- a/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/user/fixtures/AbstractUserAndRolesFixtureScript.java
+++ b/extensions/security/secman/applib/src/main/java/org/apache/isis/extensions/secman/applib/user/fixtures/AbstractUserAndRolesFixtureScript.java
@@ -32,7 +32,13 @@ import org.apache.isis.testing.fixtures.applib.fixturescripts.FixtureScript;
import lombok.Getter;
-public class AbstractUserAndRolesFixtureScript extends FixtureScript {
+/**
+ * Convenience fixture script intended to be easily subclassed in order to set up an
+ * {@link org.apache.isis.extensions.secman.applib.user.dom.ApplicationUser} with associated roles.
+ *
+ * @since 2.x {@index}
+ */
+public abstract class AbstractUserAndRolesFixtureScript extends FixtureScript {
@Inject private ApplicationUserRepository applicationUserRepository;
@Inject private ApplicationRoleRepository applicationRoleRepository;