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 2022/08/21 12:49:50 UTC
[isis] branch master updated: ISIS-2965: doc improvements.
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 b7ff03639f ISIS-2965: doc improvements.
b7ff03639f is described below
commit b7ff03639f88b8dfa72d2821d76c437750b0e612
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Aug 21 13:33:43 2022 +0100
ISIS-2965: doc improvements.
---
.../components/docs/modules/ROOT/pages/about.adoc | 14 ++--
.../ROOT/partials/module-nav/components.adoc | 6 ++
.../modules/ROOT/partials/extensions.adoc | 2 +-
.../userguide/modules/fun/partials/module-nav.adoc | 23 +++----
cribsheet.adoc | 2 +-
.../adoc/modules/commandlog/pages/about.adoc | 10 +--
.../core/excel/adoc/modules/excel/pages/about.adoc | 11 +++-
.../adoc/modules/executionlog/pages/about.adoc | 5 +-
.../adoc/modules/executionoutbox/pages/about.adoc | 3 +-
.../modules/executionrepublisher/pages/about.adoc | 5 +-
.../adoc/modules/audittrail/pages/about.adoc | 68 ++++++++++----------
.../secman/adoc/modules/secman/pages/about.adoc | 75 ++++++----------------
.../secman/pages/setting-up-with-keycloak.adoc} | 7 +-
.../secman/pages/setting-up-with-shiro.adoc | 68 +++++++++++++++-----
.../pages/setting-up-with-spring-oauth2.adoc | 14 ++--
.../adoc/modules/secman/partials/module-nav.adoc | 2 +
.../adoc/modules/sessionlog/pages/about.adoc | 1 +
.../adoc/modules/shiro-realm-ldap/pages/about.adoc | 4 +-
.../adoc/modules/spring-oauth2/pages/about.adoc | 13 ++--
.../vro/cors/adoc/modules/cors/pages/about.adoc | 53 ++++++++++++++-
.../adoc/modules/exceldownload/pages/about.adoc | 31 ++++++++-
...ava => IsisModuleExtExcelDownloadWicketUi.java} | 2 +-
.../adoc/modules/fullcalendar/pages/about.adoc | 44 ++++++++++++-
...java => IsisModuleExtFullCalendarWicketUi.java} | 2 +-
.../vw/gmap3/adoc/modules/gmap3/pages/about.adoc | 3 +-
.../vw/pdfjs/adoc/modules/pdfjs/pages/about.adoc | 42 +++++++++++-
.../pdfjs/applib/config/PdfJsConfig.java | 8 ++-
.../vw/sse/adoc/modules/sse/pages/about.adoc | 43 ++++++++++++-
security/adoc/modules/ROOT/pages/about.adoc | 21 ++++--
.../adoc/modules/ROOT/partials/extensions.adoc | 1 -
.../src/main/adoc/modules/bypass/pages/about.adoc | 2 +-
.../adoc/modules/bypass/partials/module-nav.adoc | 2 +-
.../main/adoc/modules/keycloak/pages/about.adoc | 4 +-
.../adoc/modules/keycloak/partials/module-nav.adoc | 2 +-
.../src/main/adoc/modules/shiro/pages/about.adoc | 2 +-
.../adoc/modules/shiro/partials/module-nav.adoc | 2 +-
.../src/main/adoc/modules/spring/pages/about.adoc | 4 +-
.../adoc/modules/spring/partials/module-nav.adoc | 2 +-
.../adoc/modules/ROOT/partials/extensions.adoc | 1 -
39 files changed, 419 insertions(+), 185 deletions(-)
diff --git a/antora/components/docs/modules/ROOT/pages/about.adoc b/antora/components/docs/modules/ROOT/pages/about.adoc
index 802f97176d..42fd94fa37 100644
--- a/antora/components/docs/modules/ROOT/pages/about.adoc
+++ b/antora/components/docs/modules/ROOT/pages/about.adoc
@@ -32,8 +32,8 @@ link:https://simpleapp.jpa.isis.incode.work[jpa])
_POMs_
-* xref:docs:parent-pom:about.adoc[Parent POM]
-* xref:docs:mavendeps:about.adoc[Webapp Aggregator POM]
+* xref:docs:parent-pom:about.adoc[Starter (Parent POM)]
+* xref:docs:mavendeps:about.adoc[Webapp (Aggregator POM)]
|
[discrete]
@@ -79,6 +79,12 @@ _Persistence_
* xref:pjpa:ROOT:about.adoc[JPA (EclipseLink)]
* xref:pjdo:ROOT:about.adoc[JDO (DataNucleus)]
+_Security_
+
+* xref:security:bypass:about.adoc[Bypass]
+* xref:security:shiro:about.adoc[Shiro]
+* xref:security:spring:about.adoc[Spring]
+* xref:security:keycloak:about.adoc[Keycloak]
|
@@ -87,11 +93,11 @@ _Persistence_
_For Use in Domain Apps_
-* xref:valuetypes:ROOT:about.adoc[Value Type Catalog]
+* *xref:valuetypes:ROOT:about.adoc[Value Type Catalog]*
_Extending the framework itself_
-* xref:extensions:ROOT:about.adoc[Extensions Catalog]
+* *xref:extensions:ROOT:about.adoc[Extensions Catalog]*
|
diff --git a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc b/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
index e0cb77b980..246b9c7725 100644
--- a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
+++ b/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
@@ -13,3 +13,9 @@
*** xref:pjpa:ROOT:about.adoc[JPA (EclipseLink)]
*** xref:pjdo:ROOT:about.adoc[JDO (DataNucleus)]
+** Security
+
+*** xref:security:bypass:about.adoc[Bypass]
+*** xref:security:shiro:about.adoc[Shiro]
+*** xref:security:spring:about.adoc[Spring]
+*** xref:security:keycloak:about.adoc[Keycloak]
diff --git a/antora/components/userguide/modules/ROOT/partials/extensions.adoc b/antora/components/userguide/modules/ROOT/partials/extensions.adoc
index 26a86515d6..d00da7effd 100644
--- a/antora/components/userguide/modules/ROOT/partials/extensions.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/extensions.adoc
@@ -1,5 +1,5 @@
-include::userguide:excel:partial$module-nav.adoc[]
include::userguide:commandlog:partial$module-nav.adoc[]
+include::userguide:excel:partial$module-nav.adoc[]
include::userguide:executionlog:partial$module-nav.adoc[]
include::userguide:executionoutbox:partial$module-nav.adoc[]
include::userguide:executionrepublisher:partial$module-nav.adoc[]
diff --git a/antora/components/userguide/modules/fun/partials/module-nav.adoc b/antora/components/userguide/modules/fun/partials/module-nav.adoc
index 2578c2645d..5142e9d986 100644
--- a/antora/components/userguide/modules/fun/partials/module-nav.adoc
+++ b/antora/components/userguide/modules/fun/partials/module-nav.adoc
@@ -1,15 +1,16 @@
-* xref:userguide:fun:concepts-patterns.adoc[Concepts & Patterns]
-* xref:userguide:fun:overview.adoc[Overview]
-* xref:userguide:fun:domain-entities-and-services.adoc[Domain Entities & Services]
-* xref:userguide:fun:object-members.adoc[Properties, Collections & Actions]
-* xref:userguide:fun:ui.adoc[UI Layout & Hints]
-* xref:userguide:fun:business-rules.adoc[Business Rules]
-* xref:userguide:fun:drop-downs-and-defaults.adoc[Drop downs and Defaults]
-* xref:userguide:fun:meta-annotations.adoc[Meta-annotations]
-* xref:userguide:fun:view-models.adoc[View Models]
-* xref:userguide:fun:mixins.adoc[Mixins]
-* xref:userguide:fun:modules.adoc[Modules]
+* xref:userguide:fun:about.adoc[]
+** xref:userguide:fun:concepts-patterns.adoc[Concepts & Patterns]
+** xref:userguide:fun:overview.adoc[Overview]
+** xref:userguide:fun:domain-entities-and-services.adoc[Domain Entities & Services]
+** xref:userguide:fun:object-members.adoc[Properties, Collections & Actions]
+** xref:userguide:fun:ui.adoc[UI Layout & Hints]
+** xref:userguide:fun:business-rules.adoc[Business Rules]
+** xref:userguide:fun:drop-downs-and-defaults.adoc[Drop downs and Defaults]
+** xref:userguide:fun:meta-annotations.adoc[Meta-annotations]
+** xref:userguide:fun:view-models.adoc[View Models]
+** xref:userguide:fun:mixins.adoc[Mixins]
+** xref:userguide:fun:modules.adoc[Modules]
diff --git a/cribsheet.adoc b/cribsheet.adoc
index 8abf63beba..36c854d531 100644
--- a/cribsheet.adoc
+++ b/cribsheet.adoc
@@ -1,6 +1,6 @@
= Cribsheet
-... of sometimes used scripts.
+\... of sometimes used scripts.
== Rebuild documentation from scratch
diff --git a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc
index b41570435b..0a5375734d 100644
--- a/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc
+++ b/extensions/core/commandlog/adoc/modules/commandlog/pages/about.adoc
@@ -4,17 +4,9 @@
:Notice: 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 ag [...]
-WARNING: TODO: v2 - to fully document
-
The _commandlog_ module provides an implementation that persists xref:refguide:applib:index/services/command/Command.adoc[Command]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store.
-//It further provides a number of supporting services:
-//
-//* `org.isisaddons.module.command.dom.CommandServiceJdoRepository` is a repository to search for persisted xref:refguide:applib:index/services/command/Command.adoc[Command]s
-//
-//* `org.isisaddons.module.command.dom.CommandServiceJdoContributions` contributes actions for searching for persisted child and sibling xref:refguide:applib:index/services/command/Command.adoc[Command]s.
-//
-//If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:userguide:btb:hints-and-tips.adoc#vetoing-visibility[vetoing subscriber].
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/core/excel/adoc/modules/excel/pages/about.adoc b/extensions/core/excel/adoc/modules/excel/pages/about.adoc
index d06691982b..a3702932b1 100644
--- a/extensions/core/excel/adoc/modules/excel/pages/about.adoc
+++ b/extensions/core/excel/adoc/modules/excel/pages/about.adoc
@@ -2,4 +2,13 @@
:Notice: 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 ag [...]
-WARNING: TODO
+The Excel Library provides the ability to read from Excel spreadsheets, which can be useful for certain use cases, eg bulk import of data.
+Each row of a spreadsheet can be mapped to a domain object, usually a view model.
+The view model can validate itself and then apply
+
+The library also provides the opposite use case, converting a collection of domain objects into an Excel spreadsheet.
+
+In addition, the library provides fixture support, allowing test data to be specified in a spreadsheet.
+
+
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc
index ed8a4068d4..0f81434e63 100644
--- a/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc
+++ b/extensions/core/executionlog/adoc/modules/executionlog/pages/about.adoc
@@ -4,8 +4,9 @@
:Notice: 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 ag [...]
-WARNING: TODO: v2 - to properly document.
-
The _executionlog_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store.
+WARNING: TODO: v2 - to write up...
+
+
diff --git a/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc b/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc
index 8d7410836b..18fca21305 100644
--- a/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc
+++ b/extensions/core/executionoutbox/adoc/modules/executionoutbox/pages/about.adoc
@@ -4,7 +4,7 @@
:Notice: 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 ag [...]
-WARNING: TODO: v2 - to properly document.
+
The _executionoutbox_ module provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s into an "outbox" (using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store).
The purpose of the "outbox" is to act as a temporary store of executions to be propogated to other "downstream" systems.
@@ -14,3 +14,4 @@ The client polls the outbox through the REST API (for example every 15 seconds),
Once processed (eg published to a message bus), the client then uses the same REST API to delete the executions.
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc b/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc
index 19dfb6bbef..ddf0d4aca1 100644
--- a/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc
+++ b/extensions/core/executionrepublisher/adoc/modules/executionrepublisher/pages/about.adoc
@@ -4,6 +4,7 @@
:Notice: 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 ag [...]
-WARNING: TODO: v2 - to properly document.
-The _executionrepublisher_ module contributes an action to allow logged executions (as per the xref:userguide:executionlog:about.adoc[] module to be republished to the outbox (as per the xref:userguide:executionoutbox:about.adoc[module]).
+The _executionrepublisher_ module contributes an action to allow logged executions (as per the xref:userguide:executionlog:about.adoc[] module) to be republished to the outbox (as per the xref:userguide:executionoutbox:about.adoc[] modul).
+
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc b/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc
index 2a46931887..7bf84fdd74 100644
--- a/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc
+++ b/extensions/security/audittrail/adoc/modules/audittrail/pages/about.adoc
@@ -1,37 +1,39 @@
-= Auditer
+= Audit Trail
:Notice: 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 ag [...]
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
-
-
-The xref:security:audittrail:about.adoc[Auditer] module provides an implementation of the xref:refguide:applib:index/services/publishing/spi/EntityPropertyChangeSubscriber.adoc[EntityPropertyChangeSubscriber], as well as a number of related domain services,
-It creates an audit record for each changed property (ie every time that `AuditerService#audit(...)` is called.
-
-The module also provides:
-
-* `AuditingServiceMenu` service which provides actions to search for ``AuditEntry``s, underneath an 'Activity' menu on the secondary menu bar.
-
-* `AuditingServiceRepository` service to to search for persisted `AuditEntry``s.
-None of its actions are visible in the user interface (they are all `@Programmatic`).
-
-* `AuditingServiceContributions` which contributes collections to the xref:refguide:applib-classes:mixees-and-mixins.adoc[HasInteractionId] interface.
-This will therefore display all audit entries that occurred in a given request/transaction, in other words whenever a command, a published event or another audit entry is displayed.
-
-These services can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-
-If menu items or contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:userguide:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
-
-== Usage
-
-The typical way to indicate that an object should be audited is to annotate it with the xref:refguide:applib:index/annotation/DomainObject.adoc#auditing[@DomainObject#auditing()] annotation.
-
-
-== Related Services
-
-The auditing service works very well with implementations of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persist the ``Execution`` objects obtained from the xref:refguide:applib:index/services/iactnlayer/InteractionContext.adoc[InteractionContext] service.
-The interaction execution captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `EntityPropertyChangeSubscriber` audit entries capture the _effect_ of that interaction in terms of changed state.
-
-The xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] SPI can also be combined with the audit trail service, where the xref:refguide:applib:index/services/command/Command.adoc[Command] capturesthe _intent_ of an action, not the actual action invocation itself.
-
+The xref:security:audittrail:about.adoc[] module provides an implementation of the xref:refguide:applib:index/services/publishing/spi/EntityPropertyChangeSubscriber.adoc[EntityPropertyChangeSubscriber], as well as a number of related domain services,
+It creates an audit record for each changed property of each domain entity.
+
+WARNING: TODO: v2 - to write up...
+
+// following material out of date:
+//
+//The module also provides:
+//
+//* `AuditingServiceMenu` service which provides actions to search for ``AuditEntry``s, underneath an 'Activity' menu on the secondary menu bar.
+//
+//* `AuditingServiceRepository` service to to search for persisted `AuditEntry``s.
+//None of its actions are visible in the user interface (they are all `@Programmatic`).
+//
+//* `AuditingServiceContributions` which contributes collections to the xref:refguide:applib-classes:mixees-and-mixins.adoc[HasInteractionId] interface.
+//This will therefore display all audit entries that occurred in a given request/transaction, in other words whenever a command, a published event or another audit entry is displayed.
+//
+//These services can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
+//
+//If menu items or contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:userguide:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+//
+//== Usage
+//
+//The typical way to indicate that an object should be audited is to annotate it with the xref:refguide:applib:index/annotation/DomainObject.adoc#auditing[@DomainObject#auditing()] annotation.
+//
+//
+//== Related Services
+//
+//The auditing service works very well with implementations of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persist the ``Execution`` objects obtained from the xref:refguide:applib:index/services/iactnlayer/InteractionContext.adoc[InteractionContext] service.
+//The interaction execution captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `EntityPropertyChangeSubscriber` audit entries capture the _effect_ of that interaction in terms of changed state.
+//
+//The xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] SPI can also be combined with the audit trail service, where the xref:refguide:applib:index/services/command/Command.adoc[Command] capturesthe _intent_ of an action, not the actual action invocation itself.
+//
+//
diff --git a/extensions/security/secman/adoc/modules/secman/pages/about.adoc b/extensions/security/secman/adoc/modules/secman/pages/about.adoc
index 8e6c23ffa4..a20e025f95 100644
--- a/extensions/security/secman/adoc/modules/secman/pages/about.adoc
+++ b/extensions/security/secman/adoc/modules/secman/pages/about.adoc
@@ -3,27 +3,24 @@
:Notice: 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 ag [...]
-SecMan provides an implementation of the xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] SPI, to determine whether the currently logged-in user has access to a given object member
+SecMan provides an implementation of both the xref:refguide:core:index/security/authentication/Authenticator.adoc[Authenticator] and xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] SPIs, storing user, roles and permissions information as domain entities (persisted to relational database).
+It can be used with both the JDO or JPA persistence mechanisms.
-This authorization is implemented using domain entities, which means that authorizations/permissions can then be administered from within your Apache Isis application.
-Moreover, the set of permissions (to features) is derived completely from your application's metamodel; in essence the permissions are "type-safe".
+Because these features are implemented using domain entities, it means that this security information can be administered from within your Apache Isis application.
The domain model is explained in more detail <<domain-model,below>>.
-SecMan can be used just for authorization, or it can be used in conjunction with Apache Isis' xref:security:shiro:about.adoc[Shiro security] implementation to perform authentication, where a password is held for each application user.
-This integration is discussed in more detail <<shiro-integration,below>>.
-
-This guide explains these concepts in more detail, and describes how to configure secman for use.
+If SecMan is used for authentication, user/passwords are stored in encrypted form using a configured `PasswordEncoder`.
+The framework ships with xref:refguide:extensions:index/secman/encryption/jbcrypt/services/PasswordEncoderUsingJBcrypt.adoc[] that uses the link:https://www.mindrot.org/projects/jBCrypt/[jBCrypt] library.
+Authorization is supported by associating users to roles, where each role has a set of permissions.
+Permissions can be defined at different scopes, and can either allow or veto access to the underlying feature.
+The set of permissions (to features) is derived completely from your application's metamodel; in essence the permissions are "type-safe".
-== Users, Roles and Permissions
-
-As described in the introduction, the primary purpose of SecMan is to provide an implementation of the xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] SPI, to determine whether the currently logged-in user has access to a given object member:
-
-* the logged-in user is represented as an xref:refguide:applib:index/services/iactnlayer/InteractionContext.adoc[InteractionContext]
+SecMan can be used just for authorization, or it can be used in conjunction with any of the other xref:refguide:core:index/security/authentication/Authenticator.adoc[Authenticator] implementations, for example xref:security:shiro:about.adoc[Shiro], xref:security:spring:about.adoc[Spring] or xref:security:keycloak:about.adoc[Keycloak].
+This integration is discussed in more detail <<shiro-integration,below>>.
-* by "object member" we mean either an action, property or collection,as represented by an xref:refguide:applib:index/Identifier.adoc[Identifier]
-* by "access", we mean whether the object member is xref:refguide:core:index/security/authorization/Authorizor.adoc#isVisible__InteractionContext_Identifier] to the user, and if so whether it is xref:refguide:core:index/security/authorization/Authorizor.adoc#isUsable_InteractionContext_Identifier[usable] (not disabled) by the user.
+== Users, Roles and Permissions
SecMan's xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] implementation uses domain entities to model users, roles and permissions.
Each permission relates to an "object feature".
@@ -33,14 +30,14 @@ Object features themselves come in three varieties:
+
for example `myapp.customer.CustomerAddress#zipCode`
-* next up is an object feature representing an entire type
+* next up is an object feature representing an entire type, described using its logical type name.
+
for example `myapp.customer.CustomerAddress`.
-This is usually specified using xref:refguide:applib:index/annotation/DomainObject.adoc#logicalTypeName[@DomainObject#logicalTypeName()]
+This is usually specified using the `@javax.inject.Named` annotation.
* most general is an object feature representing a namespace
+
-These consist of the portion of the xref:refguide:applib:index/annotation/DomainObject.adoc#logicalTypeName[logical type name] up to but excluding the local type name, for example `myapp.customer`.
+These consist of the portion of the logical type name up to but excluding the local type name, for example `myapp.customer`.
Permissions are inferred: a permission granted at the type level implies a permission to all the object members of the type, and a permission granted to a namespace implies a permission to all the object members of all the object types within that namespace.
@@ -215,49 +212,19 @@ Another option again is rather simple: just run multiple instances of the applic
-[#shiro-integration]
-== Shiro Integration
-
-While SecMan is primarily designed for authorization (as per the xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] SPI), it is necessary when running an Apache Isis application to specify an authenticator.
-SecMan provides specific support so that Apache Isis' xref:security:shiro:about.adoc[Shiro security] integration can be used for authentication.
-
-This is implemented through the SecMan's shiro realm submodule, which provides an implementation of Apache Shiro's `Realm` interface that then calls back into SecMan.
-
-The diagram below sketches the high-level architecture:
-
-.SecMan's Shiro architecture
-image:secman-shiro-architecture.drawio.svg[]
-
-Thus:
-
-* Apache Isis' xref:security:shiro:about.adoc[Shiro security] integration sets up Shiro web filters to intercept every http request, as well as the xref:refguide:security:index/shiro/authentication/AuthenticatorShiro.adoc[AuthenticatorShiro] implementation.
-* The `AuthenticatorShiro` calls to the Shiro Security Manager to obtain the authenticated principal.
-* The Shiro Security Manager uses the `shiro.ini` configuration file to look up the realm to perform the authentication; in this case we configure it to use Secman's realm (xref:refguide:extensions:index/secman/shiro/IsisModuleExtSecmanShiroRealm.adoc[IsisModuleExtSecmanShiroRealm]).
-* Secman's realm implementation queries the database and uses this to create an instance of `PrincipalForApplicationUser`, where the `Principal` interface is Shiro's representation of an authenticated user.
-The `PrincipalForApplicationUser` is backed by xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser], which all of the permissions to object members for this particular user.
-* to render a page, the Apache Isis viewer uses configured `Authorizor`, in this case
-Secman's own xref:refguide:extensions:index/secman/integration/authorizor/AuthorizorSecman.adoc[AuthorizorSecman].
-This looks up the current xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser] (which will already reside in-memory) and renders the page according to which object members are visible or not.
-
-
-The above configuration allows Secman to be used to authenticate users; the password is stored as an (typically) encrypted property of the xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser].
-These are called "local" users, as per the xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser]'s `accountType` property.
-
-Secman's xref:refguide:extensions:index/secman/shiro/IsisModuleExtSecmanShiroRealm.adoc[Realm implementation] also allows a "delegate" realm to be configured.
-In such cases the authentication of "delegated" users is performed by the delegate realm rather than locally.
+== Password encryption
-The diagram below shows where this delegation occurs:
+Secman leverages Spring's `org.springframework.security.crypto.password.PasswordEncoder` SPI to allow different algorithms to encrypt the user's password.
-.SecMan's Shiro delegate architecture
-image:secman-shiro-delegate-architecture.drawio.svg[]
+The `encryption-jbcrypt` module provides an implementation using the link:https://www.mindrot.org/projects/jBCrypt/[jBCrypt] library.
-Configuring the delegate realm is performed using Shiro's "poor man's dependency injection" syntax in its `shiro.ini` file.
-== Password encryption
+[#shiro-integration]
+== Using other Authenticators
-Secman leverages Spring's `org.springframework.security.crypto.password.PasswordEncoder` SPI to allow different algorithms to encrypt the user's password.
+While SecMan does provide an implementation of the xref:refguide:core:index/security/authentication/Authenticator.adoc[] SPI, it's also possible to use an alternative `Authenticator` implementation, for example as provided by xref:security:shiro:about.adoc[Apache Shiro], xref:security:spring:about.adoc[Spring] or xref:security:keycloak:about.adoc[Keycloak].
-The `encryption-jbcrypt` module provides an implementation using the link:https://www.mindrot.org/projects/jBCrypt/[jBCrypt] library.
+For more details, see xref:security:secman:setting-up-with-shiro.adoc[], xref:setting-up-with-spring-oauth2.adoc[] and xref:setting-up-with-keycloak.adoc[].
== SecMan's structure
diff --git a/extensions/vw/exceldownload/adoc/modules/exceldownload/pages/about.adoc b/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-keycloak.adoc
similarity index 76%
copy from extensions/vw/exceldownload/adoc/modules/exceldownload/pages/about.adoc
copy to extensions/security/secman/adoc/modules/secman/pages/setting-up-with-keycloak.adoc
index d890a70b1c..3c8be89427 100644
--- a/extensions/vw/exceldownload/adoc/modules/exceldownload/pages/about.adoc
+++ b/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-keycloak.adoc
@@ -1,6 +1,9 @@
-= Excel Download
+= Setting up with Keycloak
:Notice: 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 ag [...]
+:page-partial:
+This section describes how to setup and configure SecMan authorizor combined with xref:security:keycloak:about.adoc[Keycloak] being used as the authenticator.
+
+WARNING: TODO: v2 - to write up...
-WARNING: TODO
diff --git a/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-shiro.adoc b/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-shiro.adoc
index 7792ebeeb2..7f88a63c1f 100644
--- a/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-shiro.adoc
+++ b/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-shiro.adoc
@@ -3,14 +3,49 @@
:Notice: 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 ag [...]
:page-partial:
-This section describes how to setup and configure SecMan with framework's xref:security:shiro:about.adoc[Shiro integration] being used for primary authentication.
+This section describes how to set up and configure SecMan as an xref:refguide:core:index/security/authorization/Authorizor.adoc[], with framework's xref:security:shiro:about.adoc[Shiro integration] being used as the xref:refguide:core:index/security/authentication/Authenticator.adoc[].
The primary use case this enables is for authentication to be performed through an external mechanism, for example LDAP.
+This is implemented through the SecMan's shiro realm submodule, which provides an implementation of Apache Shiro's `Realm` interface that then calls back into SecMan.
-If delegate authentication has been set up, this means that authentication may pass for a user that Secman knows nothing about.
-In this case Secman will automatically create an `ApplicationUser` for this externally delegated authenticated user, with its `type` set to "DELEGATED".
+== Local Authentication
+
+The diagram below sketches the high-level architecture:
+
+.SecMan with Shiro local authentication
+image:secman-shiro-architecture.drawio.svg[]
+
+Thus:
+
+* Apache Isis' xref:security:shiro:about.adoc[Shiro security] integration sets up Shiro web filters to intercept every http request, as well as the xref:refguide:security:index/shiro/authentication/AuthenticatorShiro.adoc[AuthenticatorShiro] implementation.
+* The `AuthenticatorShiro` calls to the Shiro Security Manager to obtain the authenticated principal.
+* The Shiro Security Manager uses the `shiro.ini` configuration file to look up the realm to perform the authentication; in this case we configure it to use Secman's realm (xref:refguide:extensions:index/secman/shiro/IsisModuleExtSecmanShiroRealm.adoc[IsisModuleExtSecmanShiroRealm]).
+* Secman's realm implementation queries the database and uses this to create an instance of `PrincipalForApplicationUser`, where the `Principal` interface is Shiro's representation of an authenticated user.
+The `PrincipalForApplicationUser` is backed by xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser], which all of the permissions to object members for this particular user.
+* to render a page, the Apache Isis viewer uses configured `Authorizor`, in this case
+Secman's own xref:refguide:extensions:index/secman/integration/authorizor/AuthorizorSecman.adoc[AuthorizorSecman].
+This looks up the current xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser] (which will already reside in-memory) and renders the page according to which object members are visible or not.
+
+
+The above configuration allows Secman to be used to authenticate users; the password is stored as an (typically) encrypted property of the xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser].
+These are called "local" users, as per the xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[ApplicationUser]'s `accountType` property.
+
+
+== Delegate Authentication
+
+Local authentication - as described in the previous section - does not actually accomplish much; although Shiro's `Authenticator` implementation is in use, since the Shiro Realm just queries the SecMan database, there is no real difference from simply using SecMan's own `Authenticator` impplementation.
+
+Where things become more interesting and useful is that Secman's xref:refguide:extensions:index/secman/shiro/IsisModuleExtSecmanShiroRealm.adoc[Realm implementation] also allows a "delegate" realm to be configured, meaning that an additional alternative Realm (eg LDAP) can be queried.
+In such cases Shiro can obtain authentication of "delegated" users is performed by the delegate realm rather than locally.
+
+The diagram below shows where this delegation occurs:
+
+.SecMan with Shiro delegate authentication
+image:secman-shiro-delegate-architecture.drawio.svg[]
+
+When a delegate realm is configured, an `ApplicationUser` entity can be automatically created in the SecMan database for an external user.
+Secman can be configured so that these users are either locked or unlocked by default, as required, see xref:#configure-properties[below].
-The integration _does_ still allow for local logins (`type` set to "LOCAL") of ``ApplicationUser``s if required.
== Dependencies
@@ -21,18 +56,18 @@ In addition to the xref:setting-up.adoc#dependencies[regular dependencies] requi
.pom.xml
----
<dependencies>
- <dependency>
- <groupId>org.apache.isis.extensions</groupId>
- <artifactId>isis-extensions-secman-persistence-XXX</artifactId> <!--.-->
- </dependency>
- <dependency>
- <groupId>org.apache.isis.extensions</groupId>
- <artifactId>isis-extensions-secman-encryption-jbcrypt</artifactId> <!--.-->
- </dependency>
- <dependency>
- <groupId>org.apache.isis.extensions</groupId>
- <artifactId>isis-extensions-secman-shiro-realm</artifactId>
- </dependency>
+ <dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-secman-persistence-XXX</artifactId> <!--.-->
+ </dependency>
+ <dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-secman-encryption-jbcrypt</artifactId> <!--.-->
+ </dependency>
+ <dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-secman-shiro-realm</artifactId>
+ </dependency>
</dependencies>
----
<.> specify either `isis-extensions-secman-persistence-jpa` or `isis-extensions-secman-persistence-jdo`, as required
@@ -93,7 +128,6 @@ securityManager.realms = $isisModuleSecurityRealm
The `[users]` and `[roles]` sections are required but are unused.
-
The main point of introducing Shiro though is to introduce support for authentication by external mechanisms such as LDAP.
In this case we configure Shiro to use the external realm as the primary realm, with Secman's Shiro realm set up as a "delegate" realm.
We specify the delegate realm implementation in the `shiro.ini` file, and "inject" it into the Secman realm.
diff --git a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc b/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-spring-oauth2.adoc
similarity index 71%
copy from antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
copy to extensions/security/secman/adoc/modules/secman/pages/setting-up-with-spring-oauth2.adoc
index e0cb77b980..2307a5e37c 100644
--- a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
+++ b/extensions/security/secman/adoc/modules/secman/pages/setting-up-with-spring-oauth2.adoc
@@ -1,15 +1,9 @@
+= Setting up with Spring OAuth2
:Notice: 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 ag [...]
+:page-partial:
-* Components
+This section describes how to setup and configure SecMan authorizor combined with xref:security:spring:about.adoc[Spring] being used as the authenticator, configured with xref:security:spring-oauth2:about.adoc[OAuth2].
-** Viewers
-
-*** xref:vw:ROOT:about.adoc[Web UI (Wicket)]
-*** xref:vro:ROOT:about.adoc[REST API (Restful Objects)]
-
-** Persistence
-
-*** xref:pjpa:ROOT:about.adoc[JPA (EclipseLink)]
-*** xref:pjdo:ROOT:about.adoc[JDO (DataNucleus)]
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/security/secman/adoc/modules/secman/partials/module-nav.adoc b/extensions/security/secman/adoc/modules/secman/partials/module-nav.adoc
index 9e8b451837..188208786d 100644
--- a/extensions/security/secman/adoc/modules/secman/partials/module-nav.adoc
+++ b/extensions/security/secman/adoc/modules/secman/partials/module-nav.adoc
@@ -2,3 +2,5 @@
** xref:security:secman:about.adoc[SecMan]
*** xref:security:secman:setting-up.adoc[Setting up]
*** xref:security:secman:setting-up-with-shiro.adoc[Setting up with Shiro]
+*** xref:security:secman:setting-up-with-spring-oauth2.adoc[Setting up with Spring OAuth2]
+*** xref:security:secman:setting-up-with-keycloak.adoc[Setting up with Keycloak]
diff --git a/extensions/security/sessionlog/adoc/modules/sessionlog/pages/about.adoc b/extensions/security/sessionlog/adoc/modules/sessionlog/pages/about.adoc
index e5223dab90..1ccb4c0f49 100644
--- a/extensions/security/sessionlog/adoc/modules/sessionlog/pages/about.adoc
+++ b/extensions/security/sessionlog/adoc/modules/sessionlog/pages/about.adoc
@@ -6,3 +6,4 @@ The Session Log extension provides an implementation of the xref:refguide:applib
When a user logs on, a `SessionLogEntry` instance is persisted; when they log off, the same instance is updated.
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/security/shiro-realm-ldap/adoc/modules/shiro-realm-ldap/pages/about.adoc b/extensions/security/shiro-realm-ldap/adoc/modules/shiro-realm-ldap/pages/about.adoc
index 27e829f255..7c3aa555ae 100644
--- a/extensions/security/shiro-realm-ldap/adoc/modules/shiro-realm-ldap/pages/about.adoc
+++ b/extensions/security/shiro-realm-ldap/adoc/modules/shiro-realm-ldap/pages/about.adoc
@@ -2,7 +2,6 @@
:Notice: 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 ag [...]
-WARNING: TODO
// see `shiro.ini` (example)
@@ -18,3 +17,6 @@ WARNING: TODO
The Shiro framework also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups.
Apache Isis extends Shiro's implementation this `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
+
+
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/security/spring-oauth2/src/main/adoc/modules/spring-oauth2/pages/about.adoc b/extensions/security/spring-oauth2/src/main/adoc/modules/spring-oauth2/pages/about.adoc
index ecfef161b7..da11cea0cd 100644
--- a/extensions/security/spring-oauth2/src/main/adoc/modules/spring-oauth2/pages/about.adoc
+++ b/extensions/security/spring-oauth2/src/main/adoc/modules/spring-oauth2/pages/about.adoc
@@ -28,7 +28,10 @@ In the webapp module of your application, add the following dependency:
[[_update-appmanifest]]
== Update AppManifest
-In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import `IsisModuleSecuritySpring`, `IsisModuleExtSpringSecurityOAuth2` modules and `AuthorizorShiro`.
+In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import `IsisModuleSecuritySpring` and `IsisModuleExtSpringSecurityOAuth2` modules.
+
+Neither of these modules provide an implementation of the xref:refguide:core:index/security/authorization/Authorizor.adoc[] SPI, so we must also configure one.
+For the purpose of this walkthrough, we'll use the implementation provided by xref:security:shiro:about.adoc[Shiro], namely `AuthorizorShiro`.
[source,java]
.AppManifest.java
@@ -36,17 +39,19 @@ In your application's `AppManifest` (top-level Spring `@Configuration` used to b
@Configuration
@Import({
...
- IsisModuleExtSpringSecurityOAuth2.class,
+ IsisModuleExtSpringSecurityOAuth2.class, // <.>
AuthorizorShiro.class,
...
})
public class AppManifest {
}
----
-
-This module brings in a transitive dependency on `IsisModuleSecuritySpring`, so if that is referenced in the `AppManifest` then it can be removed.
+<.> The `IsisModuleExtSpringSecurityOAuth2` module brings in a transitive dependency on `IsisModuleSecuritySpring`.
++
Make sure though that no other `IsisModuleSecurityXxx` module is imported.
+It is also possible to use with other `Authorizor` implementations; for example, using xref:security:secman:setting-up-with-spring-oauth2.adoc[SecMan].
+
== Design
diff --git a/extensions/vro/cors/adoc/modules/cors/pages/about.adoc b/extensions/vro/cors/adoc/modules/cors/pages/about.adoc
index 0093c80b98..1d3247c43e 100644
--- a/extensions/vro/cors/adoc/modules/cors/pages/about.adoc
+++ b/extensions/vro/cors/adoc/modules/cors/pages/about.adoc
@@ -2,6 +2,55 @@
:Notice: 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 ag [...]
-WARNING: TODO
-//For more about CORS, see for example link:https://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-definedhttps://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-defined[this blog post at www.moesif.com]
+This extension configures specified CORS headers for the endpoints exposed by the xref:vro:ROOT:about.adoc[].
+
+To learn more about CORS, see for example link:https://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-definedhttps://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-defined[this blog post at www.moesif.com]
+
+
+== Configuration
+
+Add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-cors-impl</artifactId>
+</dependency>
+----
+
+Also add the following module to your `AppManifest`:
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ IsisModuleExtCors.class,
+ ...
+})
+public class AppManifest {
+}
+----
+
+Update the configuration properties:
+
+[source,yml]
+.application.yml
+----
+isis:
+ extensions:
+ cors:
+ allow-credentials: ... # <.>
+ allow-headers: ... # <.>
+ allow-methods: ... # <.>
+ allow-origins: ... # <.>
+ exposed-headers: ... # <.>
+----
+<.> xref:refguide:config:sections/isis.extensions.adoc#isis.extensions.cors.allow-credentials[isis.extensions.cors.allow-credentials]
+<.> xref:refguide:config:sections/isis.extensions.adoc#isis.extensions.cors.allowed-headers[isis.extensions.cors.allow-headers]
+<.> xref:refguide:config:sections/isis.extensions.adoc#isis.extensions.cors.allowed-methods[isis.extensions.cors.allow-methods]
+<.> xref:refguide:config:sections/isis.extensions.adoc#isis.extensions.cors.allowed-origins[isis.extensions.cors.allow-origins]
+<.> xref:refguide:config:sections/isis.extensions.adoc#isis.extensions.cors.exposed-headers[isis.extensions.cors.exposed-headers]
diff --git a/extensions/vw/exceldownload/adoc/modules/exceldownload/pages/about.adoc b/extensions/vw/exceldownload/adoc/modules/exceldownload/pages/about.adoc
index d890a70b1c..7254196e8e 100644
--- a/extensions/vw/exceldownload/adoc/modules/exceldownload/pages/about.adoc
+++ b/extensions/vw/exceldownload/adoc/modules/exceldownload/pages/about.adoc
@@ -3,4 +3,33 @@
:Notice: 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 ag [...]
-WARNING: TODO
+The Excel Download module integrates with the xref:vw:ROOT:about.adoc[Wicket Viewer] to allow any collection to be downloaded as an Excel spreadsheet.
+
+== Configuration
+
+Add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-exceldownload-wicket-ui</artifactId>
+</dependency>
+----
+
+Also add the following module to your `AppManifest`:
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ IsisModuleExtExcelDownloadWicketUi.class,
+ ...
+})
+public class AppManifest {
+}
+----
+
+
diff --git a/extensions/vw/exceldownload/wicket-ui/src/main/java/org/apache/isis/extensions/viewer/wicket/exceldownload/ui/IsisModuleExtExcelDownloadUi.java b/extensions/vw/exceldownload/wicket-ui/src/main/java/org/apache/isis/extensions/viewer/wicket/exceldownload/ui/IsisModuleExtExcelDownloadWicketUi.java
similarity index 96%
rename from extensions/vw/exceldownload/wicket-ui/src/main/java/org/apache/isis/extensions/viewer/wicket/exceldownload/ui/IsisModuleExtExcelDownloadUi.java
rename to extensions/vw/exceldownload/wicket-ui/src/main/java/org/apache/isis/extensions/viewer/wicket/exceldownload/ui/IsisModuleExtExcelDownloadWicketUi.java
index b33b6823b7..14714aab19 100644
--- a/extensions/vw/exceldownload/wicket-ui/src/main/java/org/apache/isis/extensions/viewer/wicket/exceldownload/ui/IsisModuleExtExcelDownloadUi.java
+++ b/extensions/vw/exceldownload/wicket-ui/src/main/java/org/apache/isis/extensions/viewer/wicket/exceldownload/ui/IsisModuleExtExcelDownloadWicketUi.java
@@ -31,5 +31,5 @@ import org.apache.isis.extensions.viewer.wicket.exceldownload.ui.components.Coll
// @Component's
CollectionContentsAsExcelFactory.class
})
-public class IsisModuleExtExcelDownloadUi {
+public class IsisModuleExtExcelDownloadWicketUi {
}
diff --git a/extensions/vw/fullcalendar/adoc/modules/fullcalendar/pages/about.adoc b/extensions/vw/fullcalendar/adoc/modules/fullcalendar/pages/about.adoc
index fc28cd4474..1ed47485ed 100644
--- a/extensions/vw/fullcalendar/adoc/modules/fullcalendar/pages/about.adoc
+++ b/extensions/vw/fullcalendar/adoc/modules/fullcalendar/pages/about.adoc
@@ -1,5 +1,45 @@
-= Fullcalendar
+= Full Calendar
:Notice: 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 ag [...]
-WARNING: TODO
+The Full Calendar module integrates with the xref:vw:ROOT:about.adoc[Wicket Viewer], rendering any collection of domain objects that expose a date to be rendered in a calendar view (using the link:https://fullcalendar.io/[fullcalendar] javascript library).
+
+
+== Applib
+
+[WARNING]
+====
+TODO: v2 - to write up...
+
+need to reference implement either `Calendarable` or `CalandarEventable` in the applib.
+====
+
+== Usage
+
+To configure the extension:
+
+* include the dependency:
++
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-fullcalendar-wicket-ui</artifactId>
+</dependency>
+----
+
+* update the `AppManifest`:
++
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ IsisModuleExtFullCalendarWicketUi.class, // <.>
+ ...
+})
+public class AppManifest {
+}
+----
+
diff --git a/extensions/vw/fullcalendar/wicket/ui/src/main/java/org/apache/isis/extensions/fullcalendar/wkt/viewer/IsisModuleExtFullCalendarUi.java b/extensions/vw/fullcalendar/wicket/ui/src/main/java/org/apache/isis/extensions/fullcalendar/wkt/viewer/IsisModuleExtFullCalendarWicketUi.java
similarity index 96%
rename from extensions/vw/fullcalendar/wicket/ui/src/main/java/org/apache/isis/extensions/fullcalendar/wkt/viewer/IsisModuleExtFullCalendarUi.java
rename to extensions/vw/fullcalendar/wicket/ui/src/main/java/org/apache/isis/extensions/fullcalendar/wkt/viewer/IsisModuleExtFullCalendarWicketUi.java
index 5b9fd45cff..cb12e5733c 100644
--- a/extensions/vw/fullcalendar/wicket/ui/src/main/java/org/apache/isis/extensions/fullcalendar/wkt/viewer/IsisModuleExtFullCalendarUi.java
+++ b/extensions/vw/fullcalendar/wicket/ui/src/main/java/org/apache/isis/extensions/fullcalendar/wkt/viewer/IsisModuleExtFullCalendarWicketUi.java
@@ -35,5 +35,5 @@ import org.apache.isis.extensions.fullcalendar.wkt.viewer.calendareventable.Cale
CalendarEventableCollectionAsFullCalendarFactory.class,
CalendarableCollectionAsFullCalendarFactory.class
})
-public class IsisModuleExtFullCalendarUi {
+public class IsisModuleExtFullCalendarWicketUi {
}
diff --git a/extensions/vw/gmap3/adoc/modules/gmap3/pages/about.adoc b/extensions/vw/gmap3/adoc/modules/gmap3/pages/about.adoc
index 5e552b7f29..9834f4dc08 100644
--- a/extensions/vw/gmap3/adoc/modules/gmap3/pages/about.adoc
+++ b/extensions/vw/gmap3/adoc/modules/gmap3/pages/about.adoc
@@ -2,5 +2,4 @@
:Notice: 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 ag [...]
-WARNING: TODO
-
+WARNING: TODO: v2 - to write up...
diff --git a/extensions/vw/pdfjs/adoc/modules/pdfjs/pages/about.adoc b/extensions/vw/pdfjs/adoc/modules/pdfjs/pages/about.adoc
index e3a7614ad6..7a2ee4a47d 100644
--- a/extensions/vw/pdfjs/adoc/modules/pdfjs/pages/about.adoc
+++ b/extensions/vw/pdfjs/adoc/modules/pdfjs/pages/about.adoc
@@ -1,5 +1,43 @@
-= pdf.js
+= PDF.js
:Notice: 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 ag [...]
-WARNING: TODO
+The PDF.js module integrates with the xref:vw:ROOT:about.adoc[Wicket Viewer], rendering a `Blob` property containing a PDF using the link:https://mozilla.github.io/pdf.js/[pdf.js] library.
+
+
+== Usage
+
+[WARNING]
+====
+TODO: v2 - to write up...
+
+need to annotate property using `@PdfJsViewer` and implement the `PdfJsViewerAdvisor` SPI.
+====
+
+== Configuration
+
+Add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-pdfjs-wicket-ui</artifactId>
+</dependency>
+----
+
+Also add the following module to your `AppManifest`:
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ IsisModuleExtPdfjsWicketUi.class, // <.>
+ ...
+})
+public class AppManifest {
+}
+----
+
diff --git a/extensions/vw/pdfjs/applib/src/main/java/org/apache/isis/extensions/pdfjs/applib/config/PdfJsConfig.java b/extensions/vw/pdfjs/applib/src/main/java/org/apache/isis/extensions/pdfjs/applib/config/PdfJsConfig.java
index 75d48bf3a5..0736dd360d 100644
--- a/extensions/vw/pdfjs/applib/src/main/java/org/apache/isis/extensions/pdfjs/applib/config/PdfJsConfig.java
+++ b/extensions/vw/pdfjs/applib/src/main/java/org/apache/isis/extensions/pdfjs/applib/config/PdfJsConfig.java
@@ -33,7 +33,7 @@ import lombok.With;
/**
* @since 2.0 {@index}
*/
-@Getter @With @AllArgsConstructor @NoArgsConstructor @Builder
+@Getter @AllArgsConstructor @NoArgsConstructor @Builder
public class PdfJsConfig implements Serializable {
private static final long serialVersionUID = 1L;
@@ -41,15 +41,19 @@ public class PdfJsConfig implements Serializable {
@Builder.Default
private int initialPage = 1;
- @Builder.Default
+ @Builder.Default @With
private Scale initialScale = Scale._1_00;
@Builder.Default
private int initialHeight = 800;
+ @With
private CharSequence documentUrl;
+ @With
private CharSequence workerUrl;
+ @With
private CharSequence cmapsUrl;
+ @With
private CharSequence canvasId;
public PdfJsConfig withInitialPage(int initialPage) {
diff --git a/extensions/vw/sse/adoc/modules/sse/pages/about.adoc b/extensions/vw/sse/adoc/modules/sse/pages/about.adoc
index bac99d4e40..f10bddcd61 100644
--- a/extensions/vw/sse/adoc/modules/sse/pages/about.adoc
+++ b/extensions/vw/sse/adoc/modules/sse/pages/about.adoc
@@ -2,4 +2,45 @@
:Notice: 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 ag [...]
-WARNING: TODO
+The SSE (Server Side Events) module integrates with the xref:vw:ROOT:about.adoc[Wicket Viewer], and provides the ability to dynamically update properties of type xref:valuetypes:markdown:about.adoc[Markdown] and xref:valuetypes:asciidoc:about.adoc[Asciidoc].
+One use case could be to render a progress bar for a long-running action.
+
+
+== Usage
+
+[WARNING]
+====
+TODO: v2 - to write up...
+
+need to annotate property using `@ServerSentEvents` annotation, and provide an implementation of the `SseSource` SPI.
+====
+
+== Configuration
+
+Add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.isis.extensions</groupId>
+ <artifactId>isis-extensions-sse-wicket</artifactId>
+</dependency>
+----
+
+Also add the following module to your `AppManifest`:
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ IsisModuleExtSseWicket.class, // <.>
+ ...
+})
+public class AppManifest {
+}
+----
+
+
+
diff --git a/security/adoc/modules/ROOT/pages/about.adoc b/security/adoc/modules/ROOT/pages/about.adoc
index 0f6fdb462a..e16d5fb5d8 100644
--- a/security/adoc/modules/ROOT/pages/about.adoc
+++ b/security/adoc/modules/ROOT/pages/about.adoc
@@ -30,6 +30,21 @@ include::security:keycloak:partial$module-nav.adoc[]
include::security:spring:partial$module-nav.adoc[]
+In addition to the security SPI implementations, there are a number of security-related extensions:
+
+* The xref:security:spring-oauth2:about.adoc[Spring OAuth2] extension configures the xref:security:spring:about.adoc[Spring authenticator] for OAuth2 stores (eg gmail, facebook)
+* The xref:security:shiro-realm-ldap:about.adoc[LDAP Realm] extension confiures the xref:security:shiro:about.adoc[Shiro authenticator] to use LDAP as a credential source.
+* The xref:security:secman:about.adoc[SecMan extension] provides both an authenticator and an authorizor from domain entities (users, roles and permission entities) using either xref:pjpa:ROOT:about.adoc[JPA] or xref:pjdo:ROOT:about.adoc[JDO].
++
+As these users, roles and permissions are domain objects, they can be administered through Apache Isis itself.
+
+Note that authenticators and authorizor components can be mixed.
+For example, the Keycloak or Spring OAuth2 authenticator can be used with Secman for authorization.
+
+
+The most significant of these is probably xref:security:secman:about.adoc[SecMan], which uses a
+
+
== Permissions
The xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] SPI defines two types of permissions:
@@ -82,11 +97,5 @@ If using the xref:vw::about.adoc[Wicket viewer], then note there will also be an
-== Extensions
-
-In addition to the security SPI implementations, there are a number of security-related extesions.
-
-The most significant of these is probably xref:security:secman:about.adoc[SecMan], which uses a database of users, roles and permission entities (either xref:pjpa:ROOT:about.adoc[JPA] or xref:pjdo:ROOT:about.adoc[JDO]) to manage authorisation.
-As these users, roles and permissions are domain objects, they can be administered through Apache Isis itself.
diff --git a/security/adoc/modules/ROOT/partials/extensions.adoc b/security/adoc/modules/ROOT/partials/extensions.adoc
index 2f953d87fc..4906738fd6 100644
--- a/security/adoc/modules/ROOT/partials/extensions.adoc
+++ b/security/adoc/modules/ROOT/partials/extensions.adoc
@@ -1,6 +1,5 @@
include::security:shiro-realm-ldap:partial$module-nav.adoc[]
include::security:spring-oauth2:partial$module-nav.adoc[]
-include::security:keycloak:partial$module-nav.adoc[]
include::security:secman:partial$module-nav.adoc[]
include::security:audittrail:partial$module-nav.adoc[]
include::security:sessionlog:partial$module-nav.adoc[]
diff --git a/security/bypass/src/main/adoc/modules/bypass/pages/about.adoc b/security/bypass/src/main/adoc/modules/bypass/pages/about.adoc
index d2fb3f77d2..b97c70386e 100644
--- a/security/bypass/src/main/adoc/modules/bypass/pages/about.adoc
+++ b/security/bypass/src/main/adoc/modules/bypass/pages/about.adoc
@@ -1,4 +1,4 @@
-= Bypass
+= Bypass (Authenticator & Authorizor)
:Notice: 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 ag [...]
:page-partial:
diff --git a/security/bypass/src/main/adoc/modules/bypass/partials/module-nav.adoc b/security/bypass/src/main/adoc/modules/bypass/partials/module-nav.adoc
index 335c2faae1..ec59c8f80b 100644
--- a/security/bypass/src/main/adoc/modules/bypass/partials/module-nav.adoc
+++ b/security/bypass/src/main/adoc/modules/bypass/partials/module-nav.adoc
@@ -1,5 +1,5 @@
-* xref:security:bypass:about.adoc[Bypass Implementation]
+* xref:security:bypass:about.adoc[Bypass (Authenticator & Authorizor)]
diff --git a/security/keycloak/src/main/adoc/modules/keycloak/pages/about.adoc b/security/keycloak/src/main/adoc/modules/keycloak/pages/about.adoc
index 9a34eed74b..0902b9602b 100644
--- a/security/keycloak/src/main/adoc/modules/keycloak/pages/about.adoc
+++ b/security/keycloak/src/main/adoc/modules/keycloak/pages/about.adoc
@@ -1,4 +1,4 @@
-= Keycloak Security
+= Keycloak (Authenticator only)
:Notice: 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 ag [...]
:page-partial:
@@ -7,7 +7,7 @@
This guide describes the configuration of the Keycloak implementation of Apache Isis' `Authenticator` API.
It does _not_ however provide any implementation of xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] SPI.
-You will therefore need to configure an alternative implementation, eg the xref:bypass:about.adoc[Bypass] implementation (to disable authorisation checks completely), or use the xref:secman:about.adoc[SecMan] implementation.
+You will therefore need to configure an alternative implementation, eg the xref:bypass:about.adoc[Bypass] implementation (to disable authorisation checks completely), or use the xref:secman:about.adoc[SecMan] implementation (see xref:security:secman:setting-up-with-keycloak.adoc[here for details]).
== Dependency
diff --git a/security/keycloak/src/main/adoc/modules/keycloak/partials/module-nav.adoc b/security/keycloak/src/main/adoc/modules/keycloak/partials/module-nav.adoc
index 12ef87fb94..24e37c0404 100644
--- a/security/keycloak/src/main/adoc/modules/keycloak/partials/module-nav.adoc
+++ b/security/keycloak/src/main/adoc/modules/keycloak/partials/module-nav.adoc
@@ -1,3 +1,3 @@
-** xref:security:keycloak:about.adoc[Keycloak Implementation]
+* xref:security:keycloak:about.adoc[Keycloak (Authenticator only)]
diff --git a/security/shiro/src/main/adoc/modules/shiro/pages/about.adoc b/security/shiro/src/main/adoc/modules/shiro/pages/about.adoc
index ef998cd0ac..8ee648ef79 100644
--- a/security/shiro/src/main/adoc/modules/shiro/pages/about.adoc
+++ b/security/shiro/src/main/adoc/modules/shiro/pages/about.adoc
@@ -1,4 +1,4 @@
-= Shiro Security
+= Shiro (Authenticator & Authorizor)
:Notice: 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 ag [...]
:page-partial:
diff --git a/security/shiro/src/main/adoc/modules/shiro/partials/module-nav.adoc b/security/shiro/src/main/adoc/modules/shiro/partials/module-nav.adoc
index 9e32f290af..0450eefb9a 100644
--- a/security/shiro/src/main/adoc/modules/shiro/partials/module-nav.adoc
+++ b/security/shiro/src/main/adoc/modules/shiro/partials/module-nav.adoc
@@ -1,4 +1,4 @@
-* xref:security:shiro:about.adoc[Shiro Implementation]
+* xref:security:shiro:about.adoc[Shiro (Authenticator & Authorizor)]
diff --git a/security/spring/src/main/adoc/modules/spring/pages/about.adoc b/security/spring/src/main/adoc/modules/spring/pages/about.adoc
index 002d5e686f..34599d7317 100644
--- a/security/spring/src/main/adoc/modules/spring/pages/about.adoc
+++ b/security/spring/src/main/adoc/modules/spring/pages/about.adoc
@@ -1,4 +1,4 @@
-= Spring Security
+= Spring (Authenticator only)
:Notice: 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 ag [...]
:page-partial:
@@ -7,7 +7,7 @@
This guide describes the configuration of the Spring implementation of Apache Isis' xref:refguide:core:index/security/authentication/Authenticator.adoc[Authenticator] SPI.
It does _not_ however provide any implementation of xref:refguide:core:index/security/authorization/Authorizor.adoc[Authorizor] SPI.
-You will therefore need to configure an alternative implementation, eg the xref:bypass:about.adoc[Bypass] implementation (to disable authorisation checks completely), or use the xref:secman:about.adoc[SecMan] implementation.
+You will therefore need to configure an alternative implementation, eg the xref:bypass:about.adoc[Bypass] implementation (to disable authorisation checks completely), or use the xref:secman:about.adoc[SecMan] implementation (see xref:security:secman:setting-up-with-spring-oauth2.adoc[here for details]).
include::docs:mavendeps:partial$setup-and-configure-dependencyManagement.adoc[leveloffset=+1]
diff --git a/security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc b/security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc
index 4a4281606c..21432a8ccb 100644
--- a/security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc
+++ b/security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc
@@ -1,2 +1,2 @@
-* xref:security:spring:about.adoc[Spring Implementation]
+* xref:security:spring:about.adoc[Spring (Authenticator only)]
diff --git a/viewers/wicket/adoc/modules/ROOT/partials/extensions.adoc b/viewers/wicket/adoc/modules/ROOT/partials/extensions.adoc
index f25c4191bc..b6d66d858f 100644
--- a/viewers/wicket/adoc/modules/ROOT/partials/extensions.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/partials/extensions.adoc
@@ -1,5 +1,4 @@
include::vw:exceldownload:partial$module-nav.adoc[]
include::vw:fullcalendar:partial$module-nav.adoc[]
-include::vw:gmap3:partial$module-nav.adoc[]
include::vw:pdfjs:partial$module-nav.adoc[]
include::vw:sse:partial$module-nav.adoc[]