-
Notifications
You must be signed in to change notification settings - Fork 9
Portal
Groovity portal is a core module for constructing custom web portals that have a common
base set of administrative functions and UI styles, along with a consistent navigation scheme.
The core framework offers bootstrapping, management of users, groups, roles and configuration,
and defines mechanisms by which portal pages are discovered and organized.
The value of a portal is in the way it handles cross-cutting concerns such as authentication, access control and configuration, allowing app developers to focus on specific problem domains without having to reinvent solutions to common concerns.
Groovity portal is developed to run on MySQL compatible databases, including H2 and AWS Aurora.
The portal framework requires users to login to perform most activities. By default the framework supports digest authentication against user records in the portal DB, but you can also integrate other authentication solutions.
The People administration tool in Klatch can be used to create local user accounts, update a user's name or nickname, reset their password, or disable a user's access. Successful authentication will provide a user with the "auth" role and unlock access to a number of functions; in order to gain elevated permissions within the portal, a user must also be added to a group that is then assigned additional roles, such as the special "admin" role for managing configuration and role assignments, or a role defined by a specific application within the portal.
When a portal is first launched, it will prompt you to bootstrap it with an initial superuser account; a Superusers group is automatically created and assigned the "admin" role at the root level of the portal, and the bootstrap user account is automatically added to Superusers so it has appropriate access to then set up additional users, groups and roles.
Portal groups are top-level constructs meant to mirror real-world teams in the business; groups are assigned roles that control what capabilities are exposed to its members within the portal. Groups have a notion of members and leaders - leaders are delegated administrative rights for the group, so they can add and remove members. Aside from delegated leadership, anyone with a root level "admin" role can modify any group at all. A member of a group will receive any roles assigned to that group for a given node in the portal hierarchy.
There is no hierarchy to groups themselves - groups may only contain people, and groups are not tied to the portal page hierarchy, unlike roles and configuration which are explicitly bound to nodes within the portal hierarchy.
Roles provide a way for portal apps to define classifications of user groups and to modify, restrict or expand capabilities based on those classifications. By providing a simple structure to define possible roles and then evaluate them at runtime, groovity portal can offer a single consistent tool for then dynamically assigning roles to groups of users that have been defined in the Groups admin tool.
Groovity portal defines 3 roles out of the box with special meaning; portal apps are free to make use of these 3 roles or to mix and match them with custom app-specific roles.
- anon - this role represents all non-authenticated users, and is mutually exlusive with "auth"
- auth - this role represents all authenticated users, and is mutually exclusive with "anon"
- admin - this role represents users who are either portal SuperUsers (if defined at the root level), or if assigned to a lower node represents users with delegated administrative privileges for assigning roles and managing configuration within a subtree of the portal hierarchy. SuperUsers, in addition to being able to manage roles and configuration portal-wide, also gain the right to modify any group in the system, a privilege otherwise reserved for group leaders.
To perform interactive role assignment within groovity-portal, you must have the "admin" role at the root of the portal hierarchy, or within a subfolder of the hierarchy. The scope of your admin role explicitly curtails the scope in which you can manage role assignments. Using the Roles admin tool, you can browse to the desired node in the hierarchy and perform simple clicks to assign or remove roles from groups of users. Users will have to log out of the portal and log back in for role changes to take effect.
By default, a portal page with no explicit roles defined is visible to anyone, whether authenticated or not. Most portal pages should explicitly define the roles that have access; once roles are defined, the page will become invisible and unreachable to users who lack an appropriate role.
The portal framework will automatically add a "roles" collection to the binding that contains all of the defined roles for a given page that apply to the current user.
Here is a sample script that allows access to all authenticated users, and customizes its output for users with a custom "foo" role assigned.
@Field static portal =[
title:"Sample page",
roles:['auth','foo']
];
<~
<g:portal>
Hello everyone
<g:portlet roles="foo">
Hello especially to Foo
</g:portlet>
</g:portal>
~>
In order to appear as a page in the portal site navigation, a grvt script in a portal project must provide a static portal declaration with appropriate metadata.
Minimally, this includes a title:
static portal = [
title:"ABC News"
];
Metadata can also be used to control sort order of pages in the navigation, whether or not children of the current page should be displayed as tabs, and application roles (which the app can use to customize interactions for different categories of users)
static portal = [
title:"ABC News",
tabs:true,
order:2,
roles:['auth','news-all']
];
Pages in a portal are organized hierarchically; by default the portal will follow the hierarchical structure of your source files, but you can choose to be more explicit in how you define paths.
For example, to define a custom portal home page, you can define it as "/index.grvt" in your project groovity sources, and then a simple portal declaration wires it in:
static portal = [
title:"My Portal Home",
roles:["anon","auth"]
];
You can also detach your source structure from the portal hierarchy by explicitly declaring portal paths
static portal = [
path:'/',
title:"My Portal Home",
roles:["anon","auth"]
];
Groovity-portal defines three custom tags that can be used to facilitate creation of portal pages.
The first tag, called portal, creates the page shell and site navigation. A second tag portlet allows easy creation of responsive and role-gated widgets within the page layout, and a third tag portalLinks can be used to automatically generate portal navigation links in the body of a portal page.
static portal=[
path:'/',
title:'Portal Home',
roles:['anon','auth']
]
<~
<g:portal>
<g:portlet title="Hello Authenticated user" roles="auth">
Thanks for logging in
</g:portlet>
<g:portlet title="Login" roles="anon">
<a href="/portal/session/login">Login now</a>
</g:portlet>
<g:portalLinks path="/admin/" title="Admin Tools" />
</g:portal>
~>
Groovity offers a standard mechanism for declaring and dynamically substituting
configuration variables to keep environmental details out of your source code.
The default implementation will override configuration keys with values found in
system properties, but groovity-portal extends this framework to support interactive
configuration with persistence in the portal database.
To perform interactive configuration within the portal, you must be assigned the "admin" role at the root of the portal hierarchy, or within a subfolder of the hierarchy. The scope of your admin role explicitly curtails the scope in which you can make configuration changes. Using the Configuration admin tool, you can browse to the desired node in the hierarchy and use a simple form to override the value of any configuration variable declared in code at or beneath that point in the hierarchy. You can also quickly see what the effective configuration values are, whether they came from hard-coded defaults, system properties or the database. Configuration changes take up to 10 seconds to take effect.
Example: a script that defines and then uses some configuration variables.
static portal =[
title:"Sample page"
]
static conf = [
myAppS3Bucket:"defaultBucket",
myAppS3Folder:"/"
]
def objectListing = new AmazonS3Client().listObjects(conf.myAppS3Bucket,conf.myAppS3Folder)
//...